references

tit.reporting.reportlets.references

References reportlet for TI-Toolbox reports.

This module provides the default citations and references used across TI-Toolbox reports. References use stable internal IDs while rendering human-readable citation tags in reports and adjacent citation artifacts.

TIToolboxReferencesReportlet

TIToolboxReferencesReportlet(title: str | None = None, include_defaults: bool = True, pipeline_components: list[str] | None = None, show_empty_warning: bool = False)

Bases: ReferencesReportlet

Specialized references reportlet with TI-Toolbox default citations.

Automatically includes relevant citations based on the pipeline components used.

Initialize the TI-Toolbox references reportlet.

Parameters:

Name	Type	Description	Default
title	str | None	Section title	None
include_defaults	bool	Whether to include default TI-Toolbox refs	True
pipeline_components	list[str] | None	List of components used (to filter refs)	None
show_empty_warning	bool	Render a developer-facing empty-ref warning	False

Source code in tit/reporting/reportlets/references.py

def __init__(
    self,
    title: str | None = None,
    include_defaults: bool = True,
    pipeline_components: list[str] | None = None,
    show_empty_warning: bool = False,
):
    """
    Initialize the TI-Toolbox references reportlet.

    Args:
        title: Section title
        include_defaults: Whether to include default TI-Toolbox refs
        pipeline_components: List of components used (to filter refs)
        show_empty_warning: Render a developer-facing empty-ref warning
    """
    super().__init__(
        title=title or "References", show_empty_warning=show_empty_warning
    )

    self.pipeline_components = pipeline_components or []

    if include_defaults:
        self._add_default_references()

add_default_reference

add_default_reference(key: str) -> bool

Add a default reference by stable key, visible label, or legacy alias.

Parameters:

Name	Type	Description	Default
key	str	The reference key (e.g., 'grossman2017_ti' or 'FreeSurfer')	required

Returns:

Type	Description
bool	True if reference was found and added, False otherwise

Source code in tit/reporting/reportlets/references.py

def add_default_reference(self, key: str) -> bool:
    """
    Add a default reference by stable key, visible label, or legacy alias.

    Args:
        key: The reference key (e.g., 'grossman2017_ti' or 'FreeSurfer')

    Returns:
        True if reference was found and added, False otherwise
    """
    resolved_key = self._resolve_reference_key(key)
    for ref_data in DEFAULT_REFERENCES:
        if ref_data["key"] == resolved_key:
            self.add_reference(
                key=ref_data["key"],
                label=ref_data.get("label"),
                citation=ref_data["citation"],
                doi=ref_data.get("doi"),
                url=ref_data.get("url"),
            )
            return True
    return False

get_default_references

get_default_references() -> list[dict[str, str]]

Get the list of default TI-Toolbox references.

Returns:

Type	Description
list[dict[str, str]]	List of reference dictionaries

Source code in tit/reporting/reportlets/references.py

def get_default_references() -> list[dict[str, str]]:
    """
    Get the list of default TI-Toolbox references.

    Returns:
        List of reference dictionaries
    """
    return [ref.copy() for ref in DEFAULT_REFERENCES]

get_reference_by_key

get_reference_by_key(key: str) -> dict[str, str] | None

Get a specific reference by stable key, visible label, or legacy alias.

Parameters:

Name	Type	Description	Default
key	str	The reference key or alias	required

Returns:

Type	Description
dict[str, str] | None	Reference dictionary or None if not found

Source code in tit/reporting/reportlets/references.py

def get_reference_by_key(key: str) -> dict[str, str] | None:
    """
    Get a specific reference by stable key, visible label, or legacy alias.

    Args:
        key: The reference key or alias

    Returns:
        Reference dictionary or None if not found
    """
    resolved_key = TIToolboxReferencesReportlet._resolve_reference_key(key)
    for ref in DEFAULT_REFERENCES:
        if ref["key"] == resolved_key:
            return ref.copy()
    return None