base_generator

tit.reporting.generators.base_generator

Base report generator for TI-Toolbox.

This module provides the abstract base class for all report generators, with common functionality for BIDS output management, software version collection, and error tracking.

BaseReportGenerator

BaseReportGenerator(project_dir: str | Path, subject_id: str | None = None, session_id: str | None = None, report_type: str = 'general')

Bases: ABC

Abstract base class for all TI-Toolbox report generators.

Provides common functionality including: - BIDS-compliant output path management - Software version collection - Error and warning tracking - Dataset description generation

Initialize the base report generator.

Parameters:

Name	Type	Description	Default
project_dir	str | Path	Path to the project directory	required
subject_id	str | None	BIDS subject ID (without 'sub-' prefix)	None
session_id	str | None	Optional session/run identifier	None
report_type	str	Type of report being generated	'general'

Source code in tit/reporting/generators/base_generator.py

def __init__(
    self,
    project_dir: str | Path,
    subject_id: str | None = None,
    session_id: str | None = None,
    report_type: str = "general",
):
    """
    Initialize the base report generator.

    Args:
        project_dir: Path to the project directory
        subject_id: BIDS subject ID (without 'sub-' prefix)
        session_id: Optional session/run identifier
        report_type: Type of report being generated
    """
    self.project_dir = Path(project_dir)
    self.subject_id = subject_id
    self.session_id = session_id or datetime.now().strftime("%Y%m%d_%H%M%S")
    self.report_type = report_type

    # Initialize report metadata
    self.metadata = ReportMetadata(
        title=self._get_default_title(),
        subject_id=subject_id,
        session_id=session_id,
        report_type=report_type,
        project_dir=str(project_dir),
    )

    # Initialize assembler
    self.assembler = ReportAssembler(metadata=self.metadata)

    # Tracking
    self.errors: list[dict[str, Any]] = []
    self.warnings: list[dict[str, Any]] = []
    self.software_versions: dict[str, str] = {}

    # Collect software versions
    self._collect_software_versions()

add_error

add_error(message: str, context: str | None = None, step: str | None = None) -> None

Add an error to the report.

Parameters:

Name	Type	Description	Default
message	str	Error message	required
context	str | None	Context (e.g., subject ID, montage name)	None
step	str | None	Processing step where error occurred	None

Source code in tit/reporting/generators/base_generator.py

def add_error(
    self,
    message: str,
    context: str | None = None,
    step: str | None = None,
) -> None:
    """
    Add an error to the report.

    Args:
        message: Error message
        context: Context (e.g., subject ID, montage name)
        step: Processing step where error occurred
    """
    self.errors.append(
        {
            "message": message,
            "context": context,
            "step": step,
            "severity": SeverityLevel.ERROR.value,
            "timestamp": datetime.now().isoformat(),
        }
    )

add_warning

add_warning(message: str, context: str | None = None, step: str | None = None) -> None

Add a warning to the report.

Parameters:

Name	Type	Description	Default
message	str	Warning message	required
context	str | None	Context (e.g., subject ID, montage name)	None
step	str | None	Processing step where warning occurred	None

Source code in tit/reporting/generators/base_generator.py

def add_warning(
    self,
    message: str,
    context: str | None = None,
    step: str | None = None,
) -> None:
    """
    Add a warning to the report.

    Args:
        message: Warning message
        context: Context (e.g., subject ID, montage name)
        step: Processing step where warning occurred
    """
    self.warnings.append(
        {
            "message": message,
            "context": context,
            "step": step,
            "severity": SeverityLevel.WARNING.value,
            "timestamp": datetime.now().isoformat(),
        }
    )

get_output_dir

get_output_dir() -> Path

Get the BIDS-compliant output directory for reports.

Returns:

Type	Description
Path	Path to the reports directory

Source code in tit/reporting/generators/base_generator.py

def get_output_dir(self) -> Path:
    """
    Get the BIDS-compliant output directory for reports.

    Returns:
        Path to the reports directory
    """
    base_dir = self.project_dir / REPORTS_BASE_DIR

    if self.subject_id:
        return base_dir / f"sub-{self.subject_id}"
    return base_dir

get_output_path

get_output_path(timestamp: str | None = None) -> Path

Get the full output path for the report file.

Parameters:

Name	Type	Description	Default
timestamp	str | None	Optional timestamp string (uses current time if not provided)	None

Returns:

Type	Description
Path	Full path to the report file

Source code in tit/reporting/generators/base_generator.py

def get_output_path(self, timestamp: str | None = None) -> Path:
    """
    Get the full output path for the report file.

    Args:
        timestamp: Optional timestamp string (uses current time if not provided)

    Returns:
        Full path to the report file
    """
    if timestamp is None:
        timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")

    prefix = self._get_report_prefix()
    filename = f"{prefix}_{timestamp}.html"

    return self.get_output_dir() / filename

generate

generate(output_path: str | Path | None = None) -> Path

Generate the HTML report.

Parameters:

Name	Type	Description	Default
output_path	str | Path | None	Optional custom output path	None

Returns:

Type	Description
Path	Path to the generated report file

Source code in tit/reporting/generators/base_generator.py

def generate(self, output_path: str | Path | None = None) -> Path:
    """
    Generate the HTML report.

    Args:
        output_path: Optional custom output path

    Returns:
        Path to the generated report file
    """
    # Build the report content
    self._build_report()

    # Add standard sections
    self._add_errors_section()
    self._add_methods_section(pipeline_components=[self.report_type])
    self._add_references_section(pipeline_components=[self.report_type])

    # Ensure output directory exists
    self._ensure_output_dir()

    # Create dataset description
    self._create_dataset_description()

    # Determine output path
    if output_path:
        final_path = Path(output_path)
    else:
        final_path = self.get_output_path()

    # Save the report
    self.assembler.save(final_path)

    return final_path