Overview

AMALGKIT (/əm`ælgkit/) integrates public SRA/GSA and private FASTQ data for cross-species gene-expression analysis. It supports sample selection, quantification, normalization, and filtering to help reduce technical bias; the resulting comparisons still depend on the input data and biological design.

flowchart LR
    SRA[SRA metadata] --> select
    GSA[GSA metadata] --> select
    select --> getfastq
    FASTQ[Private FASTQ] --> integrate
    integrate -->|explicit metadata path| getfastq
    getfastq --> quant --> merge
    merge --> finalize
    merge --> cstmm --> wsfilter --> csfilter --> finalize
    Orthologs[BUSCO / orthogroups] --> cstmm
    Orthologs --> csfilter

Loading

CSTMM and the filters are optional; filters may be used in either order.

Installation

AMALGKIT requires Python 3.11 or later on Linux or macOS; CI covers Python 3.11–3.14.

# Latest default-branch version in an isolated environment
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade git+https://github.com/kfuku52/amalgkit

# Or, in a separate shell, the packaged Bioconda version
mamba create -n amalgkit -c conda-forge -c bioconda --strict-channel-priority amalgkit
mamba activate amalgkit

amalgkit --version
amalgkit help metadata

getfastq requires SeqKit and fastp unless --fastp no is used. SRA and private-input runs also require fasterq-dump from sra-tools >= 3; GSA-only runs use native FASTQ retrieval. quant requires kallisto for short reads or Oarfish for long reads, including automatic backend selection. See installation and dependencies.

Patch updates are available from the default branch and listed in CHANGELOG.md. Tags, GitHub Releases, and Bioconda recipe updates are created only when the patch component is zero (for example, 0.17.0). Record both the version and source revision for reproducible analyses.

Getting started

The yeast tutorial walks through metadata review, selection, quantification, and cross-species filtering. Its bundled FASTAs are small BUSCO-focused examples, not full transcriptomes.

amalgkit dataset --name yeast --out_dir ./demo

For your own data, start an empty workspace and follow its generated guide:

amalgkit dataset --name init --out_dir ./work

Review the rules before selection: the base, test, plantae, and vertebrate presets currently select flower,leaf,root. Other groups, such as liver, require edits to both the group parameter and relevant rules. See selection.

Before quantification, supply one reference transcriptome per species under fasta/ and use --build_index yes, or prepare matching backend indices under index/. These references/indices are not downloaded by quant.

# After preparing references and selected metadata in work/
amalgkit getfastq --out_dir ./work
amalgkit quant --out_dir ./work --build_index yes
amalgkit merge --out_dir ./work
amalgkit finalize --out_dir ./work --input_dir ./work/merge --metadata ./work/merge/metadata.tsv --batch_effect_alg no

For private FASTQ, pass the generated integrate metadata explicitly through getfastq, quant, and merge. For CSTMM or long-read outputs, follow metadata and normalization: CSTMM FPKM needs the original library-size metadata, and Oarfish requires a compatible --norm, such as log2p1-none.

Command guides

Stage	Commands
Prepare inputs	dataset, metadata, integrate, select
Quantify	getfastq, quant, merge
Normalize and filter	busco, cstmm, wsfilter, csfilter, finalize
Check and recover	sanity, rerun

See parallel processing for CPU budgets and command-specific batch units. Developer setup and structured logging are covered in architecture and development. The Wiki home also maps legacy config, curate, and csca commands to their replacements.

Citation

Although AMALGKIT supports novel unpublished functions, some functionalities including metadata curation, expression level quantification, and further curation steps have been described in this paper, in which we reported the transcriptome amalgamation of 21 vertebrate species.

Fukushima K*, Pollock DD*. 2020. Amalgamated cross-species transcriptomes reveal organ-specific propensity in gene expression evolution. Nature Communications 11: 4459 (DOI: 10.1038/s41467-020-18090-8) open access

Licensing

amalgkit is MIT-licensed. See LICENSE for details.