utils.py

Utilities shared across the decoding pipelines.

resolve_orientation_col(df, orientation_name=None)

Resolve the orientation column name in a position dataframe.

Position sources name the head-direction column differently: v1 Trodes/DLC position uses "orientation" while legacy common_position uses "head_orientation". A requested orientation_name is honored when present; otherwise the first known orientation column found in df is returned (preferring "orientation").

Parameters:

Name	Type	Description	Default
df	DataFrame	Position dataframe whose columns are inspected.	required
orientation_name	str	Preferred column name to use if present in df, by default None.	None

Returns:

Type	Description
str or None	The resolved orientation column name, or None if neither the requested column nor a known orientation column is present.

Source code in src/spyglass/decoding/utils.py

def resolve_orientation_col(
    df: pd.DataFrame, orientation_name: str | None = None
) -> str | None:
    """Resolve the orientation column name in a position dataframe.

    Position sources name the head-direction column differently: v1
    Trodes/DLC position uses ``"orientation"`` while legacy ``common_position``
    uses ``"head_orientation"``. A requested ``orientation_name`` is honored
    when present; otherwise the first known orientation column found in ``df``
    is returned (preferring ``"orientation"``).

    Parameters
    ----------
    df : pandas.DataFrame
        Position dataframe whose columns are inspected.
    orientation_name : str, optional
        Preferred column name to use if present in ``df``, by default None.

    Returns
    -------
    str or None
        The resolved orientation column name, or ``None`` if neither the
        requested column nor a known orientation column is present.
    """
    cols = df.columns
    candidates = (orientation_name, *ORIENTATION_COLS)
    return next(
        (col for col in candidates if col is not None and col in cols), None
    )