API Reference

Client

class dnaerys.DnaerysClient[source]

Bases: object

Client for the Dnaerys genomic data service.

Parameters:

  • target (str, default: 'db.dnaerys.org:443') – Server address in host:port format.

  • tls (bool, default: True) – If True (default), create a secure TLS channel.

  • credentials (ChannelCredentials | None, default: None) – Custom TLS credentials. If None and tls is True, default SSL credentials are used.

  • options (dict[str, Any] | None, default: None) – gRPC channel options as {key: value} pairs.

  • default_timeout (float | None, default: None) – Default per-call timeout in seconds. None means no timeout.

  • assembly (RefAssembly | str, default: <RefAssembly.GRCh38: 2>) – Default reference assembly for all queries. Can be overridden per-method.

  • Usage:: –

    with DnaerysClient(“db.dnaerys.org:443”) as client:
    for v in client.select_variants(region=Region(“chr1”, 1000, 5000)):

    print(v)

close()[source]

Close the underlying gRPC channel.

Return type:

None

__init__(target='db.dnaerys.org:443', *, tls=True, credentials=None, options=None, default_timeout=None, assembly=RefAssembly.GRCh38)[source]
Parameters:
Return type:

None

health(*, timeout=None)[source]

Check server health status.

Return type:

HealthResult

Parameters:

timeout (float | None)

cluster_nodes(*, timeout=None)[source]

Return cluster node status.

Return type:

ClusterNodesResult

Parameters:

timeout (float | None)

dataset_info(*, return_sample_names=False, timeout=None)[source]

Return dataset information (cohorts, PRS catalog, assembly, etc.).

Return type:

DatasetInfo

Parameters:

  • return_sample_names (bool)

  • timeout (float | None)

select_variants(*, region=None, regions=None, bracket=None, samples=None, hom=True, het=True, annotations=None, variant_min_length=None, variant_max_length=None, limit=None, assembly=None, timeout=None)[source]

Select variants matching the given criteria (streaming).

limit is a hard global cap on the total number of variants returned. Because the cluster caps each ring’s response, the library fetches results in internal skip-batched requests, so limit may safely exceed the server’s per-ring cap and is still honoured exactly.

When limit is None a single request is issued and each ring returns up to its server-side cap, so for very large regions the result may be truncated — pass a limit or use paginate_variants() to retrieve everything.

Return type:

VariantStream

Parameters:
paginate_variants(*, page_size, buffer_size=None, region=None, regions=None, bracket=None, samples=None, hom=True, het=True, annotations=None, variant_min_length=None, variant_max_length=None, assembly=None, timeout=None)[source]

Create a paginated query for variants.

buffer_size is the per-ring window requested each server round-trip. It defaults to (and is capped at) the server’s per-ring limit so every ring is walked without gaps; a larger value is clamped down.

Return type:

PaginatedQuery

Parameters:
select_variants_with_stats(*, region=None, regions=None, samples=None, hom=True, het=True, annotations=None, variant_min_length=None, variant_max_length=None, limit=None, assembly=None, timeout=None)[source]

Select variants with per-variant statistics (streaming).

Accepts a single region or a list of regions, with or without samples. A single region without samples is automatically routed to the multi-region RPC transparently.

limit is a hard global cap enforced via internal skip- batched requests, so it may exceed the server per-ring cap. With limit=None a single request is issued and each ring returns up to its cap (possibly truncated for very large regions).

Return type:

VariantWithStatsStream

Parameters:
paginate_variants_with_stats(*, page_size, buffer_size=None, region=None, regions=None, samples=None, hom=True, het=True, annotations=None, variant_min_length=None, variant_max_length=None, assembly=None, timeout=None)[source]

Create a paginated query for variants with statistics.

buffer_size defaults to (and is capped at) the server’s per-ring limit so every ring is walked without gaps.

Return type:

PaginatedQuery

Parameters:
count_variants(*, region=None, regions=None, bracket=None, samples=None, hom=True, het=True, annotations=None, variant_min_length=None, variant_max_length=None, assembly=None, timeout=None)[source]

Count variants matching the given criteria.

Return type:

CountResult

Parameters:
select_samples(*, region=None, regions=None, hom=True, het=True, annotations=None, variant_min_length=None, variant_max_length=None, skip=None, limit=None, assembly=None, timeout=None)[source]

Select samples with variants in the given region(s).

Return type:

SamplesResult

Parameters:
count_samples(*, region=None, regions=None, hom=True, het=True, annotations=None, variant_min_length=None, variant_max_length=None, assembly=None, timeout=None)[source]

Count samples with variants in the given region(s).

Return type:

CountResult

Parameters:
select_samples_hom_ref(*, chr, position, skip=None, limit=None, assembly=None, timeout=None)[source]

Select samples with homozygous reference calls at a position.

Return type:

SamplesResult

Parameters:
count_samples_hom_ref(*, chr, position, assembly=None, timeout=None)[source]

Count samples with homozygous reference calls at a position.

Return type:

CountResult

Parameters:
select_de_novo(*, parent1, parent2, proband, region, annotations=None, variant_min_length=None, variant_max_length=None, limit=None, assembly=None, timeout=None)[source]

Select de novo candidate variants in a proband (streaming).

limit is a hard global cap enforced via internal skip-batched requests, so it may exceed the server per-ring cap.

Return type:

VariantStream

Parameters:
paginate_de_novo(*, page_size, buffer_size=None, parent1, parent2, proband, region, annotations=None, variant_min_length=None, variant_max_length=None, assembly=None, timeout=None)[source]

Create a paginated query for de novo candidate variants.

buffer_size defaults to (and is capped at) the server per-ring limit.

Return type:

PaginatedQuery

Parameters:
select_het_dominant(*, affected_parent, unaffected_parent, affected_child, region, annotations=None, variant_min_length=None, variant_max_length=None, limit=None, assembly=None, timeout=None)[source]

Select heterozygous dominant candidate variants (streaming).

limit is a hard global cap enforced via internal skip-batched requests, so it may exceed the server per-ring cap.

Return type:

VariantStream

Parameters:
paginate_het_dominant(*, page_size, buffer_size=None, affected_parent, unaffected_parent, affected_child, region, annotations=None, variant_min_length=None, variant_max_length=None, assembly=None, timeout=None)[source]

Create a paginated query for heterozygous dominant candidate variants.

buffer_size defaults to (and is capped at) the server per-ring limit.

Return type:

PaginatedQuery

Parameters:
select_hom_recessive(*, unaffected_parent1, unaffected_parent2, affected_child, region, annotations=None, variant_min_length=None, variant_max_length=None, limit=None, assembly=None, timeout=None)[source]

Select homozygous recessive candidate variants (streaming).

limit is a hard global cap enforced via internal skip-batched requests, so it may exceed the server per-ring cap.

Return type:

VariantStream

Parameters:
paginate_hom_recessive(*, page_size, buffer_size=None, unaffected_parent1, unaffected_parent2, affected_child, region, annotations=None, variant_min_length=None, variant_max_length=None, assembly=None, timeout=None)[source]

Create a paginated query for homozygous recessive candidate variants.

buffer_size defaults to (and is capped at) the server per-ring limit.

Return type:

PaginatedQuery

Parameters:
top_hwe(*, n, sequential=False, timeout=None)[source]

Return top N variants by Hardy-Weinberg equilibrium p-value.

Return type:

TopHweResult

Parameters:
top_chi2(*, n, samples, sequential=False, timeout=None)[source]

Return top N variants by chi-squared test p-value.

Return type:

TopChi2Result

Parameters:
prs(*, prs_name, cohort_name=None, samples=None, dominant=False, recessive=False, timeout=None)[source]

Calculate polygenic risk scores.

Return type:

PrsResult

Parameters:
sex_mismatch_check(*, cohort_name=None, samples=None, aaf_threshold=None, female_threshold=0.7, male_threshold=0.7, include_par=False, sequential=False, timeout=None)[source]

Run sex mismatch check based on X-chromosome F-statistics.

Return type:

SexMismatchResult

Parameters:

  • cohort_name (str | None)

  • samples (list[str] | None)

  • aaf_threshold (float | None)

  • female_threshold (float)

  • male_threshold (float)

  • include_par (bool)

  • sequential (bool)

  • timeout (float | None)

fstat_x(*, cohort_name=None, samples=None, aaf_threshold=None, include_par=False, sequential=False, timeout=None)[source]

Calculate F-statistics for X chromosome.

Return type:

FstatXResult

Parameters:

  • cohort_name (str | None)

  • samples (list[str] | None)

  • aaf_threshold (float | None)

  • include_par (bool)

  • sequential (bool)

  • timeout (float | None)

kinship(*, cohort_name=None, samples=None, degree=None, threshold=None, sequential=False, timeout=None)[source]

Calculate kinship coefficients for all sample pairs.

Return type:

KinshipResult

Parameters:
kinship_duo(*, sample1, sample2, sequential=False, timeout=None)[source]

Calculate kinship coefficient between two samples.

Return type:

KinshipResult

Parameters:
kinship_trio(*, sample1, sample2, sample3, degree=None, threshold=None, sequential=False, timeout=None)[source]

Calculate kinship coefficients for a trio.

Return type:

KinshipResult

Parameters:
sample_kinship(*, sample_vcf, cohort_name=None, degree=None, threshold=None, sequential=False, timeout=None)[source]

Find relatives of a sample (provided as VCF) in the dataset.

Return type:

SampleKinshipResult

Parameters:

Input types

class dnaerys.Region[source]

Bases: object

A genomic region defined by chromosome, start, and end coordinates.

Parameters:

  • chr (Chromosome) – Chromosome identifier. Strings like "chr1", "1", "X", "chrMT" are resolved to Chromosome enum members in __post_init__.

  • start (int) – 1-based inclusive start position. Must be >= 1.

  • end (int) – 1-based inclusive end position. Must be >= start. For a single-nucleotide variant (SNV), start == end.

  • ref (str | None, default: None) – Reference allele. Optional; None means no filtering by reference allele.

  • alt (str | None, default: None) – Alternative allele. Optional; None means no filtering by alternative allele.

Raises:

ValueError – If start < 1, or end < start, or chr cannot be resolved.

chr: Chromosome
start: int
end: int
ref: str | None
alt: str | None
__init__(chr, start, end, ref=None, alt=None)
Parameters:
Return type:

None

class dnaerys.Bracket[source]

Bases: object

A bracket query region for structural variant searches.

Defines a pair of coordinate ranges: one for variant start positions (start_min–start_max) and one for end positions (end_min–end_max). This follows the GA4GH Beacon Bracket Query specification.

See https://docs.genomebeacons.org/variant-queries/#beacon-bracket-queries

Parameters:

  • chr (Chromosome) – Chromosome identifier, resolved in __post_init__.

  • start_min (int) – 1-based inclusive minimum start position. Must be >= 1.

  • start_max (int) – 1-based inclusive maximum start position. Must be >= start_min.

  • end_min (int) – 1-based inclusive minimum end position. Must be >= 1.

  • end_max (int) – 1-based inclusive maximum end position. Must be >= end_min.

  • ref (str | None, default: None) – Reference allele. Optional.

  • alt (str | None, default: None) – Alternative allele. Optional.

Raises:

ValueError – If any position < 1, start_min > start_max, or end_min > end_max.

chr: Chromosome
start_min: int
start_max: int
end_min: int
end_max: int
ref: str | None
alt: str | None
__init__(chr, start_min, start_max, end_min, end_max, ref=None, alt=None)
Parameters:
Return type:

None

class dnaerys.AnnotationFilter[source]

Bases: object

Filter criteria for variant annotation-based queries.

All enum sequence fields accept either enum members or strings (resolved case-insensitively at construction). Fields within a repeated enum are OR’d together; different fields are AND’d.

For float bound pairs (e.g. af_lt / af_gt), the server applies field > gt AND field < lt. A value of None means “no filter” (the proto’s 0.0 default, which means “unset”, is mapped to None for clarity). Setting both with gt >= lt defines an empty range; a warning is emitted but the filter is still constructed.

Parameters:

  • variant_type (tuple[VariantType, ...], default: ()) – Sequence Ontology variant class terms to include (OR’d).

  • feature_type (tuple[FeatureType, ...], default: ()) – VEP feature types to include (OR’d).

  • bio_type (tuple[BioType, ...], default: ()) – VEP biotypes to include (OR’d).

  • consequence (tuple[Consequence, ...], default: ()) – Sequence Ontology consequence terms to include (OR’d).

  • impact (tuple[Impact, ...], default: ()) – VEP impact levels to include (OR’d).

  • clin_significance (tuple[ClinSignificance, ...], default: ()) – ClinVar clinical significance categories to include (OR’d). Proto field name: clinsgn.

  • af_lt (float | None, default: None) – Include variants with dataset allele frequency < this value.

  • af_gt (float | None, default: None) – Include variants with dataset allele frequency > this value.

  • gnomad_exomes_af_lt (float | None, default: None) – Include variants with gnomAD exomes AF < this value. Note: unannotated variants / those absent from gnomAD (gnomAD exomes AF = 0) are included.

  • gnomad_exomes_af_gt (float | None, default: None) – Include variants with gnomAD exomes AF > this value.

  • gnomad_genomes_af_lt (float | None, default: None) – Include variants with gnomAD genomes AF < this value. Note: unannotated variants / those absent from gnomAD (gnomAD genomes AF = 0) are included.

  • gnomad_genomes_af_gt (float | None, default: None) – Include variants with gnomAD genomes AF > this value.

  • sift (tuple[SIFT, ...], default: ()) – SIFT prediction terms to include (OR’d).

  • polyphen (tuple[PolyPhen, ...], default: ()) – PolyPhen prediction terms to include (OR’d).

  • cadd_raw_lt (float | None, default: None) – Include variants with CADD raw score < this value.

  • cadd_raw_gt (float | None, default: None) – Include variants with CADD raw score > this value.

  • cadd_phred_lt (float | None, default: None) – Include variants with CADD phred score < this value.

  • cadd_phred_gt (float | None, default: None) – Include variants with CADD phred score > this value.

  • am_score_lt (float | None, default: None) – Include variants with AlphaMissense score < this value. Mutually exclusive with am_class — setting both raises ValueError because the server silently ignores am_class when score bounds are present.

  • am_score_gt (float | None, default: None) – Include variants with AlphaMissense score > this value. Mutually exclusive with am_class.

  • am_class (tuple[AlphaMissense, ...], default: ()) – AlphaMissense pathogenicity classes to include (OR’d). Only effective when neither am_score_lt nor am_score_gt are set.

  • biallelic_only (bool, default: False) – If True, include only biallelic sites (exclude multiallelic). Mutually exclusive with multiallelic_only.

  • multiallelic_only (bool, default: False) – If True, include only multiallelic sites (exclude biallelic). Mutually exclusive with biallelic_only.

  • exclude_males (bool, default: False) – If True, exclude male samples from selection. Mutually exclusive with exclude_females.

  • exclude_females (bool, default: False) – If True, exclude female samples from selection. Mutually exclusive with exclude_males.

Raises:

ValueError – If biallelic_only and multiallelic_only are both True. If am_score_lt or am_score_gt is set together with a non-empty am_class. If exclude_males and exclude_females are both True. If an enum string value cannot be resolved.

variant_type: tuple[VariantType, ...]
feature_type: tuple[FeatureType, ...]
bio_type: tuple[BioType, ...]
consequence: tuple[Consequence, ...]
impact: tuple[Impact, ...]
clin_significance: tuple[ClinSignificance, ...]
af_lt: float | None
af_gt: float | None
gnomad_exomes_af_lt: float | None
gnomad_exomes_af_gt: float | None
gnomad_genomes_af_lt: float | None
gnomad_genomes_af_gt: float | None
sift: tuple[SIFT, ...]
polyphen: tuple[PolyPhen, ...]
cadd_raw_lt: float | None
cadd_raw_gt: float | None
cadd_phred_lt: float | None
cadd_phred_gt: float | None
am_score_lt: float | None
am_score_gt: float | None
am_class: tuple[AlphaMissense, ...]
biallelic_only: bool
multiallelic_only: bool
exclude_males: bool
exclude_females: bool
__init__(variant_type=(), feature_type=(), bio_type=(), consequence=(), impact=(), clin_significance=(), af_lt=None, af_gt=None, gnomad_exomes_af_lt=None, gnomad_exomes_af_gt=None, gnomad_genomes_af_lt=None, gnomad_genomes_af_gt=None, sift=(), polyphen=(), cadd_raw_lt=None, cadd_raw_gt=None, cadd_phred_lt=None, cadd_phred_gt=None, am_score_lt=None, am_score_gt=None, am_class=(), biallelic_only=False, multiallelic_only=False, exclude_males=False, exclude_females=False)
Parameters:
Return type:

None

Core result types

class dnaerys.Variant[source]

Bases: object

A genomic variant with population-level statistics.

All coordinates are 1-based, inclusive. For SNVs, start == end.

Annotation float fields (gnomad_exomes_af, gnomad_genomes_af, cadd_raw, cadd_phred, am_score) use 0.0 as a sentinel meaning “not annotated” — this mirrors the proto convention where the default float value (0.0) indicates absence of annotation data.

Parameters:

  • chr (Chromosome) – Chromosome this variant is on.

  • start (int) – 1-based inclusive start position.

  • end (int) – 1-based inclusive end position.

  • ref (str) – Reference allele (uppercase).

  • alt (str) – Alternative allele (uppercase).

  • af (float) – Dataset allele frequency.

  • ac (float) – Dataset allele count. float because heterozygous loci on sex chromosomes outside PAR in males are counted as 0.5.

  • an (int) – Dataset allele number (excludes samples with missing genotypes).

  • hom_samples (int) – Number of all samples with a homozygous genotype.

  • het_samples (int) – Number of all samples with a heterozygous genotype.

  • mis_samples (int) – Number of all samples with a missing (no-call) genotype.

  • hom_samples_fx (int) – Number of female samples with a homozygous genotype in the X chromosome only; 0 outside X.

  • het_samples_fx (int) – Number of female samples with a heterozygous genotype in the X chromosome only; 0 outside X.

  • mis_samples_fx (int) – Number of female samples with a missing (no-call) genotype in the X chromosome only; 0 outside X.

  • hom_samples_mxy (int) – Number of male samples with a homozygous genotype in the X & Y chromosomes only; 0 outside X and Y.

  • het_samples_mxy (int) – Number of male samples with a heterozygous genotype in the X & Y chromosomes only; 0 outside X and Y.

  • mis_samples_mxy (int) – Number of male samples with a missing (no-call) genotype in the X & Y chromosomes only; 0 outside X and Y.

  • gnomad_exomes_af (float) – gnomAD exomes allele frequency. 0.0 = not annotated. Proto field: gnomADe.

  • gnomad_genomes_af (float) – gnomAD genomes allele frequency. 0.0 = not annotated. Proto field: gnomADg.

  • cadd_raw (float) – CADD raw score. 0.0 = not annotated.

  • cadd_phred (float) – CADD phred-scaled score. 0.0 = not annotated.

  • am_score (float) – AlphaMissense pathogenicity score. 0.0 = not annotated.

  • amino_acids (str) – Amino acid substitution (HGVSp or VEP Amino_acids notation).

  • biallelic (bool) – Whether the variant was biallelic in the input VCFs.

chr: Chromosome
start: int
end: int
ref: str
alt: str
af: float
ac: float
an: int
hom_samples: int
het_samples: int
mis_samples: int
hom_samples_fx: int
het_samples_fx: int
mis_samples_fx: int
hom_samples_mxy: int
het_samples_mxy: int
mis_samples_mxy: int
gnomad_exomes_af: float
gnomad_genomes_af: float
cadd_raw: float
cadd_phred: float
am_score: float
amino_acids: str
biallelic: bool
__init__(chr, start, end, ref, alt, af, ac, an, hom_samples, het_samples, mis_samples, hom_samples_fx, het_samples_fx, mis_samples_fx, hom_samples_mxy, het_samples_mxy, mis_samples_mxy, gnomad_exomes_af, gnomad_genomes_af, cadd_raw, cadd_phred, am_score, amino_acids, biallelic)
Parameters:
Return type:

None

class dnaerys.VariantWithStats[source]

Bases: object

A variant with additional virtual-cohort counters and population statistics.

All Variant fields are flattened (not nested) for ergonomic access. The virtual cohort counters (vaf, vac, etc.) reflect the subset of samples specified in the query. The population statistics (phwe, pchi2, etc.) are computed over the full dataset population.

The odds_ratio field corresponds to the proto field or, which is a Python reserved keyword and cannot be used as an attribute name.

All annotation float sentinels and coordinate conventions are identical to Variant.

Parameters:

  • chr–biallelic (see Variant)

  • vaf (float) – Virtual cohort allele frequency.

  • vac (float) – Virtual cohort allele count.

  • van (int) – Virtual cohort allele number.

  • v_hom_samples (int) – Number of samples with a homozygous genotype within the virtual cohort.

  • v_het_samples (int) – Number of samples with a heterozygous genotype within the virtual cohort.

  • v_hom_samples_fx (int) – Number of female samples with a homozygous genotype in the X chromosome only within the virtual cohort; 0 outside X.

  • v_het_samples_fx (int) – Number of female samples with a heterozygous genotype in the X chromosome only within the virtual cohort; 0 outside X.

  • v_hom_samples_mxy (int) – Number of male samples with a homozygous genotype in the X & Y chromosomes only within the virtual cohort; 0 outside X and Y.

  • v_het_samples_mxy (int) – Number of male samples with a heterozygous genotype in the X & Y chromosomes only within the virtual cohort; 0 outside X and Y.

  • phwe (float) – P-value for Hardy-Weinberg equilibrium chi-squared test.

  • pchi2 (float) – P-value for Pearson’s chi-squared test (cases vs. controls).

  • odds_ratio (float) – Odds ratio from the chi-squared test. Proto field: or.

  • ibc (float) – F-statistic (inbreeding coefficient).

chr: Chromosome
start: int
end: int
ref: str
alt: str
af: float
ac: float
an: int
hom_samples: int
het_samples: int
mis_samples: int
hom_samples_fx: int
het_samples_fx: int
mis_samples_fx: int
hom_samples_mxy: int
het_samples_mxy: int
mis_samples_mxy: int
gnomad_exomes_af: float
gnomad_genomes_af: float
cadd_raw: float
cadd_phred: float
am_score: float
amino_acids: str
biallelic: bool
vaf: float
vac: float
van: int
v_hom_samples: int
v_het_samples: int
v_hom_samples_fx: int
v_het_samples_fx: int
v_hom_samples_mxy: int
v_het_samples_mxy: int
phwe: float
pchi2: float
odds_ratio: float
ibc: float
__init__(chr, start, end, ref, alt, af, ac, an, hom_samples, het_samples, mis_samples, hom_samples_fx, het_samples_fx, mis_samples_fx, hom_samples_mxy, het_samples_mxy, mis_samples_mxy, gnomad_exomes_af, gnomad_genomes_af, cadd_raw, cadd_phred, am_score, amino_acids, biallelic, vaf, vac, van, v_hom_samples, v_het_samples, v_hom_samples_fx, v_het_samples_fx, v_hom_samples_mxy, v_het_samples_mxy, phwe, pchi2, odds_ratio, ibc)
Parameters:
Return type:

None

Stream wrappers

class dnaerys.VariantStream[source]

Bases: object

Synchronous iterator wrapper yielding Variant objects from a gRPC stream.

Wraps an Iterable[pb2.AllelesResponse] and yields individual Variant dataclass instances. The underlying gRPC stream delivers variants in chunks (AllelesResponse messages with repeated Variant); this class flattens them into a single-item-at-a-time iterator.

Metadata (timing, cluster health) is accumulated across all consumed chunks and available via the .metadata property at any time.

Warning

to_list() and to_dataframe() are terminal operations. After either is called, the internal iterator is exhausted. Materialising genome-wide results may require substantial memory. Consider iterating with the generator for large result sets.

__init__(proto_iterator, *, limit=None)[source]

Initialise a VariantStream from a gRPC streaming iterator.

Parameters:

  • proto_iterator (Iterable[AllelesResponse]) – The raw gRPC streaming iterator.

  • limit (int | None, default: None) – Maximum number of variants to yield. None means no cap.

Return type:

None

property metadata: ResponseMetadata

Accumulated metadata from all consumed chunks.

Before any chunks have been consumed, returns defaults (elapsed_ms=0, incomplete_cluster=False, etc.). The node_id field is a comma-separated sorted string of all node IDs seen; empty string if no chunks consumed.

to_list()[source]

Exhaust the stream and return all remaining variants as a list.

This is a terminal operation. After calling to_list(), further iteration yields nothing.

Materialising genome-wide results may require substantial memory. Consider iterating with the generator for large result sets.

Return type:

list[Variant]

to_dataframe()[source]

Exhaust the stream and return a pandas DataFrame.

This is a terminal operation. Requires pandas to be installed.

Returns:

DataFrame with 24 columns matching the Variant fields. The chr column contains human-readable strings ("chr1", "chrX", "chrMT"), not enum int values.

Return type:

object

Raises:

ImportError – If pandas is not installed.

class dnaerys.VariantWithStatsStream[source]

Bases: object

Synchronous iterator wrapper yielding VariantWithStats from a gRPC stream.

Same semantics as VariantStream but wraps Iterable[pb2.AllelesWithStatsResponse] and yields VariantWithStats dataclass instances with 37 fields (24 variant + 13 statistics).

Metadata accumulation, warning emission, and terminal operation rules are identical to VariantStream.

__init__(proto_iterator, *, limit=None)[source]

Initialise a VariantWithStatsStream from a gRPC streaming iterator.

Parameters:

  • proto_iterator (Iterable[AllelesWithStatsResponse]) – The raw gRPC streaming iterator.

  • limit (int | None, default: None) – Maximum number of variants to yield. None means no cap.

Return type:

None

property metadata: ResponseMetadata

Accumulated metadata from all consumed chunks.

Same accumulation rules as VariantStream.metadata.

to_list()[source]

Exhaust the stream and return all remaining variants as a list.

This is a terminal operation.

Materialising genome-wide results may require substantial memory. Consider iterating with the generator for large result sets.

Return type:

list[VariantWithStats]

to_dataframe()[source]

Exhaust the stream and return a pandas DataFrame.

This is a terminal operation. Requires pandas to be installed.

Returns:

DataFrame with 37 columns matching the VariantWithStats fields. The chr column contains human-readable strings.

Return type:

object

Raises:

ImportError – If pandas is not installed.

Pagination

class dnaerys.Page[source]

Bases: object

A single page of variant results from a paginated query.

Parameters:

  • variants (tuple[Variant, ...]) – The variants in this page.

  • page_number (int) – 1-based page number.

variants: tuple[Variant, ...]
page_number: int
__init__(variants, page_number)
Parameters:
Return type:

None

class dnaerys.PaginatedQuery[source]

Bases: object

Iterator that serves fixed-size pages of variants from a Dnaerys query.

Manages an internal collections.deque buffer, refilling it transparently from the server via the provided fetch callable. Callers see clean, fixed-size pages without needing to know about skip/limit or cluster topology.

Parameters:

  • fetch (Callable[[int, int], VariantStream]) – A callable that takes (skip, limit) and returns a VariantStream.

  • page_size (int) – Number of variants per page (last page may be shorter).

  • buffer_size (int, default: 5000) – Per-ring window requested per server round-trip. Must be <= the server per-ring cap so every owner ring is walked without gaps; it may be smaller than page_size (a page is assembled from as many round-trips as needed).

Raises:

ValueError – If page_size < 1 or buffer_size < 1.

__init__(fetch, *, page_size, buffer_size=5000)[source]
Parameters:
Return type:

None

property page_size: int

Number of variants per page.

property buffer_size: int

Number of variants requested per server round-trip.

property total_fetched: int

Total number of variants served across all pages so far.

property has_more: bool

Whether more pages may be available.

Returns True if the buffer contains variants or the server has not yet been confirmed exhausted. Returns False only after iteration is complete and the buffer is empty.

Note

Before the first next_page() call, this property returns True even if the query matches zero variants — no server call has been made yet, so exhaustion is unknown. The first next_page() call triggers the first server round-trip; if it returns no variants, StopIteration is raised immediately and has_more becomes False.

property metadata: ResponseMetadata

Accumulated metadata from all server round-trips so far.

next_page()[source]

Return the next page of variants.

Raises:

StopIteration – When no more variants are available.

Return type:

Page

Response types

class dnaerys.ResponseMetadata[source]

Bases: object

Metadata from a Dnaerys server response.

Carried by most response types to provide timing, node identification, and cluster health information.

Parameters:

  • elapsed_ms (int) – Server-side wall-clock time from request receipt to response, in milliseconds.

  • elapsed_db_ms (int) – Database engine processing time, in milliseconds.

  • node_id (str) – Identifier of the cluster node that served the response.

  • incomplete_cluster (bool) – True if the cluster had unreachable nodes at response time.

  • affected (bool) – True if unreachable nodes could have affected the completeness of this response. Only meaningful when incomplete_cluster is also True.

elapsed_ms: int
elapsed_db_ms: int
node_id: str
incomplete_cluster: bool
affected: bool
__init__(elapsed_ms, elapsed_db_ms, node_id, incomplete_cluster, affected)
Parameters:

  • elapsed_ms (int)

  • elapsed_db_ms (int)

  • node_id (str)

  • incomplete_cluster (bool)

  • affected (bool)

Return type:

None

class dnaerys.CountResult[source]

Bases: object

Result from a variant or sample count query.

The result is a dataclass, not an int. Arithmetic requires accessing .count explicitly: result.count + 10, not result + 10.

Parameters:

  • count (int) – The number of matching variants or samples.

  • metadata (ResponseMetadata) – Server response metadata (timing, cluster health).

count: int
metadata: ResponseMetadata
__init__(count, metadata)
Parameters:
Return type:

None

class dnaerys.SamplesResult[source]

Bases: object

Result from a sample selection query.

Parameters:

  • samples (tuple[str, ...]) – Unique sample names matching the query criteria.

  • metadata (ResponseMetadata) – Server response metadata.

samples: tuple[str, ...]
metadata: ResponseMetadata
__init__(samples, metadata)
Parameters:
Return type:

None

class dnaerys.HealthResult[source]

Bases: object

Result from the Health RPC.

Parameters:

status (str) – Server health status string (e.g. "ok").

status: str
__init__(status)
Parameters:

status (str)

Return type:

None

class dnaerys.ClusterNodesResult[source]

Bases: object

Result from the ClusterNodes RPC.

Parameters:

  • active_nodes (tuple[str, ...]) – Names/IDs of nodes in the “up” state.

  • inactive_nodes (tuple[str, ...]) – Names/IDs of nodes in any state other than “up”.

  • total_nodes (int) – Total number of nodes in the cluster at the time of the request.

  • elapsed_ms (int) – Server-side wall-clock time in milliseconds.

active_nodes: tuple[str, ...]
inactive_nodes: tuple[str, ...]
total_nodes: int
elapsed_ms: int
__init__(active_nodes, inactive_nodes, total_nodes, elapsed_ms)
Parameters:
Return type:

None

class dnaerys.DatasetInfo[source]

Bases: object

Comprehensive dataset metadata from the DatasetInfo RPC.

Parameters:

  • cohorts (tuple[Cohort, ...]) – Cohorts within the dataset.

  • samples_total (int) – Total number of samples in the dataset.

  • females_total (int) – Total number of female samples.

  • males_total (int) – Total number of male samples.

  • variants_total (int) – Total number of variants in the dataset.

  • assembly (RefAssembly) – Reference genome assembly.

  • rto (bool) – Whether the dataset is in runtime-optimized mode.

  • prs (tuple[PrsInfo, ...]) – Available PRS catalogs.

  • timestamp (str) – Dataset creation timestamp.

  • data_format (int) – Data format version.

  • notes (str) – Freeform notes.

  • rings_total (int) – Total number of data rings.

  • elapsed_ms (int) – Server-side wall-clock time in milliseconds.

  • node_id (str) – Node that served the response.

  • max_variants_per_ring (int, default: 0) – Hard cap on the number of variants each individual ring returns per request. A query may request fewer, but never more, from any one ring. 0 if the server did not advertise a cap (older servers); the client then falls back to a built-in default. Used internally to size pagination buffers and strong-limit batches so results are complete.

cohorts: tuple[Cohort, ...]
samples_total: int
females_total: int
males_total: int
variants_total: int
assembly: RefAssembly
rto: bool
prs: tuple[PrsInfo, ...]
timestamp: str
data_format: int
notes: str
rings_total: int
elapsed_ms: int
node_id: str
max_variants_per_ring: int
__init__(cohorts, samples_total, females_total, males_total, variants_total, assembly, rto, prs, timestamp, data_format, notes, rings_total, elapsed_ms, node_id, max_variants_per_ring=0)
Parameters:
Return type:

None

class dnaerys.Cohort[source]

Bases: object

A sample cohort within a dataset.

Parameters:

  • cohort_name (str) – Name of the cohort.

  • samples_count (int) – Total number of samples in the cohort.

  • female_count (int) – Number of female samples.

  • male_count (int) – Number of male samples.

  • female_sample_names (tuple[str, ...]) – Female sample names. Proto field: female_samples_names.

  • male_sample_names (tuple[str, ...]) – Male sample names. Proto field: male_samples_names.

  • synthetic (bool) – Whether the cohort is synthetic.

cohort_name: str
samples_count: int
female_count: int
male_count: int
female_sample_names: tuple[str, ...]
male_sample_names: tuple[str, ...]
synthetic: bool
__init__(cohort_name, samples_count, female_count, male_count, female_sample_names, male_sample_names, synthetic)
Parameters:

  • cohort_name (str)

  • samples_count (int)

  • female_count (int)

  • male_count (int)

  • female_sample_names (tuple[str, ...])

  • male_sample_names (tuple[str, ...])

  • synthetic (bool)

Return type:

None

class dnaerys.PrsInfo[source]

Bases: object

Polygenic risk score catalog entry.

Parameters:

  • name (str) – PRS name as loaded into the dataset.

  • description (str) – PRS description. Proto field: desc.

  • cardinality (int) – Number of effect alleles in the PRS.

name: str
description: str
cardinality: int
__init__(name, description, cardinality)
Parameters:

  • name (str)

  • description (str)

  • cardinality (int)

Return type:

None

class dnaerys.PrsResult[source]

Bases: object

Result from the PRS RPC.

Parameters:

  • prs_name (str) – PRS name.

  • sample_scores (tuple[SampleScore, ...]) – Per-sample PRS scores.

  • dominant (bool) – Whether the dominant scoring mode was used.

  • recessive (bool) – Whether the recessive scoring mode was used.

  • prs_cardinality (int) – Total number of effect variants in the PRS.

  • metadata (ResponseMetadata) – Server response metadata.

prs_name: str
sample_scores: tuple[SampleScore, ...]
dominant: bool
recessive: bool
prs_cardinality: int
metadata: ResponseMetadata
__init__(prs_name, sample_scores, dominant, recessive, prs_cardinality, metadata)
Parameters:
Return type:

None

class dnaerys.SampleScore[source]

Bases: object

Per-sample polygenic risk score from the PRS RPC.

Parameters:

  • sample (str) – Sample name.

  • scores_sum (float) – Sum of PRS scores (equivalent to Plink --score sum).

  • hethom_cardinality (int) – Number of effect alleles with het or hom genotypes contributing to scores_sum.

  • ref_cardinality (int) – Number of effect alleles with reference genotypes. Negative in runtime-optimized mode.

  • mis_cardinality (int) – Number of effect alleles with missing genotypes.

  • imputed_sum (float) – Sum of imputed scores for missing alleles.

sample: str
scores_sum: float
hethom_cardinality: int
ref_cardinality: int
mis_cardinality: int
imputed_sum: float
__init__(sample, scores_sum, hethom_cardinality, ref_cardinality, mis_cardinality, imputed_sum)
Parameters:

  • sample (str)

  • scores_sum (float)

  • hethom_cardinality (int)

  • ref_cardinality (int)

  • mis_cardinality (int)

  • imputed_sum (float)

Return type:

None

class dnaerys.SexMismatchResult[source]

Bases: object

Result from the SexMismatchCheck RPC.

Parameters:
mismatch_males: tuple[SampleStat, ...]
mismatch_females: tuple[SampleStat, ...]
metadata: ResponseMetadata
__init__(mismatch_males, mismatch_females, metadata)
Parameters:
Return type:

None

class dnaerys.SampleStat[source]

Bases: object

Per-sample sex statistics from SexMismatch or FstatX RPCs.

Parameters:

  • sample (str) – Sample name.

  • reported_sex (str) – Sex as reported during ETL.

  • observed_sex (str) – Sex as observed via F-statistic analysis.

  • f_stat (float) – F-statistic value for the sample.

sample: str
reported_sex: str
observed_sex: str
f_stat: float
__init__(sample, reported_sex, observed_sex, f_stat)
Parameters:
Return type:

None

class dnaerys.FstatXResult[source]

Bases: object

Result from the FstatX RPC.

Parameters:
males: tuple[SampleStat, ...]
females: tuple[SampleStat, ...]
metadata: ResponseMetadata
__init__(males, females, metadata)
Parameters:
Return type:

None

class dnaerys.KinshipResult[source]

Bases: object

Result from Kinship, KinshipDuo, or KinshipTrio RPCs.

Parameters:
pairs: tuple[Relatedness, ...]
metadata: ResponseMetadata
__init__(pairs, metadata)
Parameters:
Return type:

None

class dnaerys.Relatedness[source]

Bases: object

Pairwise relatedness result between two samples.

Parameters:

  • sample1 (str) – First sample name.

  • sample2 (str) – Second sample name.

  • degree (KinshipDegree) – Estimated degree of relatedness.

  • phi_bwf (float) – KING “between-family” robust kinship coefficient.

sample1: str
sample2: str
degree: KinshipDegree
phi_bwf: float
__init__(sample1, sample2, degree, phi_bwf)
Parameters:
Return type:

None

class dnaerys.SampleKinshipResult[source]

Bases: object

Result from the SampleKinship RPC (external sample vs. dataset).

Parameters:

  • relatives (tuple[SampleRelatedness, ...]) – Related dataset samples and their kinship measures.

  • accepted_snvs (int) – Number of valid autosomal biallelic SNVs accepted from the input VCF.

  • metadata (ResponseMetadata) – Server response metadata.

relatives: tuple[SampleRelatedness, ...]
accepted_snvs: int
metadata: ResponseMetadata
__init__(relatives, accepted_snvs, metadata)
Parameters:
Return type:

None

class dnaerys.SampleRelatedness[source]

Bases: object

Relatedness of a dataset sample to an external sample of interest.

Parameters:

  • sample (str) – Dataset sample name.

  • degree (KinshipDegree) – Estimated degree of relatedness.

  • phi_bwf (float) – KING kinship coefficient.

  • common_loci (int) – Number of common autosomal biallelic SNV loci used for the estimate.

  • n_het_s1 (int) – Heterozygous alt GT count in the external sample. Proto field: nHetS1.

  • n_het_s2 (int) – Heterozygous alt GT count in the dataset sample. Proto field: nHetS2.

  • n_het_s1s2 (int) – Loci where both samples are heterozygous. Proto field: nHetS1S2.

  • n_hom_op (int) – Loci where samples are opposite homozygous. Proto field: nHomOp.

sample: str
degree: KinshipDegree
phi_bwf: float
common_loci: int
n_het_s1: int
n_het_s2: int
n_het_s1s2: int
n_hom_op: int
__init__(sample, degree, phi_bwf, common_loci, n_het_s1, n_het_s2, n_het_s1s2, n_hom_op)
Parameters:
Return type:

None

class dnaerys.TopHweResult[source]

Bases: object

Result from the TopNHWE RPC.

Parameters:
variants: tuple[VariantWithStats, ...]
metadata: ResponseMetadata
__init__(variants, metadata)
Parameters:
Return type:

None

class dnaerys.TopChi2Result[source]

Bases: object

Result from the TopNchi2 RPC.

Parameters:
variants: tuple[VariantWithStats, ...]
metadata: ResponseMetadata
__init__(variants, metadata)
Parameters:
Return type:

None

Enums

class dnaerys.Chromosome[source]

Bases: IntEnum

Human chromosome identifiers.

25 members: autosomes 1–22, sex chromosomes X and Y, and mitochondrial DNA. Integer values match the proto Chromosome enum (CHR1 = 1 … CHRMT = 25). CHROMOSOME_UNSPECIFIED (0) is excluded.

CHR1 = 1
CHR2 = 2
CHR3 = 3
CHR4 = 4
CHR5 = 5
CHR6 = 6
CHR7 = 7
CHR8 = 8
CHR9 = 9
CHR10 = 10
CHR11 = 11
CHR12 = 12
CHR13 = 13
CHR14 = 14
CHR15 = 15
CHR16 = 16
CHR17 = 17
CHR18 = 18
CHR19 = 19
CHR20 = 20
CHR21 = 21
CHR22 = 22
CHRX = 23
CHRY = 24
CHRMT = 25
__new__(value)
class dnaerys.RefAssembly[source]

Bases: IntEnum

Reference genome assembly versions.

GRCh37 (hg19) and GRCh38 (hg38). The Dnaerys server defaults to GRCh38 when the assembly is unspecified.

GRCh37 = 1
GRCh38 = 2
__new__(value)
class dnaerys.VariantType[source]

Bases: IntEnum

Sequence Ontology variant class terms.

34 members corresponding to the proto VariantType enum. See https://asia.ensembl.org/info/genome/variation/prediction/classification.html#classes

SNV = 1
INSERTION = 2
DELETION = 3
INDEL = 4
SUBSTITUTION = 5
INVERSION = 6
TRANSLOCATION = 7
DUPLICATION = 8
ALU_INSERTION = 9
COMPLEX_STRUCTURAL_ALTERATION = 10
COMPLEX_SUBSTITUTION = 11
COPY_NUMBER_GAIN = 12
COPY_NUMBER_LOSS = 13
COPY_NUMBER_VARIATION = 14
INTERCHROMOSOMAL_BREAKPOINT = 15
INTERCHROMOSOMAL_TRANSLOCATION = 16
INTRACHROMOSOMAL_BREAKPOINT = 17
INTRACHROMOSOMAL_TRANSLOCATION = 18
LOSS_OF_HETEROZYGOSITY = 19
MOBILE_ELEMENT_DELETION = 20
MOBILE_ELEMENT_INSERTION = 21
NOVEL_SEQUENCE_INSERTION = 22
SHORT_TANDEM_REPEAT_VARIATION = 23
TANDEM_DUPLICATION = 24
PROBE = 25
ALU_DELETION = 26
HERV_DELETION = 27
HERV_INSERTION = 28
LINE1_DELETION = 29
LINE1_INSERTION = 30
SVA_DELETION = 31
SVA_INSERTION = 32
COMPLEX_CHROMOSOMAL_REARRANGEMENT = 33
SEQUENCE_ALTERATION = 34
__new__(value)
class dnaerys.FeatureType[source]

Bases: IntEnum

VEP feature types.

3 members: TRANSCRIPT, REGULATORYFEATURE, MOTIFFEATURE.

TRANSCRIPT = 1
REGULATORYFEATURE = 2
MOTIFFEATURE = 3
__new__(value)
class dnaerys.BioType[source]

Bases: IntEnum

VEP biotypes for transcripts and regulatory features.

47 members corresponding to the proto BioType enum. See https://asia.ensembl.org/info/genome/genebuild/biotypes.html

PROCESSED_TRANSCRIPT = 1
LNCRNA = 2
ANTISENSE = 3
MACRO_LNCRNA = 4
NON_CODING = 5
RETAINED_INTRON = 6
SENSE_INTRONIC = 7
SENSE_OVERLAPPING = 8
LINCRNA = 9
NCRNA = 10
MIRNA = 11
MISCRNA = 12
PIRNA = 13
RRNA = 14
SIRNA = 15
SNRNA = 16
SNORNA = 17
TRNA = 18
VAULTRNA = 19
PROTEIN_CODING = 20
PSEUDOGENE = 21
IG_PSEUDOGENE = 22
POLYMORPHIC_PSEUDOGENE = 23
PROCESSED_PSEUDOGENE = 24
TRANSCRIBED_PSEUDOGENE = 25
TRANSLATED_PSEUDOGENE = 26
UNITARY_PSEUDOGENE = 27
UNPROCESSED_PSEUDOGENE = 28
READTHROUGH = 29
STOP_CODON_READTHROUGH = 30
TEC = 31
TR_GENE = 32
TR_C_GENE = 33
TR_D_GENE = 34
TR_J_GENE = 35
TR_V_GENE = 36
IG_GENE = 37
IG_C_GENE = 38
IG_D_GENE = 39
IG_J_GENE = 40
IG_V_GENE = 41
NONSENSE_MEDIATED_DECAY = 42
PROMOTER = 43
PROMOTER_FLANKING_REGION = 44
ENHANCER = 45
CTCF_BINDING_SITE = 46
OPEN_CHROMATIN_REGION = 47
__new__(value)
class dnaerys.Consequence[source]

Bases: IntEnum

Sequence Ontology variant consequence terms.

41 members corresponding to the proto Consequence enum. See https://asia.ensembl.org/info/genome/variation/prediction/predicted_data.html#consequences

TRANSCRIPT_ABLATION = 1
SPLICE_ACCEPTOR_VARIANT = 2
SPLICE_DONOR_VARIANT = 3
STOP_GAINED = 4
FRAMESHIFT_VARIANT = 5
STOP_LOST = 6
START_LOST = 7
TRANSCRIPT_AMPLIFICATION = 8
INFRAME_INSERTION = 9
INFRAME_DELETION = 10
MISSENSE_VARIANT = 11
PROTEIN_ALTERING_VARIANT = 12
SPLICE_REGION_VARIANT = 13
INCOMPLETE_TERMINAL_CODON_VARIANT = 14
START_RETAINED_VARIANT = 15
STOP_RETAINED_VARIANT = 16
SYNONYMOUS_VARIANT = 17
CODING_SEQUENCE_VARIANT = 18
MATURE_MIRNA_VARIANT = 19
FIVE_PRIME_UTR_VARIANT = 20
THREE_PRIME_UTR_VARIANT = 21
NON_CODING_TRANSCRIPT_EXON_VARIANT = 22
INTRON_VARIANT = 23
NMD_TRANSCRIPT_VARIANT = 24
NON_CODING_TRANSCRIPT_VARIANT = 25
UPSTREAM_GENE_VARIANT = 26
DOWNSTREAM_GENE_VARIANT = 27
TFBS_ABLATION = 28
TFBS_AMPLIFICATION = 29
TF_BINDING_SITE_VARIANT = 30
REGULATORY_REGION_ABLATION = 31
REGULATORY_REGION_AMPLIFICATION = 32
FEATURE_ELONGATION = 33
REGULATORY_REGION_VARIANT = 34
FEATURE_TRUNCATION = 35
INTERGENIC_VARIANT = 36
SPLICE_POLYPYRIMIDINE_TRACT_VARIANT = 37
SPLICE_DONOR_5TH_BASE_VARIANT = 38
SPLICE_DONOR_REGION_VARIANT = 39
CODING_TRANSCRIPT_VARIANT = 40
SEQUENCE_VARIANT = 41
__new__(value)
class dnaerys.Impact[source]

Bases: IntEnum

VEP impact severity levels.

4 members ordered from most to least severe: HIGH, MODERATE, LOW, MODIFIER.

HIGH = 1
MODERATE = 2
LOW = 3
MODIFIER = 4
__new__(value)
class dnaerys.SIFT[source]

Bases: IntEnum

SIFT prediction terms for amino acid substitution impact.

See https://sift.bii.a-star.edu.sg/

TOLERATED = 1
DELETERIOUS = 2
__new__(value)
class dnaerys.PolyPhen[source]

Bases: IntEnum

PolyPhen-2 prediction terms for amino acid substitution impact.

BENIGN = 1
POSSIBLY_DAMAGING = 2
PROBABLY_DAMAGING = 3
UNKNOWN = 4
__new__(value)
class dnaerys.ClinSignificance[source]

Bases: IntEnum

ClinVar clinical significance categories.

19 members corresponding to the proto ClinSignificance enum. See https://www.ncbi.nlm.nih.gov/clinvar/docs/clinsig/

CLNSIG_BENIGN = 1
LIKELY_BENIGN = 2
UNCERTAIN_SIGNIFICANCE = 3
LIKELY_PATHOGENIC = 4
PATHOGENIC = 5
DRUG_RESPONSE = 6
ASSOCIATION = 7
RISK_FACTOR = 8
PROTECTIVE = 9
AFFECTS = 10
CONFERS_SENSITIVITY = 11
CONFLICTING_INTERPRETATIONS = 12
NOT_PROVIDED = 13
OTHER = 14
LIKELY_PATHOGENIC_LOW_PENETRANCE = 15
PATHOGENIC_LOW_PENETRANCE = 16
UNCERTAIN_RISK_ALLELE = 17
LIKELY_RISK_ALLELE = 18
ESTABLISHED_RISK_ALLELE = 19
__new__(value)
class dnaerys.AlphaMissense[source]

Bases: IntEnum

AlphaMissense pathogenicity classification.

See https://www.science.org/doi/10.1126/science.adg7492

Thresholds: AM_LIKELY_BENIGN (score < 0.34), AM_LIKELY_PATHOGENIC (score > 0.564), AM_AMBIGUOUS (otherwise).

AM_LIKELY_BENIGN = 1
AM_LIKELY_PATHOGENIC = 2
AM_AMBIGUOUS = 3
__new__(value)
class dnaerys.KinshipDegree[source]

Bases: IntEnum

Kinship relatedness degree classifications.

Based on the KING robust kinship estimator phi_bwf thresholds: TWINS_MONOZYGOTIC (> 0.354), FIRST_DEGREE (0.177–0.354), SECOND_DEGREE (0.0884–0.177), THIRD_DEGREE (0.0442–0.0884), UNRELATED (< 0.0442).

See https://www.ncbi.nlm.nih.gov/pmc/articles/PMC3025716

TWINS_MONOZYGOTIC = 1
FIRST_DEGREE = 2
SECOND_DEGREE = 3
THIRD_DEGREE = 4
UNRELATED = 5
__new__(value)

Enum resolution helpers

dnaerys.resolve_chromosome(value)[source]

Resolve a chromosome identifier to a Chromosome enum member.

Parameters:

value (Chromosome | str | int) –

Accepts:

  • A Chromosome enum member (returned as-is).

  • An integer 1–25 (converted via Chromosome(value)).

  • A string alias (case-insensitive): "chr1" / "CHR_1" / "1" for autosomes, "chrX" / "X" for sex chromosomes, "chrMT" / "MT" for mitochondrial DNA.

Returns:

The resolved enum member.

Return type:

Chromosome

Raises:

  • ValueError – If value is a string that does not match any known alias.

  • TypeError – If value is neither a Chromosome, str, nor int.

dnaerys.resolve_enum(enum_cls, value)[source]

Resolve a string to an enum member by exact name (case-insensitive).

Parameters:

  • enum_cls (type[TypeVar(E, bound= IntEnum)]) – The target enum class.

  • value (TypeVar(E, bound= IntEnum) | str) – Either an existing member of enum_cls (returned as-is) or a string matching a member name case-insensitively.

Returns:

The resolved enum member.

Return type:

TypeVar(E, bound= IntEnum)

Raises:

ValueError – If value is a string that does not match any member name in enum_cls. The error message lists all valid member names.

dnaerys.resolve_assembly(value)[source]

Resolve a reference assembly identifier to a RefAssembly enum member.

Parameters:

value (RefAssembly | str) – Accepts a RefAssembly member or a string: "GRCh37", "GRCh38" (case-insensitive).

Returns:

The resolved enum member.

Return type:

RefAssembly

Raises:

ValueError – If value is a string that does not match a known assembly name.

Exceptions

class dnaerys.DnaerysError[source]

Bases: Exception

Base exception for all Dnaerys client errors.

All Dnaerys-specific exceptions inherit from this class, so except DnaerysError catches any library error.

The is_retryable property indicates whether the same request may succeed if retried. The base class returns False; subclasses override as appropriate.

property is_retryable: bool

Whether this error is transient and the request may be retried.

class dnaerys.DnaerysConnectionError[source]

Bases: DnaerysError

Connection failure or timeout.

Raised when the gRPC channel cannot reach the server (UNAVAILABLE) or a deadline is exceeded (DEADLINE_EXCEEDED). These are transient errors — retrying (possibly with a longer timeout) may succeed.

property is_retryable: bool

Returns True — connection errors are transient.

class dnaerys.DnaerysAuthenticationError[source]

Bases: DnaerysError

Authentication or authorization failure.

Raised for UNAUTHENTICATED (missing/invalid credentials) or PERMISSION_DENIED (valid credentials but insufficient permissions). Not retryable — the credentials or permissions must be fixed.

class dnaerys.DnaerysNotFoundError[source]

Bases: DnaerysError

Requested resource not found.

Raised for NOT_FOUND gRPC status. Not retryable — the resource does not exist.

class dnaerys.DnaerysInvalidRequestError[source]

Bases: DnaerysError

Invalid request parameters.

Raised for INVALID_ARGUMENT, FAILED_PRECONDITION, or OUT_OF_RANGE gRPC status codes. Not retryable — the request must be corrected.

class dnaerys.DnaerysServerError[source]

Bases: DnaerysError

Server-side error.

Raised for INTERNAL, UNKNOWN, DATA_LOSS, or UNIMPLEMENTED gRPC status codes. Not retryable by default — the cause is on the server side and may require investigation.

class dnaerys.DnaerysResourceExhausted[source]

Bases: DnaerysError

Resource exhausted (rate limit, quota, memory).

Raised for RESOURCE_EXHAUSTED gRPC status. Retryable after a backoff period.

property is_retryable: bool

Returns True — may succeed after backoff.

class dnaerys.DnaerysIncompleteResultWarning[source]

Bases: UserWarning

Warning emitted when results may be incomplete due to unreachable cluster nodes.

This warning fires when a server response has affected=True, indicating that cluster nodes holding potentially relevant data were unreachable. The results are still usable but may be incomplete.

Suppress with warnings.filterwarnings("ignore", category=DnaerysIncompleteResultWarning).

Constants

dnaerys.PROTO_VERSION: str = "R1.20.0"

Protocol buffer schema version that this library targets.