Manual

If you have not yet installed macrel, see install.

Macrel uses a subcommand interface. You run macrel COMMAND ... with the COMMAND specifying which components of the pipeline you want to use.

Subcommands

• peptides: to classify a fasta containing peptide sequences in a fasta file,
• contigs: to input pre-assembled contigs in a fasta file,
• reads: to input reads in fastQ format (Macrel accepts single- and paired-end reads),
• abundance: to measure abundance of a peptides fasta file using a given fastQ file,
• get-smorfs: to predict small genes from a contigs fasta file.
• query-ampsphere: to query the AMPsphere database.

Mandatory input flags

• --out: Folder destination to output [for all subcommands]
• --file-output: Can be used in the get-smorfs subcommand to output just the final file. If this is used, --out is no longer mandatory
• --fasta: Path to the input FASTA file. This is used in both the peptides subcommands (where the file is expected to contain short amino-acid sequences) and in the contigs/get-smorfs subcommands (where the file is expected to contain longer nucleotide contigs)
• --reads1/--reads2: Path to the input FastQ files [for reads subcommand]

Optional flags

• --threads (-t): Specify the number of cpus used
• --cluster: Pre-cluster the smORFs (at 100%% identity) to avoid repeats
• --tag: If used, then all the output files will incorporate it.
• --mem: Used during assembly to specify the percent of RAM used (1-0)
• --tmpdir: Temporary directory to use (default: $TMPDIR in the environment or /tmp)
• --force: Potentially over-write existing output files
• --keep-fasta-headers: Keep complete FASTA headers [get-smorfs command]
• --keep-negatives: Output a table with all sequences (default is to only output putative AMPs)
• --log-file: Output a logfile with log information from macrel (instead of printing to the console)
• --log-append: If set, the log file is appended to (rather than overwritten)

Also, macrel --version will show the version of macrel installed.

Examples

To run these examples, first download the example sequences from github, or by running:

macrel get-examples

The main output file generated by Macrel consists of a table with 6 columns containing the: sequence access code, peptide sequence, classification of peptide accordingly (cationic or anionic) and structure (linear or disulfide bond forming), the probability associated with the AMP prediction, hemolytic activity prediction and probability associated to hemolytic activity prediction. All peptides outputted in this table are considered predicted AMPs (p > 0.5) by Macrel, although peptides predicted with probabilities closer to 1 are more likely to be active. Similarly, the hemolytic activity is more likely to be verified in those peptides with probabilites associated to the prediction closer to 1.

Note that there is not a general rule to find true AMPs or hemolytic peptides, then peptides predicted with probabilites around 0.5 also can show activity. In our tests during training true peptides could be found with probabilities ranging from 0.5 to 1, although most of them with probabilites above 0.6

To run Macrel on peptides, use the peptides subcommand:

macrel peptides \
    --fasta example_seqs/expep.faa.gz \
    --output out_peptides

In this case, we use example_seqs/expep.faa.gz as the input sequence. This should be an amino-acid FASTA file. The outputs will be written into a folder called out_peptides, and Macrel will 4 threads. An example of output using this mode can be found at test/peptides/expected.prediction.

To run Macrel on contigs, use the contigs subcommand:

macrel contigs \
    --fasta example_seqs/excontigs.fna.gz \
    --output out_contigs

In this example, we use the example file excontigs.fna.gz which is a FASTA file with nucleotide sequences, writing the output to out_contigs. An example of output using this mode can be found at test/contigs/expected.prediction and test/contigs/expected.percontigs, with the latter you can also calculate AMP density.

Note that the results per contig are only produced when not using the option cluster.

Additionally to the prediction table, this mode also produces two files containing general gene prediction information in the contigs and a fasta file containing the predicted and filtered small genes (≤ 100 amino acids).

To run Macrel on paired-end reads, use the reads subcommand:

macrel reads \
    -1 example_seqs/R1.fq.gz \
    -2 example_seqs/R2.fq.gz \
    --output out_metag \
    --outtag example_metag

The paired-end reads are given as paired files (here, example_seqs/R1.fq.gz and example_seqs/R2.fq.gz). If you only have single-end reads, you can omit the -2 argument. An example of outputs using this mode can be found at test/reads/expected.prediction, test/reads/expected.smorfs.faa and test/contigs/expected.percontigs, with the latter you can also calculate AMP density.

Additionally to the prediction table, this mode also produces a contigs fasta file, and the two files containing general gene prediction coordinates and a fasta file containing the predicted and filtered small genes (≤ 100 amino acids).

To run Macrel to get abundance profiles, you only need the short reads file and a reference with peptide sequences. Use the abundance subcommand:

macrel abundance \
    -1 example_seqs/R1.fq.gz \
    --fasta example_seqs/ref.faa.gz \
    --output out_abundance \
    --outtag example_abundance

This mode returns a table of abundances containing two columns, the first with the name of the AMPs and the second with the number of reads mapped back to each peptide using the given reference. An example of this output using the example file can be found at test/abundances/expected.abundance.txt.

AMPSphere Querying

Macrel also supports querying the AMPSphere database (described in Santos-Júnior et al., 2024). To do so, use the query-ampsphere subcommand:

macrel query-ampsphere \
    --fasta example_seqs/pep8.faa \
    --output out_ampsphere

Querying Modes

1. Exact matching: This is the default mode, and it will search for exact matches of the input sequences in the AMPSphere database. This is the fastest mode (starting with version 1.5.0, can be called with the --local flag to use a local database).
2. MMSeqs2: This mode uses MMSeqs2 to perform approximate matching of the input sequences in the AMPSphere database. This is slower than exact matching but can find more matches. To use this mode, pass the --query-mode=mmseqs flag.
3. HMMER: This mode uses HMMER to search for homologs of the input sequences in the AMPSphere database. This is the slowest mode but can find more distant homologs. To use this mode, pass the --query-mode=hmm flag.

Remote vs. local

By default, macrel uses the remote API to query the AMPSphere database. This is the fastest way to query the database for a small number of peptides, but it requires an internet connection.

If you want to use a local database use the --local flag:

macrel query-ampsphere \
    --fasta example_seqs/pep8.faa \
    --query-mode mmseqs \
    --local \
    --output out_ampsphere

This will download the AMPSphere database and use it to query the input sequences. The database will stored in ~/.cache/macrel/ampsphere (you can change it with the --cache-dir flag). To use the MMSeqs2 or HHMER modes, you need to have the respective software installed on your system (conda install bioconda::mmseqs2 or conda install bioconda::hmmer).

As MMSeqs2 is a heuristic method, the results may vary slightly between the local and remote mode (as versions of MMSeqs2 may differ).