Commands

Command Reference

SGAtools has three main functions and one convenience wrapper:

Command	Input	Main result
sga-mapper	FAA or FAA directory	per-sample and aggregate mapper TSVs
sga-classify --onlyalign	FNA/FAA file, or a directory containing one format	per-sample and batch alignments
sga-classify	FNA or FNA directory, optionally matching FAA	placement, taxonomy, ANI, species assignment
sga-run	FNA or FNA directory, optionally matching FAA	Prodigal + mapper + classifier

The old command name sga-map remains an alias for sga-mapper.

sga-mapper

Annotate predicted proteins against the SAR11 Genome Atlas OG HMM library.

sga-mapper proteins.faa --output-dir results/mapper --threads 4
sga-mapper faa_dir/ --output-dir results/mapper_batch --threads 8

Argument	Required	Default	Description
proteins	yes		Amino-acid FASTA or directory containing FAA files.
-o, --output-dir	yes		Output directory. --output is a compatibility alias.
--config	no	package defaults	Configuration YAML.
--hmm-archive	no	configured local/remote archive	Explicit OG HMM archive.
--hmm-library	no	prepared library	Existing HMM library; skips archive extraction.
--metadata	no	data/mapper/og_metadata.tsv	OG metadata table.
--thresholds	no	data/mapper/og_thresholds.tsv	OG cutoff table.
--evalue-cutoff	no	1e-5	Override the trusted/noise cutoff for this run.
--domtblout	no	generated	Reuse an HMMER domtblout; skips hmmsearch.
--work-dir	no	OUTPUT/work	HMMER output and temporary files.
--threads	no	1	HMMER CPU count.
--no-download	no	off	Do not download a missing HMM archive.
--version	no		Print the package version.

Main output:

results/mapper/
├── sga_mapper.tsv
├── run_report.json
└── work/
    ├── hmmsearch.domtblout
    ├── hmmsearch.log
    └── ...                  # extracted HMM copy is removed after success

sga_mapper.tsv contains one row for every input protein. The principal columns are protein_id, OG_ID, KO, KO_name, COG, COG_name, PFAMs, PFAM_names, atlas_link, assignment_source, confidence, evalue, bitscore, hmm_coverage, and query_coverage. This is a compact summary containing every input protein. Proteins without a valid OG assignment retain only protein_id; OG_ID and the other annotation fields are empty. Assignment and rejection counts are recorded in run_report.json.

A directory containing both FAA and FNA files is rejected. Place each format in a separate directory. The number of selected input files is printed before processing begins.

Directory mode combines collision-safe copies of all protein records and runs one hmmsearch. Original protein IDs are restored in public outputs. It writes batch_sga_mapper.tsv, batch_report.json, and SAMPLE/sga_mapper.tsv plus SAMPLE/run_report.json for every input.

sga-classify --onlyalign

Create the trimmed SAR11_165 query alignment without placement, taxonomy, or ANI. The input can be either nucleotide or protein FASTA.

sga-classify proteins.faa --onlyalign --output-dir results/alignment --threads 4
sga-classify genome.fna --onlyalign --output-dir results/alignment --threads 4
sga-classify faa_dir/ --onlyalign --output-dir results/alignment_batch --threads 8

Argument	Required	Default	Description
input	yes		FNA/FAA, or a directory containing only FNA or only FAA files.
--onlyalign	yes		Stop after writing the alignment.
-o, --output-dir	yes		Output directory.
--gff	no	OUTPUT/work/gff/query.gff	GFF path for one FNA, or GFF output directory in batch mode.
--prodigal-mode	no	single	Prodigal mode: single or meta.
--config	no	package defaults	Configuration YAML.
--marker-hmm-archive	no	configured local/remote archive	SAR11_165 marker HMM archive.
--marker-domtblout	no	generated	Reuse marker HMMER results.
--work-dir	no	OUTPUT/work	Intermediate marker files.
--per-sample-details	no	off	Retain per-sample files in directory mode.
--cleanup-work	no	off	Remove generated work after success; preserve it after failure.
--threads	no	1	Threads passed to HMMER and other tools.
--no-download	no	off	Do not download marker HMMs.
--version	no		Print the package version.

Main outputs are OUTPUT/alignment.faa and OUTPUT/marker_summary.tsv. The alignment is a single trimmed sequence with the same 44,148 columns as the classifier reference alignment. The summary has one row for every marker with found or missing status. Generated marker-search and alignment files remain under OUTPUT/work/ unless --cleanup-work is specified.

Directory mode runs Prodigal concurrently when required, performs one marker HMM search on the combined proteins, and invokes MAFFT once per marker with all queries for that marker. It writes batch_alignment.faa, batch_marker_summary.tsv, and batch_report.json. Per-sample files are written only with --per-sample-details.

sga-classify

Run the complete classifier workflow from a nucleotide genome. If --proteins is omitted, Prodigal is run automatically. If it is supplied, the FAA is validated and reused.

sga-classify genome.fna --output-dir results/classifier --threads 1
sga-classify genome.fna --proteins proteins.faa \
  --output-dir results/classifier --threads 1
sga-classify fna_dir/ --proteins faa_dir/ \
  --output-dir results/classifier_batch --threads 8

Argument	Required	Default	Description
input	yes		Nucleotide genome FASTA or directory containing FNA files.
--proteins	no	Prodigal output	Existing FAA, or a matching FAA directory for batch input.
-o, --output-dir	yes		Output directory.
--gff	no	OUTPUT/work/gff/query.gff	Prodigal GFF path, or GFF output directory in batch mode.
--prodigal-mode	no	single	Prodigal mode: single or meta.
--config	no	package defaults	Configuration YAML.
--marker-hmm-archive	no	configured local/remote archive	SAR11_165 marker HMM archive.
--marker-domtblout	no	generated	Reuse marker HMMER results.
--placement-engine	no	epa-ng	EPA-ng placement; retained for explicitness.
--work-dir	no	OUTPUT/work	Alignment, placement, ANI, and logs.
--per-sample-details	no	off	Write per-sample result directories in batch mode.
--cleanup-work	no	off	Remove generated work after success; preserve it after failure.
--threads	no	1	Threads for external tools.
--no-download	no	off	Do not download marker HMMs or reference genomes.
--version	no		Print the package version.

Main outputs:

results/classifier/
├── sga_classification.tsv
├── marker_summary.tsv
├── nearest_genomes.tsv
├── classifier_run_report.json
└── work/
    ├── proteins/
    ├── gff/
    ├── alignment/
    ├── markers/
    ├── placement/
    └── fastani/

The classification table reports family, genus, subclade, and species. Every rank has its own assignment_source and confidence. Species is assigned only when the nearest reference passes the configured ANI threshold, which is 95% by default. ani_status distinguishes a species-threshold pass, a below-threshold result, missing results, genus conflict, missing reference species, and cases where ANI was not calculated.

classification_status is SAR11 only for a trusted node in a configured SAR11 family, SAR11-related (Clade IV) for an assigned Clade IV subclade or configured legacy Clade IV edge, not_SAR11 for an edge containing only outgroup descendants, and unresolved for insufficient markers or a SAR11/outgroup boundary edge. Placement and ANI are skipped below 50% marker recovery; ANI is also skipped for not_SAR11 and boundary-edge unresolved results.

Directory mode places every marker-sufficient query in one multi-query EPA-ng invocation. Queries with identical ANI reference sets share one fastANI invocation; independent reference groups run concurrently within the requested thread budget. Aggregate outputs are batch_classification.tsv, batch_nearest_genomes.tsv, batch_marker_summary.tsv, and batch_report.json. Aggregate detail tables start with a query column; per-sample result directories are opt-in with --per-sample-details.

Exact trusted-edge assignments remain primary. If subclade is assigned but genus is not, the closest trusted ancestor genus may be used when its known reference genera are unique and satisfy the configured metadata coverage. These assignments are marked trusted ancestor edge and provisional.

The result TSV excludes repeated tool/database versions. JSON reports contain the schema version, tool/database and external-tool versions, and SHA-256 hashes for the config, tree, taxonomy, trusted nodes, marker order, and EPA model.

--cleanup-work runs only after successful completion. Failed runs retain all work, and a work directory that was already non-empty before startup is left untouched to avoid deleting unrelated files. Command logs are consolidated to run.log before generated work is removed.

Classification is conservative: marker recovery below 0.50 produces unresolved and skips placement/ANI; a clear outgroup is not_SAR11; a SAR11/outgroup boundary is unresolved; and assigned Clade IV subclades are SAR11-related (Clade IV). For not_SAR11, family, genus, subclade, and species are empty.

sga-run

Run Prodigal, SGAmapper, and SGAclassifier in one command. This is a convenience wrapper; the three component commands remain independently usable.

sga-run genome.fna --output-dir results/sample --threads 4
sga-run genome.fna --proteins proteins.faa --output-dir results/sample --threads 4
sga-run fna_dir/ --output-dir results/batch --threads 8

Argument	Required	Default	Description
genome	yes		Nucleotide genome FASTA or directory containing FNA files.
-o, --output-dir	yes		Integrated output directory.
--proteins	no	predicted proteins	Existing FAA, or matching FAA directory in batch mode; skips Prodigal.
--gff	no	OUTPUT/genes.gff	Prodigal GFF path, or GFF output directory in batch mode.
--config	no	package defaults	Configuration YAML.
--prodigal-mode	no	single	Prodigal mode.
--placement-engine	no	epa-ng	EPA-ng placement; the only supported backend.
--threads	no	1	Threads for external tools.
--per-sample-details	no	off	Retain per-sample classifier files in batch mode.
--cleanup-work	no	off	Remove generated work after a successful run.
--no-download	no	off	Do not download external DB assets.
--version	no		Print the package version.

Output layout:

results/sample/
├── work/
│   ├── proteins/
│   └── gff/
├── mapper/sga_mapper.tsv
├── classifier/sga_classification.tsv
├── classifier/nearest_genomes.tsv
├── report.json
└── run.log                    # assembled after successful completion

Batch mode stores generated proteins and GFF files under work/. Per-sample classifier results are written only with --per-sample-details; aggregate TSV/report files remain the default. The top-level report.json records the component output directories and sample list, while run.log contains the completed integrated workflow log.

sga-db

sga-db manages the external OG and marker HMM assets.

sga-db validate
sga-db download --no-download
sga-db prepare-hmm
sga-db download-marker-hmm --no-download

Use sga-db --help and the subcommand help for all database-specific options.

Common behavior

If a required OG HMM, marker HMM, or reference genome archive is absent, the command downloads it automatically from the configured Zenodo record and saves it under ~/.cache/sga-tools/ (or $SGA_CACHE_DIR). Existing assets are reused. --no-download disables this behavior and reports an error when an asset is missing.

All commands validate FASTA alphabet before external tools run. Mapper input must be FAA; full classifier and sga-run input must be FNA. A clear mismatch produces an actionable error. Interactive terminals show Rich spinners for long-running commands and a determinate bar for marker-wise MAFFT. Detailed external output is kept in step logs while a run is active. For a successful integrated run, run.log is assembled first and the individual step logs are then removed.