Curation (Python)

raven-toolbox objects in raven_toolbox.curation.

Functions

Function	Summary
batch_curate	Add or update metabolites / reactions / genes from data tables.
batch_curate_from_tsv	File-path convenience wrapper for batch_curate.
CurationResult	Record of what batch_curate added / updated.
download_genome_data	Download the GFF3 annotation and protein FASTA for an NCBI genome assembly.
get_gene_data	Build a gene-mapping table from NCBI genome annotation files.
parse_gff_gene_table	Parse a GFF3 file into a gene/protein mapping table.
process_protein_fasta_file	Rename a protein FASTA's headers using a gene mapping table.
rename_model_genes	Rename model's genes in place using a mapping table.
RenameGenesResult	Outcome of a gene-renaming pass.

Reference

batch_curate

batch_curate(model: cobra.Model, *, mets_df: pd.DataFrame | None=None, genes_df: pd.DataFrame | None=None, rxns_df: pd.DataFrame | None=None, rxns_coeffs_df: pd.DataFrame | None=None, met_id_prefix: str='M_', rxn_id_prefix: str='R_')

Add or update metabolites / reactions / genes from data tables.

Each table is optional. rxns_df and rxns_coeffs_df must be provided together (one describes the per-reaction attributes, the other carries the stoichiometric coefficients).

Parameters

model

Model to curate in place.

mets_df, genes_df, rxns_df, rxns_coeffs_df

Tables matching the schema described in raven_toolbox.curation.

met_id_prefix, rxn_id_prefix

Prefixes for freshly-generated metabolite / reaction ids (e.g. s_ and r_ for yeast-GEM, M_ and R_ for the cobrapy / BiGG default). New entity ids are formed by finding the largest existing zero-padded suffix matching the prefix and incrementing from there.

Returns

A :class:CurationResult summarising the changes. :

batch_curate_from_tsv

batch_curate_from_tsv(model: cobra.Model, *, mets_tsv: str | Path | None=None, genes_tsv: str | Path | None=None, rxns_tsv: str | Path | None=None, rxns_coeffs_tsv: str | Path | None=None, met_id_prefix: str='M_', rxn_id_prefix: str='R_')

File-path convenience wrapper for batch_curate.

Each path is optional. TSVs are read with pandas' default read_csv(sep='\t'); empty cells become NaN (not the empty string), which the engine treats as "skip this field".

CurationResult

Record of what batch_curate added / updated.

Each list holds the cobra ids of the affected entities, in the order they were processed.

download_genome_data

download_genome_data(accession: str, *, output_dir: str | Path='.', verbose: bool=True)

Download the GFF3 annotation and protein FASTA for an NCBI genome assembly.

Retrieves both files in one archive via the NCBI Datasets v2 API. Files already present in output_dir are not re-fetched; delete them manually to force a refresh.

Parameters

accession:

NCBI genome assembly accession, e.g. "GCF_000002595.2". Both RefSeq (GCF_) and GenBank (GCA_) prefixes are accepted (case-insensitively).

output_dir:

Directory to save the downloaded files in (default: current directory).

verbose:

Print download progress.

Returns

(gff_file, faa_file):

Paths to the downloaded GFF3 annotation and protein FASTA files.

Raises

ValueError

If accession doesn't start with GCF_/GCA_.

RuntimeError

If the download, extraction, or the archive's contents are invalid.

get_gene_data

get_gene_data(accession_or_path: str | Path, *, output_file: str | Path | None=None, download_dir: str | Path='.')

Build a gene-mapping table from NCBI genome annotation files.

Parameters

accession_or_path:

An NCBI assembly accession (downloaded automatically via download_genome_data if not already present in download_dir), or a path to a local GFF3 file.

output_file:

If given, also save the table as a tab-delimited file.

download_dir:

Directory to download to, if accession_or_path is an accession.

Returns

pandas.DataFrame

See parse_gff_gene_table.

Raises

ValueError

If accession_or_path is neither an existing file nor a recognised NCBI assembly accession.

parse_gff_gene_table

parse_gff_gene_table(gff_path: str | Path)

Parse a GFF3 file into a gene/protein mapping table.

Extracts gene + CDS pairs. The protein accession is taken from each CDS's protein_id (or, failing that, a Dbxref=GenBank:... entry), and the owning gene is resolved through the Parent chain (CDS -> mRNA -> gene for eukaryotes, CDS -> gene for prokaryotes), so the GenBank_protein column matches a protein FASTA's headers.

Returns

pandas.DataFrame

Columns locus_tag, old_locus_tag, GeneID, gene_name, GenBank_protein, UniProt. Deduplicated (a CDS repeats once per exon) on every column except UniProt, matching getGeneData.m's own dedup key exactly.

process_protein_fasta_file

process_protein_fasta_file(faa_file: str | Path, gene_table: pd.DataFrame | str | Path, header_col: str, *, output_dir: str | Path='.')

Rename a protein FASTA's headers using a gene mapping table.

Replaces each sequence header with the value from header_col, matched via the GenBank_protein accession present in the original FASTA header (its first whitespace-delimited token). Sequences whose accession is not found in gene_table keep their original header.

Parameters

faa_file:

Path to the protein FASTA file (.faa) to process.

gene_table:

Either a DataFrame, or a path to a tab-delimited file to load one from (e.g. from raven_toolbox.curation.get_gene_data). Must contain at least the columns "GenBank_protein" and header_col.

header_col:

Column whose values replace each FASTA header (e.g. "locus_tag").

output_dir:

Directory the processed FASTA is saved in. The output file name is the original base name with "_processed" appended before the extension.

Returns

Path

Path to the written processed FASTA file.

Raises

FileNotFoundError

If faa_file doesn't exist.

ValueError

If gene_table is missing "GenBank_protein" or header_col.

Notes

A row is skipped only if its GenBank_protein is empty — not if header_col is, matching processProteinFastaFile.m exactly (an accession mapped to an empty header_col value still renames that sequence's header to an empty string).

rename_model_genes

rename_model_genes(model: cobra.Model, gene_table: pd.DataFrame | str | Path, from_col: str, to_col: str)

Rename model's genes in place using a mapping table.

Parameters

model:

Model to rename genes in.

gene_table:

Either a DataFrame, or a path to a tab-delimited file to load one from.

from_col:

Column whose values match the ids currently in model.genes.

to_col:

Column whose values will replace them.

Returns

RenameGenesResult :

Raises

ValueError

If from_col or to_col is not a column of gene_table.

RenameGenesResult

Outcome of a gene-renaming pass.

Parameters

renamed:

Number of model genes for which a mapping was found and applied.

unmapped:

Model gene ids with no entry in from_col (or an empty to_col), left unchanged. Sorted, unique.