configs

Configuration objects that tell every other module where files live and which thresholds to use. Each config derives its paths from the directory you pass in, so the same code can run against a scratch directory, a shared database, or a cluster filesystem without any global state.

from adtoolbox import configs

See the API overview for how configs pair with core objects.

Helpers

adm_parameter_paths

adm_parameter_paths(parameters_dir: str | PathLike, prefix: str) -> dict[str, str]

Source code in adtoolbox/configs.py

def adm_parameter_paths(parameters_dir: str | os.PathLike, prefix: str) -> dict[str, str]:
    parameters_dir = _norm(parameters_dir)
    return {
        "model_parameters": _join(parameters_dir, f"{prefix}_model_parameters.json"),
        "base_parameters": _join(parameters_dir, f"{prefix}_base_parameters.json"),
        "initial_conditions": _join(parameters_dir, f"{prefix}_initial_conditions.json"),
        "inlet_conditions": _join(parameters_dir, f"{prefix}_inlet_conditions.json"),
        "reactions": _join(parameters_dir, f"{prefix}_reactions.json"),
        "species": _join(parameters_dir, f"{prefix}_species.json"),
    }

Database

Paths and remote URLs for reaction, compound, protein, feed, and study databases, plus the ADM parameter bundle.

Database

Database(
    database_dir: str | PathLike = ".",
    *,
    compound_db: str | None = None,
    reaction_db: str | None = None,
    local_compound_db: str | None = None,
    local_reaction_db: str | None = None,
    csv_reaction_db: str | None = None,
    feed_db: str | None = None,
    amplicon_to_genome_db: str | None = None,
    adm_models: str | None = None,
    cazy_links: list[str] = EXTERNAL_LINKS["cazy_links"],
    amplicon_to_genome_urls: dict = EXTERNAL_LINKS["amplicon2genome"],
    adm_parameters_urls: dict = E_ADM_REMOTE,
    adm_parameters: dict | None = None,
    seed_rxn_url: str = EXTERNAL_LINKS["seed_rxn_url"],
    seed_compound_url: str = EXTERNAL_LINKS["seed_compound_url"],
    protein_db_url: str = INTERNAL_LINKS["protein_db_url"],
    adtoolbox_rxn_db_url: str = INTERNAL_LINKS["adtoolbox_rxn_db_url"],
    feed_db_url: str = INTERNAL_LINKS["feed_db_url"],
    adtoolbox_singularity: str = ADTOOLBOX_CONTAINERS["singularity_x86"],
    adtoolbox_docker: str = ADTOOLBOX_CONTAINERS["docker_x86"],
    protein_db: str | None = None,
    adm_microbial_groups_mapping: dict = E_ADM_MICROBIAL_GROUPS_MAPPING,
    metacyc_protein_db: str | None = None,
    studies_remote: dict = INTERNAL_LINKS,
    studies_local: dict | None = None,
    check_sanity: bool = False
)

Configuration for core.Database functionality.

Source code in adtoolbox/configs.py

def __init__(
    self,
    database_dir: str | os.PathLike = ".",
    *,
    compound_db: str | None = None,
    reaction_db: str | None = None,
    local_compound_db: str | None = None,
    local_reaction_db: str | None = None,
    csv_reaction_db: str | None = None,
    feed_db: str | None = None,
    amplicon_to_genome_db: str | None = None,
    adm_models: str | None = None,
    cazy_links: list[str] = EXTERNAL_LINKS["cazy_links"],
    amplicon_to_genome_urls: dict = EXTERNAL_LINKS["amplicon2genome"],
    adm_parameters_urls: dict = E_ADM_REMOTE,
    adm_parameters: dict | None = None,
    seed_rxn_url: str = EXTERNAL_LINKS["seed_rxn_url"],
    seed_compound_url: str = EXTERNAL_LINKS["seed_compound_url"],
    protein_db_url: str = INTERNAL_LINKS["protein_db_url"],
    adtoolbox_rxn_db_url: str = INTERNAL_LINKS["adtoolbox_rxn_db_url"],
    feed_db_url: str = INTERNAL_LINKS["feed_db_url"],
    adtoolbox_singularity: str = ADTOOLBOX_CONTAINERS["singularity_x86"],
    adtoolbox_docker: str = ADTOOLBOX_CONTAINERS["docker_x86"],
    protein_db: str | None = None,
    adm_microbial_groups_mapping: dict = E_ADM_MICROBIAL_GROUPS_MAPPING,
    metacyc_protein_db: str | None = None,
    studies_remote: dict = INTERNAL_LINKS,
    studies_local: dict | None = None,
    check_sanity: bool = False,
):
    self.database_dir = _norm(database_dir)
    adm_parameters_dir = _join(self.database_dir, "ADM_Parameters")
    studies_dir = _join(self.database_dir, "Studies")

    self.compound_db = _norm(compound_db or _join(self.database_dir, "compounds.json"))
    self.reaction_db = _norm(reaction_db or _join(self.database_dir, "reactions.json"))
    self.local_compound_db = _norm(local_compound_db or _join(self.database_dir, "Local_compounds.json"))
    self.local_reaction_db = _norm(local_reaction_db or _join(self.database_dir, "Local_reactions.json"))
    self.csv_reaction_db = _norm(csv_reaction_db or _join(self.database_dir, "Reaction_Metadata.csv"))
    self.feed_db = _norm(feed_db or _join(self.database_dir, "feed_db.tsv"))
    self.amplicon_to_genome_db = _norm(amplicon_to_genome_db or _join(self.database_dir, "Amplicon2GenomeDBs"))
    self.adm_models = _norm(adm_models or _join(adm_parameters_dir, "models.json"))
    self.cazy_links = cazy_links
    self.amplicon_to_genome_urls = amplicon_to_genome_urls
    self.adm_parameters_urls = adm_parameters_urls
    self.adm_parameters = adm_parameters or adm_parameter_paths(adm_parameters_dir, "e_adm")
    self.adm_parameters = {key: _norm(value) for key, value in self.adm_parameters.items()}
    self.seed_rxn_url = seed_rxn_url
    self.seed_compound_url = seed_compound_url
    self.protein_db_url = protein_db_url
    self.adtoolbox_rxn_db_url = adtoolbox_rxn_db_url
    self.feed_db_url = feed_db_url
    self.adtoolbox_singularity = adtoolbox_singularity
    self.adtoolbox_docker = adtoolbox_docker
    self.protein_db = _norm(protein_db or _join(self.database_dir, "Protein_DB.fasta"))
    self.adm_microbial_groups_mapping = adm_microbial_groups_mapping
    self.studies_remote = studies_remote
    default_studies_local = {
        "metagenomics_studies": _join(studies_dir, "metagenomics_studies.tsv"),
        "experimental_data_db": _join(studies_dir, "experimental_data_references.json"),
    }
    if studies_local:
        default_studies_local.update(studies_local)
    self.studies_local = {key: _norm(value) for key, value in default_studies_local.items()}
    self.metacyc_protein_db = _norm(metacyc_protein_db or _join(self.database_dir, "metacyc_protein_db.fasta"))
    self.protein_db_mmseqs = pathlib.Path(self.protein_db).parent.joinpath("protein_db_mmseqs")

    # Compatibility aliases for older examples/tests that treated Database as
    # the active ADM parameter config.
    self.model_parameters = self.adm_parameters["model_parameters"]
    self.base_parameters = self.adm_parameters["base_parameters"]
    self.initial_conditions = self.adm_parameters["initial_conditions"]
    self.inlet_conditions = self.adm_parameters["inlet_conditions"]
    self.reactions = self.adm_parameters["reactions"]
    self.species = self.adm_parameters["species"]

    if check_sanity:
        self.check_adm_parameters()

database_dir instance-attribute

database_dir = _norm(database_dir)

compound_db instance-attribute

compound_db = _norm(compound_db or _join(database_dir, 'compounds.json'))

reaction_db instance-attribute

reaction_db = _norm(reaction_db or _join(database_dir, 'reactions.json'))

local_compound_db instance-attribute

local_compound_db = _norm(
    local_compound_db or _join(database_dir, "Local_compounds.json")
)

local_reaction_db instance-attribute

local_reaction_db = _norm(
    local_reaction_db or _join(database_dir, "Local_reactions.json")
)

csv_reaction_db instance-attribute

csv_reaction_db = _norm(csv_reaction_db or _join(database_dir, "Reaction_Metadata.csv"))

feed_db instance-attribute

feed_db = _norm(feed_db or _join(database_dir, 'feed_db.tsv'))

amplicon_to_genome_db instance-attribute

amplicon_to_genome_db = _norm(
    amplicon_to_genome_db or _join(database_dir, "Amplicon2GenomeDBs")
)

adm_models instance-attribute

adm_models = _norm(adm_models or _join(adm_parameters_dir, 'models.json'))

cazy_links instance-attribute

cazy_links = cazy_links

amplicon_to_genome_urls instance-attribute

amplicon_to_genome_urls = amplicon_to_genome_urls

adm_parameters_urls instance-attribute

adm_parameters_urls = adm_parameters_urls

adm_parameters instance-attribute

adm_parameters = {key: (_norm(value))for (key, value) in (items())}

seed_rxn_url instance-attribute

seed_rxn_url = seed_rxn_url

seed_compound_url instance-attribute

seed_compound_url = seed_compound_url

protein_db_url instance-attribute

protein_db_url = protein_db_url

adtoolbox_rxn_db_url instance-attribute

adtoolbox_rxn_db_url = adtoolbox_rxn_db_url

feed_db_url instance-attribute

feed_db_url = feed_db_url

adtoolbox_singularity instance-attribute

adtoolbox_singularity = adtoolbox_singularity

adtoolbox_docker instance-attribute

adtoolbox_docker = adtoolbox_docker

protein_db instance-attribute

protein_db = _norm(protein_db or _join(database_dir, 'Protein_DB.fasta'))

adm_microbial_groups_mapping instance-attribute

adm_microbial_groups_mapping = adm_microbial_groups_mapping

studies_remote instance-attribute

studies_remote = studies_remote

studies_local instance-attribute

studies_local = {key: (_norm(value))for (key, value) in (items())}

metacyc_protein_db instance-attribute

metacyc_protein_db = _norm(
    metacyc_protein_db or _join(database_dir, "metacyc_protein_db.fasta")
)

protein_db_mmseqs instance-attribute

protein_db_mmseqs = joinpath('protein_db_mmseqs')

model_parameters instance-attribute

model_parameters = adm_parameters['model_parameters']

base_parameters instance-attribute

base_parameters = adm_parameters['base_parameters']

initial_conditions instance-attribute

initial_conditions = adm_parameters['initial_conditions']

inlet_conditions instance-attribute

inlet_conditions = adm_parameters['inlet_conditions']

reactions instance-attribute

reactions = adm_parameters['reactions']

species instance-attribute

species = adm_parameters['species']

check_adm_parameters

check_adm_parameters()

Source code in adtoolbox/configs.py

def check_adm_parameters(self):
    branches = all(
        pathlib.Path(path).parent == pathlib.Path(self.adm_parameters["model_parameters"]).parent
        for path in self.adm_parameters.values()
    )
    if not branches:
        warnings.warn("The ADM parameters are not in the same directory!")

Metagenomics

Directories, alignment thresholds, and container images used by the metagenomics pipeline. Defaults are derived from a Database config unless you override them.

Metagenomics

Metagenomics(
    metagenomics_dir: str | PathLike = ".",
    *,
    database_dir: str | PathLike | None = None,
    database: Database | None = None,
    amplicon2genome_k=10,
    vsearch_similarity=0.97,
    genomes_base_dir: str | None = None,
    align_to_gtdb_outputs_dir: str | None = None,
    amplicon2genome_db: str | None = None,
    genome_alignment_script: str | None = None,
    vsearch_threads: int = 4,
    rsync_download_dir: str | None = None,
    adtoolbox_singularity: str = ADTOOLBOX_CONTAINERS["singularity_x86"],
    adtoolbox_docker: str = ADTOOLBOX_CONTAINERS["docker_x86"],
    genome_alignment_output: str | None = None,
    csv_reaction_db: str | None = None,
    sra: str | None = None,
    bit_score=40,
    e_value=10**-5,
    protein_db: str | None = None,
    protein_db_mmseqs: str | None = None,
    adm_mapping=E_ADM_MICROBIAL_GROUPS_MAPPING
)

Configuration for core.Metagenomics functionality.

Source code in adtoolbox/configs.py

def __init__(
    self,
    metagenomics_dir: str | os.PathLike = ".",
    *,
    database_dir: str | os.PathLike | None = None,
    database: Database | None = None,
    amplicon2genome_k=10,
    vsearch_similarity=0.97,
    genomes_base_dir: str | None = None,
    align_to_gtdb_outputs_dir: str | None = None,
    amplicon2genome_db: str | None = None,
    genome_alignment_script: str | None = None,
    vsearch_threads: int = 4,
    rsync_download_dir: str | None = None,
    adtoolbox_singularity: str = ADTOOLBOX_CONTAINERS["singularity_x86"],
    adtoolbox_docker: str = ADTOOLBOX_CONTAINERS["docker_x86"],
    genome_alignment_output: str | None = None,
    csv_reaction_db: str | None = None,
    sra: str | None = None,
    bit_score=40,
    e_value=10**-5,
    protein_db: str | None = None,
    protein_db_mmseqs: str | None = None,
    adm_mapping=E_ADM_MICROBIAL_GROUPS_MAPPING,
):
    self.metagenomics_dir = _norm(metagenomics_dir)
    database = database or Database(database_dir=database_dir or self.metagenomics_dir)

    self.k = amplicon2genome_k
    self.vsearch_similarity = vsearch_similarity
    self.genomes_base_dir = genomes_base_dir or _join(self.metagenomics_dir, "Genomes")
    self.align_to_gtdb_outputs_dir = align_to_gtdb_outputs_dir or self.genomes_base_dir
    self.amplicon2genome_db = amplicon2genome_db or database.amplicon_to_genome_db
    self.protein_db = protein_db or database.protein_db
    self.protein_db_mmseqs = (
        protein_db_mmseqs
        or (
            pathlib.Path(protein_db).parent / "protein_db_mmseqs"
            if protein_db
            else database.protein_db_mmseqs
        )
    )
    self.seed_rxn_db = database.reaction_db
    self.genome_alignment_output = genome_alignment_output or _join(self.metagenomics_dir, "Outputs")
    self.bit_score = bit_score
    self.e_value = e_value
    self.vsearch_threads = vsearch_threads
    self.csv_reaction_db = csv_reaction_db or database.csv_reaction_db
    self.sra = sra or _join(self.metagenomics_dir, "SRA")
    self.gtdb_dir_fasta = None
    matches = list(pathlib.Path(self.amplicon2genome_db).rglob(Metagenomics.gtdb_dir))
    if matches:
        self.gtdb_dir_fasta = str(matches[0])
    self.genome_alignment_script = genome_alignment_script or _join(self.metagenomics_dir, "genome_alignment_script.sh")
    self.adtoolbox_singularity = adtoolbox_singularity
    self.adtoolbox_docker = adtoolbox_docker
    self.rsync_download_dir = rsync_download_dir or _join(self.genomes_base_dir, "rsync_download.sh")
    self.adm_mapping = adm_mapping

gtdb_dir class-attribute instance-attribute

gtdb_dir = '*ssu*.fna'

metagenomics_dir instance-attribute

metagenomics_dir = _norm(metagenomics_dir)

k instance-attribute

k = amplicon2genome_k

vsearch_similarity instance-attribute

vsearch_similarity = vsearch_similarity

genomes_base_dir instance-attribute

genomes_base_dir = genomes_base_dir or _join(metagenomics_dir, 'Genomes')

align_to_gtdb_outputs_dir instance-attribute

align_to_gtdb_outputs_dir = align_to_gtdb_outputs_dir or genomes_base_dir

amplicon2genome_db instance-attribute

amplicon2genome_db = amplicon2genome_db or amplicon_to_genome_db

protein_db instance-attribute

protein_db = protein_db or protein_db

protein_db_mmseqs instance-attribute

protein_db_mmseqs = protein_db_mmseqs or (
    parent / "protein_db_mmseqs" if protein_db else protein_db_mmseqs
)

seed_rxn_db instance-attribute

seed_rxn_db = reaction_db

genome_alignment_output instance-attribute

genome_alignment_output = genome_alignment_output or _join(metagenomics_dir, 'Outputs')

bit_score instance-attribute

bit_score = bit_score

e_value instance-attribute

e_value = e_value

vsearch_threads instance-attribute

vsearch_threads = vsearch_threads

csv_reaction_db instance-attribute

csv_reaction_db = csv_reaction_db or csv_reaction_db

sra instance-attribute

sra = sra or _join(metagenomics_dir, 'SRA')

gtdb_dir_fasta instance-attribute

gtdb_dir_fasta = None

genome_alignment_script instance-attribute

genome_alignment_script = genome_alignment_script or _join(
    metagenomics_dir, "genome_alignment_script.sh"
)

adtoolbox_singularity instance-attribute

adtoolbox_singularity = adtoolbox_singularity

adtoolbox_docker instance-attribute

adtoolbox_docker = adtoolbox_docker

rsync_download_dir instance-attribute

rsync_download_dir = rsync_download_dir or _join(genomes_base_dir, 'rsync_download.sh')

adm_mapping instance-attribute

adm_mapping = adm_mapping

Annotation

Annotation

Annotation(
    annotation_dir: str | PathLike = ".", *, metacyc_protein_db: str | None = None
)

Source code in adtoolbox/configs.py

def __init__(self, annotation_dir: str | os.PathLike = ".", *, metacyc_protein_db: str | None = None):
    self.annotation_dir = _norm(annotation_dir)
    self.metacyc_protein_db = metacyc_protein_db or _join(self.annotation_dir, "metacyc_protein_db.fasta")

annotation_dir instance-attribute

annotation_dir = _norm(annotation_dir)

metacyc_protein_db instance-attribute

metacyc_protein_db = metacyc_protein_db or _join(
    annotation_dir, "metacyc_protein_db.fasta"
)

Documentation

Documentation

Documentation(
    documentation_dir: str | PathLike | None = None, *, readme: str | None = None
)

Source code in adtoolbox/configs.py

def __init__(self, documentation_dir: str | os.PathLike | None = None, *, readme: str | None = None):
    self.documentation_dir = _norm(documentation_dir or PKG_DATA)
    self.readme = readme or _join(self.documentation_dir, "README.md")

documentation_dir instance-attribute

documentation_dir = _norm(documentation_dir or PKG_DATA)

readme instance-attribute

readme = readme or _join(documentation_dir, 'README.md')

Studies

Studies

Studies(
    studies_dir: str | PathLike = ".",
    *,
    metagenomics_studies: str | None = None,
    experimental_data_db: str | None = None
)

Source code in adtoolbox/configs.py

def __init__(
    self,
    studies_dir: str | os.PathLike = ".",
    *,
    metagenomics_studies: str | None = None,
    experimental_data_db: str | None = None,
):
    self.studies_dir = _norm(studies_dir)
    self.metagenomics_studies = metagenomics_studies or _join(self.studies_dir, "metagenomics_studies.tsv")
    self.experimental_data_db = experimental_data_db or _join(self.studies_dir, "experimental_data_references.json")
    self.experimental_data_references = self.experimental_data_db

studies_dir instance-attribute

studies_dir = _norm(studies_dir)

metagenomics_studies instance-attribute

metagenomics_studies = metagenomics_studies or _join(
    studies_dir, "metagenomics_studies.tsv"
)

experimental_data_db instance-attribute

experimental_data_db = experimental_data_db or _join(
    studies_dir, "experimental_data_references.json"
)

experimental_data_references instance-attribute

experimental_data_references = experimental_data_db

Utils

Container images and Slurm defaults used by the helpers in utils.

Utils

Utils(
    utils_dir: str | PathLike = ".",
    *,
    slurm_template: str = os.path.join(PKG_DATA, "slurm_template.txt"),
    slurm_executer: str = "",
    slurm_wall_time: str = "24:00:00",
    slurm_job_name: str = "ADToolbox",
    slurm_outlog: str = "ADToolbox.log",
    slurm_cpus: str = "12",
    slurm_memory: str = "100G",
    slurm_save_dir: str | None = None,
    adtoolbox_singularity: str = ADTOOLBOX_CONTAINERS["singularity_x86"],
    adtoolbox_docker: str = ADTOOLBOX_CONTAINERS["docker_x86"]
)

Configuration for utility helpers.

Source code in adtoolbox/configs.py

def __init__(
    self,
    utils_dir: str | os.PathLike = ".",
    *,
    slurm_template: str = os.path.join(PKG_DATA, "slurm_template.txt"),
    slurm_executer: str = "",
    slurm_wall_time: str = "24:00:00",
    slurm_job_name: str = "ADToolbox",
    slurm_outlog: str = "ADToolbox.log",
    slurm_cpus: str = "12",
    slurm_memory: str = "100G",
    slurm_save_dir: str | None = None,
    adtoolbox_singularity: str = ADTOOLBOX_CONTAINERS["singularity_x86"],
    adtoolbox_docker: str = ADTOOLBOX_CONTAINERS["docker_x86"],
) -> None:
    self.utils_dir = _norm(utils_dir)
    self.slurm_template = slurm_template
    self.slurm_executer = slurm_executer
    self.slurm_wall_time = slurm_wall_time
    self.slurm_job_name = slurm_job_name
    self.slurm_outlog = slurm_outlog
    self.slurm_cpus = slurm_cpus
    self.slurm_save_dir = slurm_save_dir or self.utils_dir
    self.slurm_memory = slurm_memory
    self.adtoolbox_singularity = adtoolbox_singularity
    self.adtoolbox_docker = adtoolbox_docker

utils_dir instance-attribute

utils_dir = _norm(utils_dir)

slurm_template instance-attribute

slurm_template = slurm_template

slurm_executer instance-attribute

slurm_executer = slurm_executer

slurm_wall_time instance-attribute

slurm_wall_time = slurm_wall_time

slurm_job_name instance-attribute

slurm_job_name = slurm_job_name

slurm_outlog instance-attribute

slurm_outlog = slurm_outlog

slurm_cpus instance-attribute

slurm_cpus = slurm_cpus

slurm_save_dir instance-attribute

slurm_save_dir = slurm_save_dir or utils_dir

slurm_memory instance-attribute

slurm_memory = slurm_memory

adtoolbox_singularity instance-attribute

adtoolbox_singularity = adtoolbox_singularity

adtoolbox_docker instance-attribute

adtoolbox_docker = adtoolbox_docker