Display Formatting API

Helpers for rendering sample-sheet enrichment-method strings in figures. The raw method names tcrsift accepts (AIMpos, CTYneg_tetpos) are pipeline-friendly but ugly in plot axes. tcrsift.format translates them to display-friendly forms:

Raw	Pretty
AIMpos	AIM⁺
CTYneg	CTY⁻
AIMpos_CTYneg	AIM⁺CTY⁻
CTYneg_tetpos	tet⁺CTY⁻ (CTY reorder)
AIMpos_CTYneg-2	AIM⁺CTY⁻ (donor suffix dropped)

Applied automatically by tcrsift's built-in plots (method × method overlap heatmap, per-method recovery panels, per-sample scatter titles). Call directly when adding labels to custom plots.

Usage

from tcrsift.format import pretty_method, pretty_samples

pretty_method("AIMpos_CTYneg")   # "AIM⁺CTY⁻"
pretty_method("CTYneg_tetpos")   # "tet⁺CTY⁻"

# Map over a list / Series of names.
pretty_samples(["AIMpos-1", "tetpos-1"])  # ["AIM⁺", "tet⁺"]

format

Display formatters for sample-sheet method names (#77).

The raw enrichment-method strings in tcrsift sample sheets are pipeline-friendly but ugly in figures: AIMpos, CTYneg, AIMpos_CTYneg, tetpos, IFNpos. Built-in plots route every method/sample axis label through :func:pretty_method so figures show the readable AIM⁺, CTY⁻, AIM⁺CTY⁻ forms.

Rules:

• Suffix pos → Unicode superscript ⁺.
• Suffix neg → Unicode superscript ⁻.
• A name combining several markers (joined by _, or an N-way set combination joined by +) is reordered so any baseline marker (default CTY, an exclusion gate in our cohort) always reads last (CTYneg_tetpos → tet⁺CTY⁻). This gives a consistent label no matter which order the markers happened to appear in the data.

Baseline markers default to :data:BASELINE_MARKERS (("CTY",)) but can be overridden globally via :func:set_baseline_markers or per call via the last= argument. An explicit priority= list pins the leading order of non-baseline markers.

Pass-through behavior: any name that doesn't match the rules is returned unchanged. Non-string input is coerced via str().

pretty_method

pretty_method(name: str, *, priority: Sequence[str] | None = None, last: Sequence[str] | None = None) -> str

Format a tcrsift enrichment-method string for display.

Markers joined by _ are reordered so baseline markers (default CTY) read last, for any number of parts (not just two). Override the baseline set with last= (or globally via :func:set_baseline_markers) and pin leading order with priority=.

Examples: >>> pretty_method("AIMpos") 'AIM⁺' >>> pretty_method("CTYneg") 'CTY⁻' >>> pretty_method("AIMpos_CTYneg") 'AIM⁺CTY⁻' >>> pretty_method("CTYneg_tetpos") 'tet⁺CTY⁻' >>> pretty_method("CTYneg_AIMpos_IFNpos") 'AIM⁺IFN⁺CTY⁻'

Source code in tcrsift/format.py

def pretty_method(
    name: str,
    *,
    priority: Sequence[str] | None = None,
    last: Sequence[str] | None = None,
) -> str:
    """Format a tcrsift enrichment-method string for display.

    Markers joined by ``_`` are reordered so baseline markers (default
    ``CTY``) read last, for any number of parts (not just two). Override the
    baseline set with ``last=`` (or globally via :func:`set_baseline_markers`)
    and pin leading order with ``priority=``.

    Examples:
        >>> pretty_method("AIMpos")
        'AIM⁺'
        >>> pretty_method("CTYneg")
        'CTY⁻'
        >>> pretty_method("AIMpos_CTYneg")
        'AIM⁺CTY⁻'
        >>> pretty_method("CTYneg_tetpos")
        'tet⁺CTY⁻'
        >>> pretty_method("CTYneg_AIMpos_IFNpos")
        'AIM⁺IFN⁺CTY⁻'
    """
    if not isinstance(name, str):
        return str(name)
    parts = name.split("_")
    # Reorder on the RAW tokens (baseline detection is independent of the
    # superscript translation), then format each surviving part.
    ordered = order_conditions(parts, priority=priority, last=last)
    return "".join(_format_part(p) for p in ordered)

pretty_methods

pretty_methods(names: Iterable[str]) -> list[str]

Map :func:pretty_method over a list/Series of method names.

Source code in tcrsift/format.py

def pretty_methods(names: Iterable[str]) -> list[str]:
    """Map :func:`pretty_method` over a list/Series of method names."""
    return [pretty_method(str(n)) for n in names]

pretty_sample

pretty_sample(name: str) -> str

Format a sample name like AIMpos_CTYneg-2 as the prettified method (AIM⁺CTY⁻), dropping the trailing -N donor suffix.

Use in plots that label by sample-of-origin in a single-donor context (the donor is named elsewhere in the figure title).

Source code in tcrsift/format.py

def pretty_sample(name: str) -> str:
    """Format a sample name like ``AIMpos_CTYneg-2`` as the prettified
    method (``AIM⁺CTY⁻``), dropping the trailing ``-N`` donor suffix.

    Use in plots that label by sample-of-origin in a single-donor
    context (the donor is named elsewhere in the figure title).
    """
    if not isinstance(name, str):
        return str(name)
    stem = name.rsplit("-", 1)[0] if "-" in name else name
    if not stem:
        return name
    return pretty_method(stem)

pretty_samples

pretty_samples(names: Iterable[str]) -> list[str]

Map :func:pretty_sample over a list/Series of sample names.

Source code in tcrsift/format.py

def pretty_samples(names: Iterable[str]) -> list[str]:
    """Map :func:`pretty_sample` over a list/Series of sample names."""
    return [pretty_sample(str(n)) for n in names]