Sequence, assembly and sequencing queries: 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.

Search ENA biological samples by taxonomy or keyword¶

dnakit.databases.enaportal_search_samples(*, query, limit=None, fields=None, verbose=True)

Parameter	Type	Required / default	Description and constraints
`query`	string	Required	ENA search query. Examples: 'tax_tree(562)' (E. coli), 'description="liver"', 'tax_tree(9606) AND description="tumor"'.
`limit`	integer \| null	None	Maximum results to return (1-100, default 10).
`fields`	string \| null	None	Comma-separated fields. Default: 'sample_accession,sample_alias,description,tax_id,scientific_name,first_public'.
`verbose`	bool	True	Progress flag.

Search ENA sequencing studies¶

dnakit.databases.enaportal_search_studies(*, query, limit=None, fields=None, verbose=True)

Parameter	Type	Required / default	Description and constraints
`query`	string	Required	ENA search query. IMPORTANT: Plain text keywords (e.g., 'cancer') will cause HTTP 400. Always wrap text keywords with description="...". Examples: 'description="cancer"', 'tax_tree(9606)' (human), 'description="transcriptomics" AND tax_tree(10090)' (mouse transcriptomics).
`limit`	integer \| null	None	Maximum results to return (1-100, default 10).
`fields`	string \| null	None	Comma-separated fields to return. Default: 'study_accession,study_title,center_name,first_public,description'. Other fields: 'last_updated,tax_id,scientific_name'.
`verbose`	bool	True	Progress flag.

Retrieve gene, transcript or genomic interval sequences¶

dnakit.databases.ensembl_get_sequence(*, id, type=None, species=None, multiple_sequences=None, verbose=True)

Parameter	Type	Required / default	Description and constraints
`id`	string	Required	Ensembl gene/transcript ID (e.g., 'ENSG00000139618' or 'ENST00000380152')
`type`	string	None	Sequence type: 'genomic' (genomic DNA), 'cds' (coding sequence), 'cdna' (cDNA), 'protein' (protein/peptide sequence -- 'peptide' is also accepted and mapped to 'protein', the name Ensembl's own REST API actually expects)
`species`	string	None	Species name (optional, defaults to human)
`multiple_sequences`	boolean	None	Return multiple sequences if available (e.g., all transcripts)
`verbose`	bool	True	Progress flag.

Retrieve a sequence by Ensembl identifier¶

dnakit.databases.ensembl_seq_get_id_sequence(*, ensembl_id, type=None, verbose=True)

Parameter	Type	Required / default	Description and constraints
`ensembl_id`	string	Required	Ensembl stable ID. Examples: 'ENSP00000269305' (TP53 protein, 393 aa), 'ENST00000269305' (TP53-201 transcript), 'ENSG00000141510' (TP53 gene). Protein IDs start with ENSP, transcript with ENST, gene with ENSG.
`type`	string	None	Sequence type to return. Options: 'protein' (amino acid), 'cdna' (spliced cDNA), 'cds' (coding sequence), 'genomic' (unspliced DNA). Default: 'protein' for ENSP IDs, auto-detected for others.
`verbose`	bool	True	Progress flag.

Retrieve Ensembl reference sequence by genomic coordinates¶

dnakit.databases.ensembl_seq_get_region_sequence(*, region, species=None, verbose=True)

Parameter	Type	Required / default	Description and constraints
`region`	string	Required	Genomic region in format 'chr:start-end' or 'chr:start..end:strand'. Examples: '17:7668421-7668520' (TP53 locus, 100bp), '7:140424943-140425043' (BRAF locus, 100bp), 'X:15560138-15602945' (MECP2 gene). Strand: 1 for forward, -1 for reverse.
`species`	string	None	Ensembl species name. Default: 'homo_sapiens'. Examples: 'mus_musculus', 'danio_rerio', 'drosophila_melanogaster'.
`verbose`	bool	True	Progress flag.

Convert GenBank UIDs to sequence accessions¶

dnakit.databases.ncbi_fetch_accessions(*, operation=None, uids, verbose=True)

Parameter	Type	Required / default	Description and constraints
`operation`	object \| None	None	Operation type (fixed: fetch_accession)
`uids`	object	Required	GenBank UID(s) from NCBI_search_nucleotide. Can be single UID or array of UIDs. {"oneOf": [{"type": "array", "items": {"type": "string"}}, {"type": "string"}]}
`verbose`	bool	True	Progress flag.

Retrieve NCBI nucleotide records by accession¶

dnakit.databases.ncbi_get_sequence(*, operation=None, accession, format=None, verbose=True)

Parameter	Type	Required / default	Description and constraints
`operation`	object \| None	None	Operation type (fixed: fetch_sequence)
`accession`	string	Required	NCBI accession number (e.g., 'U00096', 'NC_045512', 'NM_000546'). Works with GenBank, EMBL, and RefSeq accessions.
`format`	string	None	Sequence format: 'fasta' for FASTA, 'gb' for GenBank, 'embl' for EMBL, 'gp' for GenPept protein. Default: fasta
`verbose`	bool	True	Progress flag.

Search nucleotide records by organism, gene or strain¶

dnakit.databases.ncbi_search_nucleotide(*, operation=None, organism=None, gene=None, strain=None, keywords=None, seq_type=None, query=None, limit=None, sort=None, verbose=True)

Parameter	Type	Required / default	Description and constraints
`operation`	object \| None	None	Operation type (fixed: search)
`organism`	string	None	Organism name to search (e.g., 'Escherichia coli', 'Homo sapiens'). Searches in [Organism] field.
`gene`	string	None	Gene name to search (e.g., 'BRCA1', 'TP53'). Searches in [Gene] field.
`strain`	string	None	Strain name to filter (e.g., 'K-12', 'MG1655'). Searches in [Strain] field.
`keywords`	string	None	Keywords to search in titles (e.g., 'complete genome', 'mitochondrial'). Searches in [Title] field.
`seq_type`	string	None	Sequence type filter: 'complete_genome' for complete genomes, 'mrna' for mRNA sequences, 'refseq' for RefSeq curated sequences
`query`	string	None	Free-form search query if not using structured filters. Use NCBI query syntax (e.g., '(Escherichia coli[Organism]) AND (K-12[Strain])')
`limit`	integer	None	Maximum number of results to return (default: 20, max: 100)
`sort`	string	None	Sort order for results (default: relevance)
`verbose`	bool	True	Progress flag.

Search SRA runs by study and experimental conditions¶

dnakit.databases.ncbi_sra_search_runs(*, operation=None, study=None, organism=None, strategy=None, platform=None, source=None, query=None, limit=None, sort=None, verbose=True)

Parameter	Type	Required / default	Description and constraints
`operation`	object \| None	None	Operation type (fixed: search)
`study`	string	None	Study accession to search (e.g., 'SRP000001', 'ERP000001', 'DRP000001'). Searches in [Study] field.
`organism`	string	None	Organism name to filter (e.g., 'Homo sapiens', 'Mus musculus', 'SARS-CoV-2'). Searches in [Organism] field.
`strategy`	string	None	Sequencing strategy to filter. Common values: 'RNA-Seq' (transcriptomics), 'WGS' (whole genome), 'WXS' (exome), 'ChIP-Seq' (chromatin), 'ATAC-Seq' (accessibility), 'Bisulfite-Seq' (methylation), 'AMPLICON' (targeted), 'Hi-C' (3D genome)
`platform`	string	None	Sequencing platform to filter. Common values: 'ILLUMINA', 'OXFORD_NANOPORE', 'PACBIO_SMRT', 'ION_TORRENT', 'BGISEQ'
`source`	string	None	Library source to filter. Common values: 'GENOMIC' (DNA), 'TRANSCRIPTOMIC' (RNA), 'METAGENOMIC', 'METATRANSCRIPTOMIC', 'SYNTHETIC', 'VIRAL_RNA'
`query`	string	None	Free-form search query if not using structured filters. Use NCBI query syntax (e.g., '(Homo sapiens[Organism]) AND (RNA-Seq[Strategy])')
`limit`	integer	None	Maximum number of results to return (default: 20, max: 100)
`sort`	string	None	Sort order for results (default: relevance)
`verbose`	bool	True	Progress flag.

Retrieve genome assembly versions and metadata¶

dnakit.databases.ncbidatasets_get_genome_assembly(*, accession, verbose=True)

Parameter	Type	Required / default	Description and constraints
`accession`	string	Required	Assembly accession, e.g. 'GCF_000005845.2' (E. coli K-12) or 'GCF_000001405.40' (human GRCh38.p14).
`verbose`	bool	True	Progress flag.

Retrieve chromosome and scaffold sequence reports¶

dnakit.databases.ncbidatasets_get_sequence_reports(*, accession, page_size=None, page_token=None, verbose=True)

Parameter	Type	Required / default	Description and constraints
`accession`	string	Required	Assembly accession, e.g. 'GCF_000005845.2'.
`page_size`	integer \| null	None	Maximum sequence records in this page (default 100, maximum 1000).
`page_token`	string \| null	None	Opaque next_page_token returned by a previous call. Omit for the first page. {"minLength": 1, "pattern": ".\S."}
`verbose`	bool	True	Progress flag.

Retrieve taxonomy lineages and counts by taxon ID¶

dnakit.databases.ncbidatasets_get_taxonomy(*, tax_id, verbose=True)

Parameter	Type	Required / default	Description and constraints
`tax_id`	string	Required	NCBI Taxonomy ID (numeric). Examples: '9606' (Homo sapiens), '10090' (Mus musculus), '7227' (Drosophila melanogaster), '562' (E. coli).
`verbose`	bool	True	Progress flag.

List genome assemblies for a taxon¶

dnakit.databases.ncbidatasets_list_genomes_by_taxon(*, taxon, limit=None, reference_only=None, verbose=True)

Parameter	Type	Required / default	Description and constraints
`taxon`	string	Required	NCBI tax id or scientific name, e.g. '562', 'Escherichia coli', 'Saccharomyces cerevisiae'. {"minLength": 1, "pattern": ".\S."}
`limit`	integer \| null	None	Max assemblies to return (default 20, max 100).
`reference_only`	boolean \| null	None	If true, return only reference/representative genomes.
`verbose`	bool	True	Progress flag.

Find taxonomy suggestions from a partial organism name¶

dnakit.databases.ncbidatasets_suggest_taxonomy(*, query, verbose=True)

Parameter	Type	Required / default	Description and constraints
`query`	string	Required	Partial organism name to search. Examples: 'drosophila', 'escherichia', 'arabidopsis', 'saccharomyces'. {"minLength": 1, "pattern": ".\S."}
`verbose`	bool	True	Progress flag.

Retrieve SRA experiment metadata by accession¶

dnakit.databases.sra_get_experiment(*, accession, verbose=True)

Parameter	Type	Required / default	Description and constraints
`accession`	string	Required	SRA accession number (e.g., 'SRX26927637', 'SRP000001', 'SRS000001')
`verbose`	bool	True	Progress flag.

Search SRA sequencing experiments¶

dnakit.databases.sra_search_experiments(*, query=None, organism=None, library_strategy=None, platform=None, limit=None, verbose=True)

Parameter	Type	Required / default	Description and constraints
`query`	string	None	Search keywords (e.g., 'human gut metagenome', 'BRCA1 RNA-Seq', 'single cell lung cancer')
`organism`	string	None	Organism name to filter by (e.g., 'Homo sapiens', 'Mus musculus', 'human gut metagenome')
`library_strategy`	string	None	Sequencing strategy filter (e.g., 'RNA-Seq', 'WGS', 'WXS', 'ChIP-Seq', 'ATAC-seq', 'Bisulfite-Seq', 'AMPLICON')
`platform`	string	None	Sequencing platform filter (e.g., 'ILLUMINA', 'PACBIO_SMRT', 'OXFORD_NANOPORE', 'ION_TORRENT')
`limit`	integer	None	Maximum results to return (1-50, default 10)
`verbose`	bool	True	Progress flag.

Resolve sequence UIDs to versioned accessions in batches¶

dnakit.search.ncbi.accessions(uids, *, database='nuccore', config=None, api_base_url='https://eutils.ncbi.nlm.nih.gov/entrez/eutils', verbose=True)

Parameter	Type	Required / default	Description and constraints
`uids`	Sequence[str \| int]	Required	NCBI sequence UIDs, resolved in batches of 200.
`database`	Literal['nuccore', 'protein']	'nuccore'	NCBI sequence database: nuccore or protein.
`config`	SearchConfig \| None	None	SearchConfig for queries; DownloadConfig for downloads.
`api_base_url`	str	'https://eutils.ncbi.nlm.nih.gov/entrez/eutils'	Service API base URL; see the signature for its default.
`verbose`	bool	True	Show DNAKit progress messages without changing results.