Download: 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.

ENCODE returns text: mostly JSON, but get_citations can return BibTeX/RIS and export_data can return CSV/TSV. Use json.loads() only for JSON. Tracking and credentials use ~/.dnakit-encode/; persistent credential storage needs dnakit[encode-credentials].

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.

Download a file over HTTP or HTTPS

dnakit.databases.download_file(*, url, output_path=None, timeout=None, return_content=None, chunk_size=None, follow_redirects=None, verbose=True)

Parameter	Type	Required / default	Description and constraints
url	string	Required	HTTP or HTTPS URL to download from (e.g., https://example.com/file.txt)
output_path	string	None	Optional path to save the file. If not specified, file will be saved to system temp directory.
timeout	integer	None	Request timeout in seconds
return_content	boolean	None	If true, return file content as text instead of saving to disk (default: false)
chunk_size	integer	None	Download chunk size in bytes (default: 8192)
follow_redirects	boolean	None	Follow HTTP redirects (default: true)
verbose	bool	True	Progress flag.

Download an ENA nucleotide sequence with a checksum manifest

dnakit.download.ena.sequence(accession, output_path, *, format='fasta', config=None, search_config=None, api_base_url='https://www.ebi.ac.uk/ena/browser/api', verbose=True)

Parameter	Type	Required / default	Description and constraints
accession	str	Required	Versioned sequence accession; ENA uses INSDC, NCBI also accepts RefSeq.
output_path	str | Path	Required	Destination sequence file path.
format	Literal['fasta', 'embl', 'genbank']	'fasta'	fasta, genbank or embl; see the download guide for provider and conversion support.
config	DownloadConfig | None	None	SearchConfig for queries; DownloadConfig for downloads.
search_config	SearchConfig | None	None	SearchConfig for query timeout, response size and NCBI credentials.
api_base_url	str	'https://www.ebi.ac.uk/ena/browser/api'	Service API base URL; see the signature for its default.
verbose	bool	True	Show DNAKit progress messages without changing results.

Download an NCBI nucleotide or protein sequence

dnakit.download.ncbi.sequence(accession, output_path, *, database='nuccore', format='fasta', seq_start=None, seq_stop=None, strand=1, config=None, search_config=None, api_base_url='https://eutils.ncbi.nlm.nih.gov/entrez/eutils', verbose=True)

Parameter	Type	Required / default	Description and constraints
accession	str	Required	Versioned sequence accession; ENA uses INSDC, NCBI also accepts RefSeq.
output_path	str | Path	Required	Destination sequence file path.
database	Literal['nuccore', 'protein']	'nuccore'	NCBI sequence database: nuccore or protein.
format	Literal['fasta', 'genbank', 'embl']	'fasta'	fasta, genbank or embl; see the download guide for provider and conversion support.
seq_start	int | None	None	NCBI nucleotide start, 1-based inclusive; requires seq_stop.
seq_stop	int | None	None	NCBI nucleotide end, 1-based inclusive; requires seq_start.
strand	Literal[1, 2]	1	NCBI nucleotide strand: 1 forward, 2 reverse complement.
config	DownloadConfig | None	None	SearchConfig for queries; DownloadConfig for downloads.
search_config	SearchConfig | None	None	SearchConfig for query timeout, response size and NCBI credentials.
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.

Find and batch-download ENCODE files

dnakit.encode.batch_download(download_dir, file_format=None, output_type=None, output_category=None, assembly=None, assay_title=None, organism='Homo sapiens', organ=None, biosample_type=None, target=None, preferred_default=None, organize_by='experiment', verify_md5=True, limit=100, dry_run=True, *, verbose=True)

Parameter	Type	Required / default	Description and constraints
download_dir	str	Required	Local directory to save files
file_format	str | None	None	File format filter ("fastq", "bam", "bed", "bigWig", etc.)
output_type	str | None	None	Output type filter ("reads", "peaks", "signal", etc.)
output_category	str | None	None	Output category ("raw data", "alignment", "annotation", etc.)
assembly	str | None	None	Genome assembly ("GRCh38", "mm10", etc.)
assay_title	str | None	None	Assay type ("Histone ChIP-seq", "ATAC-seq", "total RNA-seq", etc.)
organism	str	'Homo sapiens'	Organism (default: "Homo sapiens")
organ	str | None	None	Organ/tissue ("pancreas", "brain", "liver", etc.)
biosample_type	str | None	None	Biosample type ("tissue", "cell line", "primary cell", etc.)
target	str | None	None	ChIP/CUT&RUN target ("H3K27me3", "CTCF", etc.)
preferred_default	bool | None	None	If True, only download default/recommended files
organize_by	Literal['flat', 'experiment', 'format', 'experiment_format']	'experiment'	File organization ("flat", "experiment", "format", "experiment_format")
verify_md5	bool	True	Verify downloads with MD5 checksums (default True)
limit	int	100	Max files to download (default 100, safety limit)
dry_run	bool	True	If True (default), only preview what would be downloaded. Set False to download.
verbose	bool	True	Show DNAKit progress messages without changing results.

Download ENCODE files by accession

dnakit.encode.download_files(file_accessions, download_dir, organize_by='flat', verify_md5=True, *, verbose=True)

Parameter	Type	Required / default	Description and constraints
file_accessions	list[str]	Required	List of file accessions to download (e.g., ["ENCFF635JIA", "ENCFF388RZD"])
download_dir	str	Required	Local directory path to save files (e.g., "./data/encode")
organize_by	Literal['flat', 'experiment', 'format', 'experiment_format']	'flat'	How to organize downloaded files: - "flat": All files in download_dir (default) - "experiment": download_dir/ENCSR.../filename - "format": download_dir/bed/filename - "experiment_format": download_dir/ENCSR.../bed/filename
verify_md5	bool	True	Verify file integrity with MD5 checksum (default True)
verbose	bool	True	Show DNAKit progress messages without changing results.