Orientation Driver Attribution

Orientation attribution explains a two-group, multi-stage difference after an upstream trajectory analysis has identified the shared PLS space of interest. Pass the pooled, aligned feature matrix, matching group/stage metadata, and the one fitted PLS estimator to analyze_orientation_attribution.

The analysis orders groups and stages deterministically unless explicit levels are supplied. For every adjacent stage pair it reports each group's raw transition and path length, the unit directional contrast, the same contrast after PLS score projection and inverse transformation, and the signed residual observed - pls_captured. Observed feature values remain in the result; the reconstruction is a parallel, lossy view rather than a replacement.

Two decompositions

Attribution reports two decompositions, and they explain different quantities.

The principal-orientation block decomposes the tested angle estimand: principal-axis divergence, the contrast between the groups' signed leading principal axes. It applies the same functional the statistic is built from (motco.stats.trajectory.principal_orientation) to each group's stage-mean configuration, observed and PLS-reconstructed, so the explanation and the test cannot drift apart.

The per-adjacent-transition blocks describe where along the trajectory the groups' step directions diverge. They are a per-step description, not the tested estimand; the two decompositions coincide only for a two-stage design, where the configuration is rank one and PC1 is the transition direction.

Both appear in the tabular outputs under the transition_id column — the transitions as from->to, the principal block under principal_component_id (default principal), which is validated against the stage-derived identifiers so the two can never collide.

Degeneracy and availability

A principal axis exists for any configuration with variance, but it is only resolvable when one axis dominates. The result reports each contributing configuration's relative eigengap and flags the principal contrast degenerate when any falls below eigengap_threshold (default 0.05). The flagged contrast is still returned: degeneracy is a property of the data, so callers stratify on the flag rather than lose rows.

That is distinct from unavailability. A trajectory whose net displacement from first stage to last is at or below zero_tolerance is closed, and no direction is defined at all — that group's principal orientation is marked unavailable, exactly as a zero-length transition is.

Units and stability

Effects are reported in the input coordinate units, normally pooled standardized units. Positive per-feature scales can be supplied to add original-unit columns. These scales only convert reported effects; they never change PLS geometry.

Bootstrap resampling is independent within every group-by-stage cell and uses the same fitted model and preprocessing contract in every replicate. The result records the seed, requested count, valid count, sign stability, and top-k selection frequency, for the principal-orientation block as well as the transitions. Each replicate's principal axis is signed by that replicate's own net displacement, so resampling noise cannot flip the axis; a replicate whose trajectory closes contributes no contrast and counts as invalid. Bootstrap is available for arithmetic row-derived means; precomputed covariate-adjusted mean tables are accepted with stability marked unavailable.

Labels and interpretation

Feature-to-module or feature-to-pathway labels are optional and must be a complete one-to-one mapping supplied by the caller. Aggregate tables preserve the labels and mark their source as caller-supplied. Aggregation is not a pathway annotation service and does not establish biological causality.

The result contains no p-values or significance decisions. Attribution should be run after the calling workflow has made any global orientation inference decision. It describes associations implied by one frozen shared PLS model; the inverse reconstruction is not unique, and bootstrap stability is conditional on that fitted representation.

Functions

motco.stats.attribution.analyze_orientation_attribution(X, metadata, model, *, group_col='group', stage_col='stage', feature_cols=None, groups=None, stages=None, mean_table=None, precomputed_means=None, original_scales=None, feature_scales=None, feature_groups=None, group_labels=None, label_namespace='module', bootstrap_replicates=0, bootstrap_seed=0, top_k=10, zero_tolerance=1e-12, eigengap_threshold=0.05, principal_component_id='principal', sample_id_col=None)

Attribute two-group trajectory orientation differences.

Reports both decompositions described in the module docstring: the principal-orientation contrast, which decomposes the tested angle estimand and carries a relative-eigengap degeneracy qualifier, and the per-adjacent-transition contrasts, which describe where along the trajectory the group directions diverge. The two coincide only for a two-stage design.

Parameters:

Name	Type	Description	Default
X	DataFrame	Aligned feature matrix in the exact coordinate system consumed by model. Observed values are never overwritten by reconstructions.	required
metadata	DataFrame	Row-aligned metadata containing group_col and stage_col.	required
model	Any	One already fitted pooled PLS estimator exposing transform and inverse_transform. It is reused for all groups and replicates.	required
mean_table	DataFrame | None	Optional complete group-by-stage table. It may have a two-level MultiIndex or explicit group/stage columns. When supplied, bootstrap resampling is unavailable because row-level sampling semantics are not defined for adjusted means.	None
precomputed_means	DataFrame | None	Optional complete group-by-stage table. It may have a two-level MultiIndex or explicit group/stage columns. When supplied, bootstrap resampling is unavailable because row-level sampling semantics are not defined for adjusted means.	None
original_scales	Sequence[float] | Series | Mapping[str, float] | None	Optional positive per-feature scale in canonical feature order. The aliases are accepted for readability at call sites; supplying both is an error.	None
feature_scales	Sequence[float] | Series | Mapping[str, float] | None	Optional positive per-feature scale in canonical feature order. The aliases are accepted for readability at call sites; supplying both is an error.	None
feature_groups	Mapping[str, str] | Series | DataFrame | None	Optional one-to-one caller-supplied feature-to-label mapping. The aliases are accepted for readability at call sites.	None
group_labels	Mapping[str, str] | Series | DataFrame | None	Optional one-to-one caller-supplied feature-to-label mapping. The aliases are accepted for readability at call sites.	None
eigengap_threshold	float	Relative-eigengap level at or above which a stage-mean configuration is treated as having a well-separated principal axis. A contributing configuration below it flags the principal-orientation contrast as degenerate; the contrast is still returned, so callers stratify rather than lose rows. The default (0.05) separates the audit's resolvable replicates from its near-isotropic independent-baseline draws.	0.05
principal_component_id	str	Reserved identifier carrying the principal-orientation component in the tabular outputs' transition_id column. It is validated against the stage-derived transition ids so the two can never collide.	'principal'

Returns:

Type	Description
OrientationAttributionResult	Frozen typed records and DataFrame views for means, transitions, the principal-orientation block, feature effects, aggregates, and bootstrap stability.

Source code in src/motco/stats/attribution.py

def analyze_orientation_attribution(
    X: pd.DataFrame,
    metadata: pd.DataFrame,
    model: Any,
    *,
    group_col: str = "group",
    stage_col: str = "stage",
    feature_cols: Sequence[str] | None = None,
    groups: Sequence[str] | None = None,
    stages: Sequence[str] | None = None,
    mean_table: pd.DataFrame | None = None,
    precomputed_means: pd.DataFrame | None = None,
    original_scales: Sequence[float] | pd.Series | Mapping[str, float] | None = None,
    feature_scales: Sequence[float] | pd.Series | Mapping[str, float] | None = None,
    feature_groups: Mapping[str, str] | pd.Series | pd.DataFrame | None = None,
    group_labels: Mapping[str, str] | pd.Series | pd.DataFrame | None = None,
    label_namespace: str = "module",
    bootstrap_replicates: int = 0,
    bootstrap_seed: int | None = 0,
    top_k: int = 10,
    zero_tolerance: float = 1e-12,
    eigengap_threshold: float = 0.05,
    principal_component_id: str = "principal",
    sample_id_col: str | None = None,
) -> OrientationAttributionResult:
    """Attribute two-group trajectory orientation differences.

    Reports both decompositions described in the module docstring: the
    principal-orientation contrast, which decomposes the tested ``angle``
    estimand and carries a relative-eigengap degeneracy qualifier, and the
    per-adjacent-transition contrasts, which describe where along the trajectory
    the group directions diverge. The two coincide only for a two-stage design.

    Parameters
    ----------
    X:
        Aligned feature matrix in the exact coordinate system consumed by
        ``model``. Observed values are never overwritten by reconstructions.
    metadata:
        Row-aligned metadata containing ``group_col`` and ``stage_col``.
    model:
        One already fitted pooled PLS estimator exposing ``transform`` and
        ``inverse_transform``. It is reused for all groups and replicates.
    mean_table, precomputed_means:
        Optional complete group-by-stage table. It may have a two-level
        MultiIndex or explicit group/stage columns. When supplied, bootstrap
        resampling is unavailable because row-level sampling semantics are not
        defined for adjusted means.
    original_scales, feature_scales:
        Optional positive per-feature scale in canonical feature order. The
        aliases are accepted for readability at call sites; supplying both is
        an error.
    feature_groups, group_labels:
        Optional one-to-one caller-supplied feature-to-label mapping. The
        aliases are accepted for readability at call sites.
    eigengap_threshold:
        Relative-eigengap level at or above which a stage-mean configuration is
        treated as having a well-separated principal axis. A contributing
        configuration below it flags the principal-orientation contrast as
        degenerate; the contrast is still returned, so callers stratify rather
        than lose rows. The default (0.05) separates the audit's resolvable
        replicates from its near-isotropic independent-baseline draws.
    principal_component_id:
        Reserved identifier carrying the principal-orientation component in the
        tabular outputs' ``transition_id`` column. It is validated against the
        stage-derived transition ids so the two can never collide.

    Returns
    -------
    OrientationAttributionResult
        Frozen typed records and DataFrame views for means, transitions, the
        principal-orientation block, feature effects, aggregates, and bootstrap
        stability.
    """
    if mean_table is not None and precomputed_means is not None:
        raise AttributionError("Provide only one of mean_table and precomputed_means.")
    if original_scales is not None and feature_scales is not None:
        raise AttributionError("Provide only one of original_scales and feature_scales.")
    if feature_groups is not None and group_labels is not None:
        raise AttributionError("Provide only one of feature_groups and group_labels.")
    if not isinstance(label_namespace, str) or not label_namespace.strip():
        raise AttributionError("label_namespace must be a non-empty string.")
    if precomputed_means is not None:
        mean_table = precomputed_means
    if feature_scales is not None:
        original_scales = feature_scales
    if group_labels is not None:
        feature_groups = group_labels

    feature_frame, metadata_frame, feature_names = _validate_inputs(
        X,
        metadata,
        model,
        group_col,
        stage_col,
        feature_cols,
        sample_id_col,
    )
    ordered_groups = cast(
        tuple[str, str], _ordered_levels(metadata_frame[group_col], groups, 2, "groups")
    )
    ordered_stages = _ordered_levels(metadata_frame[stage_col], stages, 2, "stages")
    _validate_cells(metadata_frame, group_col, stage_col, ordered_groups, ordered_stages)
    scale_values = _validate_scales(original_scales, feature_names)
    label_values = _validate_feature_groups(feature_groups, feature_names)

    if mean_table is None:
        means_array = _arithmetic_means(
            feature_frame,
            metadata_frame,
            group_col,
            stage_col,
            ordered_groups,
            ordered_stages,
        )
        mean_source = "arithmetic"
    else:
        means_array = _precomputed_mean_array(
            mean_table,
            feature_names,
            ordered_groups,
            ordered_stages,
            group_col,
            stage_col,
        )
        mean_source = "precomputed"
        if bootstrap_replicates:
            raise AttributionError(
                "bootstrap_replicates must be zero when mean_table contains precomputed means; "
                "row-level bootstrap semantics are unavailable."
            )

    _validate_bootstrap_settings(bootstrap_replicates, top_k, zero_tolerance)
    _validate_principal_settings(eigengap_threshold, principal_component_id, ordered_stages)
    reconstructed_array = _reconstruct_means(means_array, model, feature_names)
    transitions = _build_transitions(
        means_array,
        reconstructed_array,
        ordered_groups,
        ordered_stages,
        zero_tolerance,
    )
    principal = _build_principal_orientation(
        means_array,
        reconstructed_array,
        ordered_groups,
        ordered_stages,
        zero_tolerance,
        eigengap_threshold,
        principal_component_id,
    )
    model_components = _model_components(model)
    config = AttributionConfig(
        group_column=group_col,
        stage_column=stage_col,
        feature_names=feature_names,
        groups=ordered_groups,
        stages=ordered_stages,
        mean_source=mean_source,
        input_units="standardized_input",
        original_units_available=scale_values is not None,
        zero_tolerance=float(zero_tolerance),
        bootstrap_replicates=int(bootstrap_replicates),
        bootstrap_seed=bootstrap_seed,
        top_k=int(top_k),
        model_components=model_components,
        label_namespace=label_namespace if label_values is not None else None,
        label_source="caller-supplied" if label_values is not None else None,
        eigengap_threshold=float(eigengap_threshold),
        principal_component_id=principal_component_id,
    )

    bootstrap_records = _bootstrap(
        feature_frame,
        metadata_frame,
        group_col,
        stage_col,
        ordered_groups,
        ordered_stages,
        model,
        feature_names,
        scale_values,
        bootstrap_replicates,
        bootstrap_seed,
        top_k,
        zero_tolerance,
        principal_component_id,
    )
    bootstrap_lookup = {
        (record.transition_id, record.component): record for record in bootstrap_records
    }
    feature_effects, feature_records = _feature_effect_table(
        transitions,
        principal,
        feature_names,
        scale_values,
        bootstrap_lookup,
        label_values,
        label_namespace,
        bootstrap_replicates,
    )
    aggregate_effects, aggregate_records = _aggregate_effect_table(
        feature_effects,
        feature_names,
        label_values,
        label_namespace,
        bootstrap_replicates,
    )
    transition_summaries, transition_vectors = _transition_tables(
        transitions,
        ordered_groups,
        feature_names,
    )
    principal_summaries, principal_vectors = _principal_tables(
        principal,
        ordered_groups,
        feature_names,
    )
    bootstrap_table = _bootstrap_table(bootstrap_records, feature_names)
    means_table = _means_table(means_array, ordered_groups, ordered_stages, feature_names)
    reconstructed_table = _means_table(
        reconstructed_array, ordered_groups, ordered_stages, feature_names
    )
    interpretation = InterpretationMetadata(
        statement="Attribution describes associations implied by one fitted shared PLS representation.",
        causal_boundary="Feature, module, and pathway effects are not causal claims.",
        significance_boundary=(
            "No p-values or significance decisions are produced; external orientation inference remains the caller's "
            "responsibility."
        ),
        reconstruction_boundary=(
            "PLS-captured effects are a lossy inverse-transform view and are not a unique inverse of measured features."
        ),
        bootstrap_boundary=(
            "Bootstrap stability is conditional on the fitted preprocessing contract and frozen PLS model."
        ),
        label_source="caller-supplied" if label_values is not None else None,
        decomposition_boundary=(
            f"The '{principal_component_id}' component decomposes the tested angle estimand — principal-axis "
            "divergence between the groups' signed leading principal axes — while per-adjacent-transition "
            "contrasts describe where along the trajectory the group directions diverge; the two coincide only "
            "for two-stage designs. A degenerate principal contrast is reported with its flag and MUST NOT be "
            "read as a well-defined orientation."
        ),
    )
    return OrientationAttributionResult(
        config=config,
        means=means_table,
        reconstructed_means=reconstructed_table,
        transitions=tuple(transitions),
        principal_orientation=principal,
        feature_effects=feature_effects,
        transition_summaries=transition_summaries,
        transition_vectors=transition_vectors,
        principal_summaries=principal_summaries,
        principal_vectors=principal_vectors,
        aggregate_effects=aggregate_effects,
        bootstrap_summaries=bootstrap_table,
        interpretation=interpretation,
        feature_records=tuple(feature_records),
        aggregate_records=tuple(aggregate_records),
        bootstrap_records=tuple(bootstrap_records),
    )

motco.stats.attribution.attribution_frames(result)

Return all findings-ready tables for result.

Source code in src/motco/stats/attribution.py

def attribution_frames(result: OrientationAttributionResult) -> dict[str, pd.DataFrame]:
    """Return all findings-ready tables for ``result``."""

    configuration = pd.DataFrame(
        [
            ("group_column", result.config.group_column),
            ("stage_column", result.config.stage_column),
            ("feature_names", list(result.config.feature_names)),
            ("groups", list(result.config.groups)),
            ("stages", list(result.config.stages)),
            ("mean_source", result.config.mean_source),
            ("input_units", result.config.input_units),
            ("original_units_available", result.config.original_units_available),
            ("zero_tolerance", result.config.zero_tolerance),
            ("bootstrap_replicates", result.config.bootstrap_replicates),
            ("bootstrap_seed", result.config.bootstrap_seed),
            ("top_k", result.config.top_k),
            ("model_components", result.config.model_components),
            ("label_namespace", result.config.label_namespace),
            ("label_source", result.config.label_source),
            ("eigengap_threshold", result.config.eigengap_threshold),
            ("principal_component_id", result.config.principal_component_id),
        ],
        columns=["setting", "value"],
    )
    interpretation = pd.DataFrame(
        [
            ("statement", result.interpretation.statement),
            ("causal_boundary", result.interpretation.causal_boundary),
            ("significance_boundary", result.interpretation.significance_boundary),
            ("reconstruction_boundary", result.interpretation.reconstruction_boundary),
            ("bootstrap_boundary", result.interpretation.bootstrap_boundary),
            ("label_source", result.interpretation.label_source),
            ("decomposition_boundary", result.interpretation.decomposition_boundary),
        ],
        columns=["field", "value"],
    )
    return {
        "means": result.means.copy(),
        "reconstructed_means": result.reconstructed_means.copy(),
        "feature_effects": result.feature_effects.copy(),
        "transition_summaries": result.transition_summaries.copy(),
        "transition_vectors": result.transition_vectors.copy(),
        "principal_orientation": result.principal_summaries.copy(),
        "principal_orientation_vectors": result.principal_vectors.copy(),
        "aggregate_effects": result.aggregate_effects.copy(),
        "bootstrap_summaries": result.bootstrap_summaries.copy(),
        "configuration": configuration,
        "interpretation": interpretation,
    }

motco.stats.attribution.write_attribution_outputs(result, output_dir)

Write attribution tables as CSV files and return their paths.

Source code in src/motco/stats/attribution.py

def write_attribution_outputs(
    result: OrientationAttributionResult,
    output_dir: str | Path,
) -> dict[str, Path]:
    """Write attribution tables as CSV files and return their paths."""

    directory = Path(output_dir)
    directory.mkdir(parents=True, exist_ok=True)
    paths: dict[str, Path] = {}
    for name, frame in attribution_frames(result).items():
        path = directory / f"{name}.csv"
        frame.to_csv(path, index=False)
        paths[name] = path
    return paths