Variant Effects and Protein Stability: parameters and notes¶

See the tutorial for usage and examples.

Each function includes its purpose, API, inputs, outputs, example code and result description. Prepare any required credentials, local files and optional dependencies; remote results vary with database releases and query time.

These functions call existing models or prediction services. Weights, SDKs, credentials and service terms remain provider requirements; DNAKit did not retrain these models.

Each function includes its purpose, API, inputs, outputs, example code and result description. Prepare any required credentials, local files and optional dependencies; remote results vary with database releases and query time.

Score regulatory variant effects with AlphaGenome¶

dnakit.databases.alpha_genome_score_variant(*, chromosome, position, reference_bases, alternate_bases, output_type=None, organism=None, sequence_length=None, top_n=None, verbose=True)

Parameter	Type	Required / default	Description and constraints
`chromosome`	string	Required	Chromosome, e.g. 'chr22'.
`position`	integer	Required	1-based variant position.
`reference_bases`	string	Required	Reference allele, e.g. 'A'.
`alternate_bases`	string	Required	Alternate allele, e.g. 'C'.
`output_type`	string \| null	None	Modality to score: RNA_SEQ (default), ATAC, DNASE, CAGE, CHIP_HISTONE, CHIP_TF, SPLICE_SITES, CONTACT_MAPS.
`organism`	string \| null	None	'human' (default) or 'mouse'.
`sequence_length`	string \| null	None	Context window: 16KB, 100KB, 500KB, or 1MB (default).
`top_n`	integer \| null	None	Number of top \|effect\| tracks to return (default 20).
`verbose`	bool	True	Progress flag.

Configure before running: ALPHA_GENOME_API_KEY.

Predict mutation effects on protein stability with DynaMut2¶

dnakit.databases.dyna_mut2_predict_stability(*, operation=None, pdb_id, chain, mutation, verbose=True)

Parameter	Type	Required / default	Description and constraints
`operation`	string	None	Operation type
`pdb_id`	string	Required	4-character PDB accession code from RCSB PDB (e.g., '4HHB' for hemoglobin, '1U46' for ACK1 kinase). The structure will be downloaded automatically.
`chain`	string	Required	Chain identifier in the PDB structure (e.g., 'A'). Must be a valid chain in the specified PDB entry.
`mutation`	string	Required	Single-point mutation in the format WtPosNew where Wt is the wild-type amino acid (1-letter code), Pos is the residue number, and New is the mutant amino acid (1-letter code). Examples: 'V1A' (Val1Ala), 'E346K' (Glu346Lys), 'G12D' (Gly12Asp).
`verbose`	bool	True	Progress flag.

Score missense variants with ESM-2¶

dnakit.databases.esm2_score_missense_variant(*, sequence, position, mutant, wild_type=None, model_id=None, wait_for_model=None, verbose=True)

Parameter	Type	Required / default	Description and constraints
`sequence`	string	Required	Wild-type protein sequence in 1-letter amino-acid code (whitespace is ignored).
`position`	integer	Required	1-based residue position of the variant within the sequence.
`mutant`	string	Required	Mutant amino acid (single 1-letter code, one of the 20 standard residues).
`wild_type`	string \| null	None	Optional wild-type residue (1-letter). If given, it is validated against the residue at `position` to catch coordinate/sequence mismatches.
`model_id`	string \| null	None	ESM-2 model to use. Default 'facebook/esm2_t33_650M_UR50D'. Other sizes: esm2_t30_150M_UR50D, esm2_t12_35M_UR50D, esm2_t6_8M_UR50D.
`wait_for_model`	boolean \| null	None	If true, block until the model finishes loading on the HF servers instead of returning a retryable 'loading' status.
`verbose`	bool	True	Progress flag.

Summarize protein feature disruption caused by a variant¶

dnakit.databases.esm_explain_variant_mechanism(*, sequence, position, ref_aa, alt_aa, window=None, top_k_features=None, include_descriptions=None, model=None, sae_model=None, verbose=True)

Parameter	Type	Required / default	Description and constraints
`sequence`	string	Required	Reference (wild-type) protein amino acid sequence in single-letter code. Up to ~2700 AA.
`position`	integer	Required	1-indexed residue position of the variant
`ref_aa`	string	Required	Single-letter wild-type amino acid (must match sequence[position-1])
`alt_aa`	string	Required	Single-letter substituted amino acid
`window`	integer	None	Residue window centered on the mutation for activation summation.
`top_k_features`	integer	None	Number of top lost / top gained features to describe and include in the category summary.
`include_descriptions`	boolean	None	If true (default), call ESM_describe_sae_feature on each top feature to get category labels. If false, return raw feature IDs without categories (cheaper).
`model`	string	None	ESMC base model
`sae_model`	string	None	SAE codebook identifier
`verbose`	bool	True	Progress flag.

Configure before running: ESM_API_KEY.

Batch-score missense variants using SAE disruption¶

dnakit.databases.esm_score_variant_sae_batch(*, sequence, variants, window=None, top_k_features=None, model=None, sae_model=None, verbose=True)

Parameter	Type	Required / default	Description and constraints
`sequence`	string	Required	Reference (wild-type) protein amino acid sequence in single-letter code. Up to ~2700 AA.
`variants`	array	Required	List of variants to score. Each variant: {position: 1-indexed int, ref_aa: single letter matching sequence[position-1], alt_aa: single letter substitution}. {"maxItems": 100, "items": {"type": "object", "properties": {"position": {"type": "integer", "description": "1-indexed residue position"}, "ref_aa": {"type": "string", "description": "Single-letter wild-type amino acid (must match sequence[position-1])"}, "alt_aa": {"type": "string", "description": "Single-letter substituted amino acid"}}, "required": ["position", "ref_aa", "alt_aa"]}}
`window`	integer	None	Residue window centered on each variant for activation summation. Default 8 (i.e. positions [pos-8, pos+8]).
`top_k_features`	integer	None	Number of top features to return per variant (top-K lost + top-K gained).
`model`	string	None	ESMC base model (must be the 6B model — SAEs are trained against it)
`sae_model`	string	None	SAE codebook identifier
`verbose`	bool	True	Progress flag.

Configure before running: ESM_API_KEY.

Compare reference and mutant protein SAE features¶

dnakit.databases.esm_score_variant_sae_disruption(*, sequence, position, ref_aa, alt_aa, window=None, top_k_features=None, model=None, sae_model=None, verbose=True)

Parameter	Type	Required / default	Description and constraints
`sequence`	string	Required	Reference protein sequence (canonical isoform). Single-letter codes, no gaps. The mutant sequence is built internally by substituting alt_aa at position.
`position`	integer	Required	1-indexed mutation position. The amino acid at sequence[position-1] must equal ref_aa; otherwise the tool returns an error (the wrong sequence was supplied or the variant notation references a different isoform).
`ref_aa`	string	Required	Reference amino acid at the mutation position, single-letter code (e.g. 'R'). Tool validates this matches the supplied sequence.
`alt_aa`	string	Required	Mutant amino acid, single-letter code (e.g. 'H' for R175H).
`window`	integer	None	Residue window radius around the mutation. Per-feature activations are summed across this window before computing the delta. Default 8 = +/- 8 residues = 17-residue window.
`top_k_features`	integer	None	Number of top LOST and top GAINED features to return. Default 10.
`model`	string	None	ESMC backbone (default esmc-6b-2024-12).
`sae_model`	string	None	SAE checkpoint (default layer-60 6B SAE).
`verbose`	bool	True	Progress flag.

Configure before running: ESM_API_KEY.

Score DNA variant effects with Evo 2¶

dnakit.databases.evo2_score_variant(*, ref_sequence=None, alt_sequence=None, sequence=None, position=None, reference=None, alternate=None, model=None, verbose=True)

Parameter	Type	Required / default	Description and constraints
`ref_sequence`	string \| null	None	Reference DNA window (A/C/G/T/N). Use with alt_sequence (same length).
`alt_sequence`	string \| null	None	Alternate DNA window, same length/centering as ref_sequence.
`sequence`	string \| null	None	Reference DNA window for point-substitution mode (use with position + alternate).
`position`	integer \| null	None	1-based position of the substituted base within `sequence`.
`reference`	string \| null	None	Optional reference base (single letter) at `position`, validated against `sequence`.
`alternate`	string \| null	None	Alternate base (single letter) substituted at `position`.
`model`	string	None	Hosted Evo 2 model size: evo2-40b (default, most accurate) or evo2-7b (smaller, faster).
`verbose`	bool	True	Progress flag.

Configure before running: NVIDIA_API_KEY.

Retrieve a variant's maximum SpliceAI delta score¶

dnakit.databases.splice_ai_get_max_delta(*, variant, genome=None, verbose=True)

Parameter	Type	Required / default	Description and constraints
`variant`	string	Required	Variant in chr-pos-ref-alt format (e.g., chr8-140300616-T-G)
`genome`	string	None	Genome build: 37 or 38 (default: 38)
`verbose`	bool	True	Progress flag.

Predict splice effects with Pangolin¶

dnakit.databases.splice_ai_predict_pangolin(*, variant, genome=None, distance=None, mask=None, verbose=True)

Parameter	Type	Required / default	Description and constraints
`variant`	string	Required	Variant in chr-pos-ref-alt format (e.g., chr8-140300616-T-G)
`genome`	string	None	Genome build: 37 or 38 (default: 38)
`distance`	integer	None	Distance parameter for model (default: 1000)
`mask`	boolean	None	Use masked scores
`verbose`	bool	True	Progress flag.

Predict splice-site changes with SpliceAI¶

dnakit.databases.splice_ai_predict_splice(*, variant, genome=None, distance=None, mask=None, verbose=True)

Parameter	Type	Required / default	Description and constraints
`variant`	string	Required	Variant in chr-pos-ref-alt format (e.g., chr8-140300616-T-G) or colon-separated
`genome`	string	None	Genome build: 37 (GRCh37/hg19) or 38 (GRCh38/hg38). Default: 38
`distance`	integer	None	Distance parameter for model (default: 50). Larger values capture more distal effects.
`mask`	boolean	None	Use masked scores (recommended for variant interpretation). Raw scores better for alternative splicing analysis.
`verbose`	bool	True	Progress flag.