smftools.informatics.fastq_export

Write per-barcode FASTQ files of reads directly from the raw ragged store.

Reads sequence and quality straight from the ragged parquet shards (the literal as-sequenced read in query coordinates, not a reference-padded reconstruction), so this needs only the raw spine's obs (with its ragged_shard pointer column) -- no BAM re-parsing or dense materialization.

Functions

write_fastq_manifest(outdir, manifest)	Write a fastq_manifest.csv summarizing per-barcode read counts and paths.
write_fastq_per_barcode(raw_obs, base_dir, ...)	Write one FASTQ per barcode/group from the raw ragged store.

smftools.informatics.fastq_export.write_fastq_per_barcode(raw_obs, base_dir, outdir, *, read_ids=None, group_labels='Barcode', gzip_output=True)

Write one FASTQ per barcode/group from the raw ragged store.

Reads are grouped by their ragged_shard pointer so every shard is read at most once, regardless of how many barcode groups its reads belong to; decoded records then stream to one open file handle per barcode.

Parameters:

• raw_obs (DataFrame) -- The raw spine's obs, indexed by read_id, with a ragged_shard column (see informatics.raw_store.write_raw_store).

• base_dir (str | Path) -- Raw spine's parent directory, used to resolve ragged_shard relative paths.

• outdir (str | Path) -- Directory to write <barcode>.fastq[.gz] into.

• read_ids (set[str] | None (default: None)) -- Read IDs to include (e.g. a QC-passed set). None writes every read in raw_obs.

• group_labels (Series | str (default: 'Barcode')) -- Either a column name in raw_obs, or an externally supplied Series (indexed by read_id) of per-read group/barcode labels -- e.g. sample-sheet-enriched names from a preprocessed AnnData.

• gzip_output (bool (default: True)) -- Whether to gzip-compress the FASTQ output.

Returns:

{barcode: {"path": Path, "n_reads": int}} for every barcode that had at least one read written.

Return type:

dict[str, dict]

Raises:

KeyError -- If raw_obs lacks a ragged_shard column, or group_labels names a missing column.

smftools.informatics.fastq_export.write_fastq_manifest(outdir, manifest)

Write a fastq_manifest.csv summarizing per-barcode read counts and paths.

Return type:

Path