Python API¶

Most of hypline is the command-line pipeline, but a small Python API is re-exported at the top level for reading and writing hypline's Parquet files directly:

from hypline import (
    read_feature,
    read_feature_metadata,
    read_confound,
    read_confound_metadata,
    save_feature,
    save_confound,
)

The two halves are deliberately asymmetric. Saves are entity-based — you pass bids_root plus BIDS entities (dyad, feat/conf, run, …) and hypline derives the canonical output path for you, so writes always land where the pipeline expects. Features and confounds describe the shared conversation, so they are keyed by dyad, not sub — see Subject vs. dyad. Reads are path-based — you usually already have a file in hand. Both enforce the dataset layout and the file formats; a malformed DataFrame or path raises rather than writing something the CLI can't later consume.

Plugging in a custom feature¶

The CLI generates feat-phonemic, feat-semantic, feat-spectral, and feat-syntactic features. To drive an encoding model on a feature hypline doesn't compute — prosody, anything else you can align to the stimulus — build the DataFrame yourself and save_feature it into the dataset. From then on it is a first-class feature: it sits under features/, carries the right entities, and any downstream step that reads features by name will find it.

A feature DataFrame needs two columns: start_time (seconds from the start of the stimulus) and feature (one equal-width vector per row). Match the start_time convention hypline already uses — see the feature file format.

import polars as pl
from hypline import save_feature

df = pl.DataFrame(
    {
        "start_time": [0.0, 0.48, 0.91],
        "feature": [[0.1, 0.2, 0.3], [0.0, 0.5, 0.1], [0.4, 0.4, 0.2]],
    }
)

path = save_feature(
    df,
    bids_root="data/",
    dyad="101",
    feat="embed",
    task="conv",
    run="1",
)

This writes data/features/dyad-030/ses-1/embed/dyad-030_ses-1_task-conv_run-1_feat-embed.parquet. Pass desc="..." to tag a variant into its own embed-<desc>/ subdirectory, and metadata={...} to stash extra keys in the Parquet footer.

Custom confounds need TR alignment

save_confound is the confound-side parallel, but a confound is regressed out of the BOLD, so its rows must align to the BOLD's TR grid: start_time must begin at 0.0 and step by repetition_time, which you pass explicitly (a single-row table carries no spacing to infer it from). See Segments and metadata for how TR-aligned confounds relate to the run.

Round-tripping¶

Read a feature back into a DataFrame, or peek at its footer metadata without loading the data:

from hypline import read_feature, read_feature_metadata

df = read_feature(path)
meta = read_feature_metadata(path)   # feature_name, feature_dim, hypline_version, …

The reads validate the path and cross-check the footer against the path entities, so a file that round-trips through read_feature is one the pipeline will accept.

Reference¶

Writing¶

hypline.save_feature ¶

save_feature(df: DataFrame, *, bids_root: str | Path, dyad: str, feat: str, desc: str | None = None, metadata: dict[str, Any] | None = None, **entities: str) -> Path

Save a feature DataFrame to its canonical layout location.

Parameters:

Name	Type	Description	Default
`df`	`DataFrame`	Must contain `start_time` (numeric, source-relative seconds) and `feature` (Array or List of equal width per row). The `feature` column is normalized to fixed-width `Array(Float64)` on write; other columns are preserved.	required
`bids_root`	`str \| Path`	Project root; the file lands under `<bids_root>/features/dyad-<dyad>/[ses-<ses>/]<feat>[-<desc>]/`.	required
`dyad`	`str`	Required dyad and feature-kind labels. Features describe the shared conversation, so they are keyed by dyad, not subject.	required
`feat`	`str`	Required dyad and feature-kind labels. Features describe the shared conversation, so they are keyed by dyad, not subject.	required
`desc`	`str \| None`	Optional variant tag landing as a `desc-<desc>` entity, placing the file under a `<feat>-<desc>/` subdirectory. Omit for the canonical (variant-free) feature.	`None`
`metadata`	`dict[str, Any] \| None`	Extra keys merged into the Parquet footer's `hypline` blob. The reserved keys `feature_name`, `feature_dim`, and `hypline_version` are auto-injected and must not be supplied. Keys prefixed with `_` are exempt from cross-file equality checks at encoding time.	`None`
`**entities`	`str`	Additional BIDS entities (`ses`, `task`, `run`, custom descriptors). Entity ordering and validation are handled by `BIDSPath`.	`{}`

Returns:

Type	Description
`Path`	Resolved output path.

Raises:

Type	Description
`ValueError`	If required columns are missing, `feature` widths are ragged, or `metadata` supplies a reserved key.

hypline.save_confound ¶

save_confound(df: DataFrame, *, bids_root: str | Path, dyad: str, conf: str, repetition_time: float, tr_method: str | None, desc: str | None = None, metadata: dict[str, Any] | None = None, **entities: str) -> Path

Save a confound DataFrame to its canonical layout location.

Parameters:

Name	Type	Description	Default
`df`	`DataFrame`	Must contain `start_time` (numeric, beginning at `0.0` with intervals equal to `repetition_time`) and `confound` (Array or List of equal width per row). The `confound` column is normalized to fixed-width `Array(Float64)` on write.	required
`bids_root`	`str \| Path`	Project root; the file lands under `<bids_root>/confounds/dyad-<dyad>/[ses-<ses>/]<conf>[-<desc>]/`.	required
`dyad`	`str`	Required dyad and confound-kind labels. Confounds describe the shared conversation, so they are keyed by dyad, not subject.	required
`conf`	`str`	Required dyad and confound-kind labels. Confounds describe the shared conversation, so they are keyed by dyad, not subject.	required
`repetition_time`	`float`	TR of the target BOLD acquisition, in seconds. Must be passed explicitly: a single-row DataFrame carries no spacing, and inferring TR from row spacing would silently disagree with the BOLD's true TR.	required
`tr_method`	`str \| None`	Free-form label for how TR-aligned rows were produced (downsampling/upsampling method, or a marker for native-TR computation). Pass `None` if not applicable. Recorded verbatim; must be equal across files sharing the same `(conf, desc)` pair for downstream consistency checks to pass.	required
`desc`	`str \| None`	Names which derivation of the kind's source this file holds, landing as a `desc-<desc>` entity under a `<conf>-<desc>/` subdirectory. Omit for the kind's unnamed default derivation.	`None`
`metadata`	`dict[str, Any] \| None`	Extra keys merged into the Parquet footer's `hypline` blob. Reserved keys (`confound_kind`, `confound_variant`, `tr_method`, `repetition_time`, `n_trs`, `confound_dim`, `hypline_version`) are auto-injected and must not be supplied. Keys prefixed with `_` are exempt from cross-file equality checks.	`None`
`**entities`	`str`	Additional BIDS entities (`ses`, `task`, `run`, custom descriptors).	`{}`

Returns:

Type	Description
`Path`	Resolved output path.

Raises:

Type	Description
`ValueError`	If required columns are missing, `start_time` is not TR-aligned, `confound` widths are ragged, or `metadata` supplies a reserved key.

Reading¶

hypline.read_feature ¶

read_feature(path: str | Path) -> pl.DataFrame

Read a feature DataFrame from a hypline-format Parquet file.

Validates that the path carries a feat entity, .parquet extension, and no BIDS suffix; checks the footer's feature_name matches the feat entity; normalizes the feature column to fixed-width Array(Float64).

Parameters:

Name	Type	Description	Default
`path`	`str \| Path`	Path to a hypline feature Parquet file.	required

Returns:

Type	Description
`DataFrame`	The stored feature DataFrame.

Raises:

Type	Description
`ValueError`	If the path is not a valid hypline feature path, the footer lacks a `hypline` metadata blob, or `feature_name` disagrees with the path entity.

hypline.read_confound ¶

read_confound(path: str | Path) -> pl.DataFrame

Read a confound DataFrame from a hypline-format Parquet file.

Validates that the path carries a conf entity, .parquet extension, and no BIDS suffix; checks that the footer's confound_kind and confound_variant match the path's conf and desc entities; normalizes the confound column to fixed-width Array(Float64).

Parameters:

Name	Type	Description	Default
`path`	`str \| Path`	Path to a hypline confound Parquet file.	required

Returns:

Type	Description
`DataFrame`	The stored confound DataFrame.

Raises:

Type	Description
`ValueError`	If the path is not a valid hypline confound path, the footer lacks a `hypline` metadata blob, or `confound_kind`/`confound_variant` disagrees with the path entities.

Metadata¶

hypline.read_feature_metadata ¶

read_feature_metadata(path: str | Path) -> dict[str, Any]

Read footer metadata from a hypline feature file without loading data.

Parameters:

Name	Type	Description	Default
`path`	`str \| Path`	Path to a hypline feature Parquet file.	required

Returns:

Type	Description
`dict`	The `hypline` JSON blob from the Parquet footer, including the auto-injected `feature_name`, `feature_dim`, and `hypline_version` keys alongside any caller-supplied keys.

Raises:

Type	Description
`ValueError`	Same conditions as `read_feature`.

hypline.read_confound_metadata ¶

read_confound_metadata(path: str | Path) -> dict[str, Any]

Read footer metadata from a hypline confound file without loading data.

Parameters:

Name	Type	Description	Default
`path`	`str \| Path`	Path to a hypline confound Parquet file.	required

Returns:

Type	Description
`dict`	The `hypline` JSON blob from the Parquet footer, including the auto-injected `confound_kind`, `confound_variant`, `tr_method`, `repetition_time`, `n_trs`, `confound_dim`, and `hypline_version` keys alongside any caller-supplied keys.

Raises:

Type	Description
`ValueError`	Same conditions as `read_confound`.