posthoc.io

Genotype reader

class posthoc.io.genotype_reader.GenotypeData(genotypes, variant_ids, sample_ids)[source]

Bases: object

Container for a genotype matrix and associated variant/sample metadata.

Parameters:
genotypes

Genotype matrix of shape (n_samples, n_variants).

Type:

np.ndarray

variant_ids

DataFrame of variant metadata (e.g. CHROM, POS, ID, REF, ALT), one row per variant.

Type:

pd.DataFrame

sample_ids

Sample identifiers corresponding to the rows of genotypes.

Type:

list of str

genotypes: ndarray
variant_ids: DataFrame
sample_ids: list[str]
property n_samples: int

Number of samples in the genotype matrix.

Returns:

Number of rows in genotypes.

Return type:

int

property n_variants: int

Number of variants in the genotype matrix.

Returns:

Number of columns in genotypes.

Return type:

int

posthoc.io.genotype_reader.read_pgen(pfile_prefix)[source]

Read a PLINK2 .pgen/.pvar/.psam fileset into a GenotypeData container.

Parameters:

pfile_prefix (str or Path) – Path prefix shared by the .pgen, .pvar, and .psam files (i.e. the path without the file extension).

Returns:

Container holding the genotype matrix (samples x variants), variant metadata, and sample identifiers.

Return type:

GenotypeData

Raises:

FileNotFoundError – If any of the expected .pgen, .pvar, or .psam files does not exist at the given prefix.

Phenotype and covariate reader

posthoc.io.pheno_covar_reader.load_pheno(pheno_path, pheno_name=None)[source]

Load a phenotype value for each sample from a PLINK-format phenotype file.

Parameters:

  • pheno_path (str or Path) – Path to the whitespace-delimited phenotype file.

  • pheno_name (str, optional) – Name of the phenotype column to load. If None, the first non-FID/IID column in the file is used.

Returns:

Series of phenotype values indexed by sample IID, cast to float.

Return type:

pd.Series

posthoc.io.pheno_covar_reader.load_covar(covar_path)[source]

Load covariate values for each sample from a PLINK-format covariate file.

Parameters:

covar_path (str or Path) – Path to the whitespace-delimited covariate file.

Returns:

DataFrame of covariate values indexed by sample IID, with all covariate columns (excluding FID and IID) cast to float.

Return type:

pd.DataFrame

posthoc.io.pheno_covar_reader.align_samples(sample_ids, pheno, covar=None)[source]

Align genotype sample order with phenotype and (optionally) covariate data.

Determines the set of samples present in sample_ids that also have non-missing values in pheno and, if provided, covar, then returns a boolean mask and correspondingly ordered phenotype and covariate arrays.

Parameters:

  • sample_ids (list of str) – Sample identifiers in genotype order.

  • pheno (pd.Series) – Phenotype values indexed by sample identifier.

  • covar (pd.DataFrame, optional) – Covariate values indexed by sample identifier. If None, only pheno is used for alignment.

Returns:

  • keep_mask (np.ndarray) – Boolean array of length len(sample_ids) indicating which samples (in original order) are retained.

  • aligned_pheno (np.ndarray) – Phenotype values for the retained samples, in sample_ids order.

  • aligned_covar (np.ndarray or None) – Covariate values for the retained samples, in sample_ids order, or None if covar was not provided.

Raises:

ValueError – If there are no overlapping, non-missing samples across the provided genotype, phenotype, and covariate data.

Return type:

tuple[ndarray, ndarray, ndarray | None]

Writers

posthoc.io.writer.write_glm(variant_ids, importances, p_values, p_corrected, test_name, n_samples, out_path)[source]

Write GLM (generalized linear model) association results to a tab-separated file.

Combines variant metadata with importance scores, permutation p-values, and corrected p-values into a single output table.

Parameters:

  • variant_ids (pd.DataFrame) – DataFrame containing variant metadata with columns CHROM, POS, ID, REF, and ALT. Must have the same number of rows as importances.

  • importances (np.ndarray) – Array of importance/effect-size scores, one per variant.

  • p_values (np.ndarray) – Array of permutation p-values, one per variant.

  • p_corrected (np.ndarray) – Array of multiple-testing-corrected p-values, one per variant.

  • test_name (str) – Name of the statistical test used, written to the TEST column.

  • n_samples (int) – Number of samples used in the analysis, written to the N column.

  • out_path (str or Path) – Destination file path for the tab-separated output.

Returns:

Writes the result directly to out_path.

Return type:

None

Raises:

ValueError – If the length of importances does not match the number of rows in variant_ids.

posthoc.io.writer.write_pal(variant_ids, mu, amas, pal_common_idx, pal_amas_idx, p_values, n_models, out_path)[source]

Write PAL (polygenic adaptation / allele-sharing) results to a tab-separated file.

Combines variant metadata with mu and AMAS statistics, boolean flags indicating membership in common and AMAS-specific PAL sets, and associated p-values.

Parameters:

  • variant_ids (pd.DataFrame) – DataFrame containing variant metadata with columns CHROM, POS, ID, REF, and ALT. Must have the same number of rows as mu.

  • mu (np.ndarray) – Array of mu statistics, one per variant.

  • amas (np.ndarray) – Array of AMAS statistics, one per variant.

  • pal_common_idx (np.ndarray) – Integer indices (into the variant array) of variants belonging to the common PAL set.

  • pal_amas_idx (np.ndarray) – Integer indices (into the variant array) of variants belonging to the AMAS-specific PAL set. Also used to index p_values.

  • p_values (np.ndarray) – P-values corresponding to the variants indexed by pal_amas_idx. Variants not in pal_amas_idx are assigned NaN.

  • n_models (int) – Number of models used in the analysis, written to the N_MODELS column.

  • out_path (str or Path) – Destination file path for the tab-separated output.

Returns:

Writes the result directly to out_path.

Return type:

None

Raises:

ValueError – If the length of mu does not match the number of rows in variant_ids.