Python API¶
This reference is generated from the exact vibframe-anndata package version installed by the documentation build.
Raw import¶
vibframe_anndata.import_raw ¶
import_raw(source: str | Path | Sequence[str | Path] | None = None, *, config: str | Path | Mapping[str, Any] | PackageConfig | None = None, adapter: VibFrameAdapter | None = None) -> AnnData
Phase 1: ingest VibFrame raw signals into a reusable zero-feature AnnData in memory.
vibframe_anndata.import_raw_to_h5ad ¶
import_raw_to_h5ad(source: str | Path | Sequence[str | Path] | None = None, output: str | Path | None = None, *, config: str | Path | Mapping[str, Any] | PackageConfig | None = None, adapter: VibFrameAdapter | None = None, block_size_mib: int = 32) -> Path
Phase 1 at scale: stream raw VibFrame signals directly to a base .h5ad.
Feature editing¶
vibframe_anndata.add_features ¶
Phase 2: add configured features using only raw data already stored in AnnData.
vibframe_anndata.add_features_to_h5ad ¶
add_features_to_h5ad(source: str | Path, config: str | Path | Mapping[str, Any] | PackageConfig, *, output: str | Path | None = None, block_rows: int = 512) -> Path
Phase 2 at scale: enrich a package-generated H5AD by observation blocks.
output=None updates the source atomically through a temporary file. Supplying output
preserves the input and creates an enriched copy. Raw Awkward sample buffers are read only for
the current observation block.
vibframe_anndata.recalculate_features ¶
recalculate_features(adata: AnnData, config: str | Path | Mapping[str, Any] | PackageConfig) -> AnnData
Recalculate configured logical features with replacement semantics.
vibframe_anndata.recalculate_features_to_h5ad ¶
recalculate_features_to_h5ad(source: str | Path, config: str | Path | Mapping[str, Any] | PackageConfig, *, output: str | Path | None = None, block_rows: int = 512) -> Path
Recalculate configured logical features on disk with bounded raw-data memory.
vibframe_anndata.remove_features ¶
Remove feature variables without changing obs or raw obsm data.
vibframe_anndata.remove_features_from_h5ad ¶
remove_features_from_h5ad(source: str | Path, names: Sequence[str], *, output: str | Path | None = None, block_rows: int = 4096) -> Path
Remove feature variables from a large H5AD without loading its raw payload.
Ground truth and evaluation¶
See Ground truth and evaluation for storage, alignment and resource semantics.
vibframe_anndata.get_snapshot_ground_truth ¶
Read snapshot truth only, without materializing raw waveform/spectrum samples.
vibframe_anndata.get_waveform_ground_truth ¶
get_waveform_ground_truth(data: Any, *, point_id: str | None = None, proc_mode_id: str | None = None) -> pd.DataFrame
Return source fields plus vfta_* binding columns, one row per waveform label.
This is a convenience JSON projection. Use read_evaluation_table for exact Arrow types, original null values and source records outside the selected observations.
vibframe_anndata.list_evaluation_files ¶
List source, relative path, kind, exact size and hash without reading raw buffers.
vibframe_anndata.read_evaluation_file ¶
read_evaluation_file(data: Any, path: str, *, source: str | None = None, verify: bool = True) -> bytes
Read one original sidecar verbatim. Ambiguous multi-source paths are errors.
vibframe_anndata.read_evaluation_json ¶
Decode preserved JSON, including DiagGT documents and scenario configuration.
vibframe_anndata.read_evaluation_table ¶
read_evaluation_table(data: Any, path: str, *, source: str | None = None, columns: list[str] | None = None) -> pa.Table
Decode a preserved Parquet sidecar, retaining its Arrow schema and nulls.
vibframe_anndata.export_evaluation_files ¶
export_evaluation_files(data: Any, destination: str | Path, *, source: str | None = None) -> list[Path]
Recover original files under source-hash subdirectories, without overwriting.
The archive is dataset-wide even when AnnData is sliced; export intentionally retains all originals, not only the aligned annotations of a selected subset.
vibframe_anndata.add_ground_truth_to_h5ad ¶
add_ground_truth_to_h5ad(source: str | Path, vibframe_source: Any, *, config: Any = None, output: str | Path | None = None) -> Path
Add/replace evaluation labels without re-reading or recalculating raw samples.
Existing obs must retain source, machine and snap_t. The identical source set must be supplied to reproduce multi-source labels. A transactional temporary copy requires additional disk space of approximately the original H5AD size. Raw buffers and X/var are copied on disk, never loaded into process memory.
Convenience conversion¶
vibframe_anndata.convert ¶
convert(source: str | Path | Sequence[str | Path] | None = None, *, config: str | Path | Mapping[str, Any] | PackageConfig, adapter: VibFrameAdapter | None = None) -> AnnData
Convenience operation chaining in-memory ingestion and configured feature calculation.
Catalog inspection¶
vibframe_anndata.available_catalog_metrics ¶
Return metric names declared by the persisted VibFrame metric catalog.
vibframe_anndata.audit_metric_catalog ¶
Report supported and explicitly unsupported persisted catalog definitions.
Configuration¶
vibframe_anndata.load_config ¶
Load config from YAML, a mapping, or an already validated object.
vibframe_anndata.PackageConfig
dataclass
¶
Validated representation of config.yaml.
vibframe_anndata.FeatureRequest
dataclass
¶
One requested feature, optional raw-channel selector and algorithm options.
vibframe_anndata.GroundTruthConfig
dataclass
¶
Optional snapshot-level evaluation ground-truth ingestion.
Persistence and validation¶
vibframe_anndata.write_h5ad ¶
Validate and persist a round-trip-safe AnnData without duplicating large raw buffers.
vibframe_anndata.validate_anndata_contract ¶
Raise :class:ContractError if the package-level data contract is violated.
vibframe_anndata.validate_streamed_h5ad ¶
Validate structural invariants without loading multi-GiB Awkward buffers into RAM.
Exceptions¶
vibframe_anndata.VibFrameAnnDataError ¶
Bases: Exception
Base exception for all errors raised deliberately by this package.
vibframe_anndata.ConfigurationError ¶
Bases: VibFrameAnnDataError
Raised when configuration is invalid or internally inconsistent.
vibframe_anndata.ContractError ¶
Bases: VibFrameAnnDataError
Raised when an AnnData object violates the package data contract.
vibframe_anndata.FeatureError ¶
Bases: VibFrameAnnDataError
Raised when a feature cannot be selected, computed or materialized safely.
vibframe_anndata.MissingSignalError ¶
Bases: VibFrameAccessError
Raised when a required raw signal is missing for a snapshot.
vibframe_anndata.SerializationError ¶
Bases: VibFrameAnnDataError
Raised when a .h5ad write operation fails.
vibframe_anndata.VibFrameAccessError ¶
Bases: VibFrameAnnDataError
Raised when a VibFrame source cannot be opened or interpreted.