Reading¤

Yield consecutive variant blocks from this dataset.

Each yielded block has at most size variants and follows the same return contract as genoio.Dataset.read. Blocks are fixed-width retained-variant chunks ordered by source variant order after any filtering. BGEN dosage blocks with a concrete region filter use a same-path .bgen.bgi index when present. Haplotype blocks follow the same source-encoded representation rules as genoio.Dataset.read.

Arguments:

• size: maximum number of variants per yielded block.
• read_options: forwarded to genoio.Dataset.read.

Returns:

Iterator yielding matrices or matrix/metadata tuples.

Yield one read result per requested region filter.

Each yielded item is (region, result), where region is the original object from regions and result follows the same return contract as genoio.Dataset.read. Concrete VCF/BCF and BGEN region filters use the same indexed pushdown paths as normal reads when an index is present. Haplotype region reads follow the same source-encoded representation rules as genoio.Dataset.read.

Arguments:

• regions: iterable of region filter expressions.
• read_options: forwarded to genoio.Dataset.read, except variants, which is supplied by each region.

Returns:

Iterator yielding (region, matrix_or_tuple) pairs.

Read a genotype or haplotype matrix from this dataset.

Dense reads return a NumPy array with shape (samples, variants). Sparse reads return SciPy CSC by default or CSR when sparse="csr". Set return_samples or return_variants to return Polars metadata frames with the matrix.

Arguments:

• kind: Matrix row layout. "geno" returns one row per retained sample, with diploid genotype values in each cell. "haplo" returns one row per source haplotype, so diploid samples contribute two rows. Haplotype reads require phased records in the source.
• dosage: Value source for each matrix cell. "hardcall" reads allele counts from called genotypes. "dosage" reads expected allele counts from dosage/probability fields when the source format supports them. genoio does not convert dosages into hard calls.
• sparse: Output storage. False returns a dense NumPy array. True and "csc" return a SciPy CSC matrix; "csr" returns a SciPy CSR matrix. Sparse reads require missing="raise" because this release does not store sparse missing-value masks.
• variants: Variants to keep. Pass a genoio filter expression to filter by metadata or genotype predicates, or pass an iterable of variant IDs to keep matching IDs. None keeps all variants. Retained columns stay in source order, not request order.
• samples: Sample IDs to keep. Pass a list, tuple, or set of sample IDs. None keeps all samples. Retained rows stay in source order; duplicate requested IDs are rejected.
• missing: Missing-call policy. None uses "nan" for dense reads and "raise" for sparse reads. "nan" stores missing calls as np.nan, "raise" fails if retained calls are missing, and "impute" fills missing calls with the retained variant mean.
• dtype: NumPy dtype for returned matrix values. Missing policies that write np.nan or imputed means require a floating dtype.
• return_samples: When True, return a sample metadata frame with the matrix. Haplotype reads include columns that map haplotype rows back to source samples.
• return_variants: When True, return a variant metadata frame for the retained matrix columns.

Returns:

Matrix alone, or a tuple containing the matrix and requested metadata frames.

Raises:

• genoio.InvalidOptionError: if read options are invalid.
• genoio.UnsupportedRepresentation: if the requested representation is unavailable for the source.
• genoio.InvalidSourceError: if the source cannot be decoded.
• genoio.MissingDataError: if retained missing calls conflict with the requested missing-data policy.
• genoio.InternalError: if the compiled backend reports an internal invariant failure.

Return sample metadata as a Polars DataFrame.

Columns are fid, iid, father, mother, sex, and phenotype. Rows are ordered as they appear in the source. Haplotype reads that return sample metadata add source_sample_index and haplotype_index columns to map haplotype rows back to source samples.

Returns:

Polars DataFrame with source sample metadata in source order.

Return variant metadata as a Polars DataFrame.

Columns are chrom, pos, id, a0, and a1. Rows are ordered as they appear in the source; variant frames returned by matrix reads are ordered to match matrix columns after filtering. The a1 allele is the allele counted by returned genotype values.

The stats argument is reserved for future metadata-stat controls. Passing it currently raises genoio.InvalidOptionError.

Arguments:

• stats: reserved; must be None.

Returns:

Polars DataFrame with source variant metadata in source order.