biolm.seqframe package

Sequence-centric dataframes over Parquet with DuckDB-backed query and enrichment.

Requires pip install 'biolm-sdk[seqframe]' (or biolm-sdk[pipeline]).

See Working with SeqFrame, biolm.seqframe, and SeqFrame Metadata Schema Reference for the Parquet metadata field reference.

SeqFrame — sequence-centric dataframe abstraction for the BioLM SDK.

SeqFrame provides a high-level abstraction over Parquet for representing and operating on collections of biological sequences. It is complementary to biolm.datasets: local datasets are inventory bags (dataset.yaml + files, optional push/pull), while SeqFrame handles querying, enrichment, and conversion. Soft label type: seqframe marks a dataset that opens via Dataset.open_seqframe() / SeqFrame.from_dataset().

Requires optional dependencies:

default

pip install 'biolm-sdk[seqframe]'

Also available when biolm-sdk[pipeline] is installed (same data stack deps).

class biolm.seqframe.SeqFrame(parquet_path: str | Path, ops: Tuple[Op, ...] = (), metadata: SeqFrameMetadata | None = None)

Bases: object

Sequence-centric dataframe abstraction over Parquet + DuckDB.

SeqFrames are immutable: transforming operations return new instances. Query operations are lazy until materialization (collect, write, enrich).

property bio

collect() → DataFrame

property columns: List[str]

classmethod from_csv(path: str | Path, **kwargs) → SeqFrame

classmethod from_dataframe(df: DataFrame, *, molecule_type: str | None = None, path: str | Path | None = None) → SeqFrame

classmethod from_dataset(dataset: Any) → SeqFrame: Open a Dataset as a SeqFrame.

classmethod from_fasta(path: str | Path, **kwargs) → SeqFrame

classmethod from_jsonl(path: str | Path, **kwargs) → SeqFrame

classmethod from_protocol(run_or_path: Any, **kwargs) → SeqFrame

classmethod from_rows(rows: List[Dict[str, Any]], *, sequence_column: str = 'sequence', id_column: str = 'id', molecule_type: str | None = None, path: str | Path | None = None) → SeqFrame

head(n: int = 5) → DataFrame

property io

property lab

merge_columns(df: DataFrame, *, on: str = 'id') → SeqFrame: Join enrichment results back into this SeqFrame by key column.

property models

property protocols

property query

classmethod read(path: str | Path) → SeqFrame

property schema: SeqFrameMetadata

property shape: Tuple[int, int]

to_dataset(dataset_id: str, *, client: Any = None, filename: str = 'sequences.parquet', tags: List[str] | None = None, description: str | None = None, attrs: Dict[str, Any] | None = None, force: bool = False) → Any: Write this SeqFrame into a local Dataset (type: seqframe).

write(path: str | Path) → SeqFrame

class biolm.seqframe.SeqFrameMetadata(sequence_column: str = 'sequence', id_column: str = 'id', molecule_type: str = 'unknown', alphabet: str | None = None, created_by: str = '', extensions: ~typing.List[str] = <factory>, version: str = '0.1')

Bases: object

Biological semantics and column mapping for a SeqFrame.

alphabet: str | None = None

created_by: str = ''

extensions: List[str]

classmethod from_dict(data: Dict[str, Any]) → SeqFrameMetadata

classmethod from_parquet_metadata(metadata: Dict[bytes, bytes]) → SeqFrameMetadata

id_column: str = 'id'

molecule_type: str = 'unknown'

sequence_column: str = 'sequence'

to_dict() → Dict[str, Any]

to_parquet_metadata() → Dict[bytes, bytes]

version: str = '0.1'

biolm.seqframe.core module

SeqFrame core: immutable, lazy sequence-centric dataframe.

class biolm.seqframe.core.SeqFrame(parquet_path: str | Path, ops: Tuple[Op, ...] = (), metadata: SeqFrameMetadata | None = None)

Bases: object

Sequence-centric dataframe abstraction over Parquet + DuckDB.

SeqFrames are immutable: transforming operations return new instances. Query operations are lazy until materialization (collect, write, enrich).

property bio

collect() → DataFrame

property columns: List[str]

classmethod from_csv(path: str | Path, **kwargs) → SeqFrame

classmethod from_dataframe(df: DataFrame, *, molecule_type: str | None = None, path: str | Path | None = None) → SeqFrame

classmethod from_dataset(dataset: Any) → SeqFrame: Open a Dataset as a SeqFrame.

classmethod from_fasta(path: str | Path, **kwargs) → SeqFrame

classmethod from_jsonl(path: str | Path, **kwargs) → SeqFrame

classmethod from_protocol(run_or_path: Any, **kwargs) → SeqFrame

classmethod from_rows(rows: List[Dict[str, Any]], *, sequence_column: str = 'sequence', id_column: str = 'id', molecule_type: str | None = None, path: str | Path | None = None) → SeqFrame

head(n: int = 5) → DataFrame

property io

property lab

merge_columns(df: DataFrame, *, on: str = 'id') → SeqFrame: Join enrichment results back into this SeqFrame by key column.

property models

property protocols

property query

classmethod read(path: str | Path) → SeqFrame

property schema: SeqFrameMetadata

property shape: Tuple[int, int]

to_dataset(dataset_id: str, *, client: Any = None, filename: str = 'sequences.parquet', tags: List[str] | None = None, description: str | None = None, attrs: Dict[str, Any] | None = None, force: bool = False) → Any: Write this SeqFrame into a local Dataset (type: seqframe).

write(path: str | Path) → SeqFrame

biolm.seqframe.dataset_bridge module

Thin Dataset ↔ SeqFrame bridge.

Datasets remain bags of files; SeqFrame is the typed tabular opener when a dataset contains exactly one SeqFrame Parquet (or an explicit attrs.seqframe_path).

biolm.seqframe.dataset_bridge.open_seqframe(dataset: Dataset) → SeqFrame: Open a Dataset as a SeqFrame (requires biolm-sdk[seqframe]).

biolm.seqframe.dataset_bridge.resolve_seqframe_parquet(dataset: Dataset) → Path

Resolve the SeqFrame Parquet path inside a dataset.

Resolution order: 1. attrs["seqframe_path"] (relative to dataset root, or absolute) 2. Exactly one *.parquet file under the dataset

Raises:: DatasetError: If zero or multiple candidates, or the pointed path is missing.

biolm.seqframe.dataset_bridge.seqframe_to_dataset(sf: SeqFrame, dataset_id: str, *, client: 'DatasetClient' | None = None, filename: str = 'sequences.parquet', tags: List[str] | None = None, description: str | None = None, attrs: Dict[str, Any] | None = None, force: bool = False) → Dataset

Materialize a SeqFrame into a local Dataset with type: seqframe.

Creates the dataset under the client’s primary root when missing, writes Parquet under data/, and records attrs.seqframe_path.

biolm.seqframe.metadata module

SeqFrame Parquet metadata schema (version 0.1).

class biolm.seqframe.metadata.SeqFrameMetadata(sequence_column: str = 'sequence', id_column: str = 'id', molecule_type: str = 'unknown', alphabet: str | None = None, created_by: str = '', extensions: ~typing.List[str] = <factory>, version: str = '0.1')

Bases: object

Biological semantics and column mapping for a SeqFrame.

alphabet: str | None = None

created_by: str = ''

extensions: List[str]

classmethod from_dict(data: Dict[str, Any]) → SeqFrameMetadata

classmethod from_parquet_metadata(metadata: Dict[bytes, bytes]) → SeqFrameMetadata

id_column: str = 'id'

molecule_type: str = 'unknown'

sequence_column: str = 'sequence'

to_dict() → Dict[str, Any]

to_parquet_metadata() → Dict[bytes, bytes]

version: str = '0.1'