Home

SAR11 Genome Atlas Tools (SGAtools) user guide

SGAtools provides three workflows for the SAR11 Genome Atlas. This page is the self-contained starting point for installation, inputs, options, outputs, and classification rules.

Install

For the released package:

conda create -n sga-tools \
  -c conda-forge \
  -c bioconda \
  --strict-channel-priority \
  sar11-genome-atlas-tools
conda activate sga-tools

SGAtools itself is published on the stsnsn Anaconda.org channel. Bioconda and conda-forge provide its native and general-purpose dependencies.

Check the installation:

sga-db --version
sga-mapper --version
sga-classify --version
sga-run --version

Quick start

The shortest useful examples are below. Required database files are downloaded automatically on the first run and reused from the user cache afterwards.

Map a protein FASTA to SAR11 Genome Atlas OGs:

sga-mapper proteins.faa -o results/mapper

Create a SAR11_165 alignment only:

sga-classify proteins.faa --onlyalign -o results/alignment

Run full classification from a nucleotide genome:

sga-classify genome.fna -o results/classifier

Run the integrated workflow from a nucleotide genome:

sga-run genome.fna -o results/run

For multiple genomes, pass a directory instead of a file:

sga-run fna_dir/ -o results/batch --threads 8

Database files and cache

The first command that needs a missing asset downloads it from the SGAtools Zenodo record and reuses it thereafter. The writable default cache is:

~/.cache/sga-tools/

Set SGA_CACHE_DIR to use another location. The three runtime archives are:

Archive	Used by
SAR11_Orthogroups_4577.hmm.tar.gz	sga-mapper
SAR11_165_marker_hmms.tar.gz	sga-classify
fna_files.tar.gz	nearest-genome fastANI

Existing files are verified and reused. To prefetch assets:

sga-db download
sga-db download-marker-hmm

If a large download ends with an MD5 mismatch, retry with curl or wget as shown in the error message. --no-download makes a missing asset an error.

Input formats

Command	Single input	Directory input
sga-mapper	FAA	FAA files
sga-classify --onlyalign	FNA or FAA	FNA files only, or FAA files only
sga-classify	FNA, optional FAA	FNA files, optional matching FAA files
sga-run	FNA, optional FAA	FNA files, optional matching FAA files

Directory mode shares HMM searches, marker-wise MAFFT, multi-query EPA-ng, and grouped fastANI. A directory containing both FAA and FNA files is rejected; place each format in a separate directory. The selected file count is also printed, and a directory with no matching files is an error.

sga-mapper

Search proteins against SAR11 Genome Atlas OG HMMs and write one row per input protein. Unassigned proteins remain in the TSV with only protein_id filled.

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

Option	Default	Description
proteins	required	FAA file or FAA directory
-o, --output-dir, --output	required	Output directory
--config	package defaults	Configuration YAML
--hmm-archive	configured archive	Explicit OG HMM archive
--hmm-library	prepared library	Existing pressed HMM library
--metadata	configured table	OG metadata TSV
--thresholds	configured table	OG cutoff TSV
--evalue-cutoff	1e-5	Override trusted/noise cutoff
--domtblout	generated	Reuse HMMER results and skip hmmsearch
--work-dir	OUTPUT/work	Temporary files and logs
--threads	1	HMMER CPU count
--no-download	off	Do not fetch a missing HMM archive
--version		Print version and exit

Single output is sga_mapper.tsv with run_report.json. Directory mode adds batch_sga_mapper.tsv, batch_report.json, and one output directory per sample.

sga-classify --onlyalign

Extract SAR11_165 markers and create the 44,148-column trimmed alignment. It does not run placement, taxonomy, or ANI.

sga-classify proteins.faa --onlyalign -o results/alignment --threads 4
sga-classify fna_dir/ --onlyalign -o results/alignment_batch --threads 8

Option	Default	Description
input	required	FNA/FAA file, or a directory containing one format
--onlyalign	required	Stop after alignment
-o, --output-dir, --output	required	Output directory
--gff	OUTPUT/work/gff/query.gff	Prodigal GFF, or batch GFF directory
--prodigal-mode	single	single or meta Prodigal mode
--config	package defaults	Configuration YAML
--marker-hmm-archive	configured archive	Marker HMM archive
--marker-domtblout	generated	Reuse marker HMMER results
--work-dir	OUTPUT/work	Intermediate marker files
--per-sample-details	off	Retain per-sample files in directory mode
--cleanup-work	off	Remove generated work only after success
--threads	1	External-tool thread budget
--no-download	off	Do not fetch marker HMMs
--version		Print version and exit

Outputs are alignment.faa and marker_summary.tsv; directory mode also writes batch_alignment.faa, batch_marker_summary.tsv, and batch_report.json.

sga-classify

For FNA, run Prodigal when --proteins is omitted, extract markers, align, place with EPA-ng, assign taxonomy, and calculate nearest-genome ANI.

sga-classify genome.fna -o results/classifier --threads 8
sga-classify fna_dir/ --proteins faa_dir/ -o results/classifier_batch --threads 8

Option	Default	Description
input	required	FNA file or FNA directory
--proteins	Prodigal output	Existing FAA, or matching FAA directory
-o, --output-dir, --output	required	Output directory
--gff	OUTPUT/work/gff/query.gff	Prodigal GFF, or batch GFF directory
--prodigal-mode	single	single or meta Prodigal mode
--config	package defaults	Configuration YAML
--marker-hmm-archive	configured archive	Marker HMM archive
--marker-domtblout	generated	Reuse marker HMMER results
--placement-engine	epa-ng	EPA-ng only; retained for explicitness
--work-dir	OUTPUT/work	Alignment, placement, ANI, and logs
--per-sample-details	off	Retain per-sample result directories
--cleanup-work	off	Remove generated work only after success
--threads	1	External-tool thread budget
--no-download	off	Do not fetch marker/reference assets
--version		Print version and exit

Main outputs are sga_classification.tsv, marker_summary.tsv, nearest_genomes.tsv, and classifier_run_report.json. The query alignment is written under work/alignment/. Directory mode writes aggregate batch_classification.tsv, batch_nearest_genomes.tsv, batch_marker_summary.tsv, and batch_report.json. Per-sample directories are opt-in.

sga-run

Run Prodigal, mapper, and classifier as one workflow. It accepts FNA and can reuse a supplied FAA.

sga-run genome.fna -o results/run --threads 8
sga-run fna_dir/ --proteins faa_dir/ -o results/batch_run --threads 8

Option	Default	Description
genome	required	FNA file or FNA directory
-o, --output-dir	required	Integrated output directory
--proteins	predicted proteins	Existing FAA, or matching FAA directory
--gff	OUTPUT/genes.gff	Prodigal GFF, or batch GFF directory
--config	package defaults	Configuration YAML
--prodigal-mode	single	single or meta Prodigal mode
--placement-engine	epa-ng	EPA-ng only
--threads	1	External-tool thread budget
--per-sample-details	off	Retain per-sample classifier files in batch mode
--cleanup-work	off	Remove generated work after a successful run
--no-download	off	Do not fetch external DB assets
--version		Print version and exit

Generated proteins and GFF files are stored under work/. Output also includes mapper/, classifier/, report.json, and run.log. Batch classifier output is aggregate by default; per-sample files require --per-sample-details.

sga-db

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

Use sga-db --help and each subcommand's --help for database-specific options. validate checks the bundled manifest; download fetches the OG HMM archive; download-marker-hmm fetches SAR11_165 marker HMMs; and prepare-hmm presses a local OG HMM library.

Subcommand option	Description
--version	Print package version and exit
validate --config	Configuration YAML
validate --manifest	Manifest JSON to validate
validate --root	Root directory used to resolve manifest files
download --config	Configuration YAML
download --archive	Use an explicit OG HMM archive
download --output-dir	Download destination directory
download --url	Override the configured archive URL
download --no-download	Require a local archive
prepare-hmm --config	Configuration YAML
prepare-hmm --archive	Use an explicit archive
prepare-hmm --output-dir	Extraction destination; default tmp/hmm
prepare-hmm --no-press	Extract without running hmmpress
download-marker-hmm --config	Configuration YAML
download-marker-hmm --archive	Use an explicit marker archive
download-marker-hmm --no-download	Require local marker HMMs

Classification rules

Status	Meaning
SAR11	Placement is within a trusted SAR11 family region
SAR11-related (Clade IV)	Placement is in configured Clade IV edges
not_SAR11	Clear outgroup placement; ANI is skipped
unresolved	Marker fraction below 0.50 or mixed SAR11/outgroup boundary

When marker fraction is below 0.50, placement and ANI are skipped. For not_SAR11, family, genus, subclade, and species are empty. Formal species assignment requires ANI >=95% by default, sufficient aligned fraction, and a reference genome with a registered species name.

Logs and troubleshooting

Progress is written to stderr. Rich terminals show spinners and bars; non-interactive runs show compact messages. report.json and per-step logs record provenance. A successful sga-run assembles run.log.

For an MD5 mismatch on a large archive, remove the incomplete .part file and use the curl or wget retry command printed by the error. For EPA-ng SIGKILL, inspect the work/placement/epa-ng.log path printed in the error. Use --no-download when all required assets are already cached.

See Example Tests for reproducible runs with public FAA and FNA files, Reference Data for database details, and Commands for the full option reference.