MitoTrawlR

MitoTrawlR is a modular R package for recovering mitochondrial sequences from short-read data and preparing homologous mitochondrial markers for phylogenetic analysis. It coordinates established external programs for sensitive read recruitment, assembly, sequence search, annotation, alignment, trimming, and tree inference.

The supplied workflow supports:

1. Building a mitochondrial reference genome and marker set from GenBank, GFF3, or a tabular annotation.
2. Iteratively recruiting reads with BBMap and assembling them with SPAdes and CAP3.
3. Identifying and extracting reference-homologous mitochondrial markers and detecting tRNAs with tRNAscan-SE.
4. Aligning homologous markers across samples with MAFFT.
5. Trimming and assessing alignments with TrimAl and PhyloProcessR utilities.
6. Building reference-ordered marker sets and concatenated mitochondrial matrices.
7. Inferring a partitioned maximum-likelihood tree with IQ-TREE and plotting marker recovery.

MitoTrawlR accepts FASTQ files but does not currently perform adapter removal or read-quality filtering. Supply reads that have already passed the preprocessing appropriate for the project. Its oriented FASTA assemblies and GFF3 files are analysis products, not automatically validated submissions for GenBank or another archive.

Package relationship

MitoTrawlR and PhyloProcessR are separate packages in the PhyloForge organization. MitoTrawlR owns mitochondrial-specific reference construction, recruitment, assembly selection, annotation, and workflow orchestration. PhyloProcessR supplies reusable sequence I/O, alignment, trimming, and phylogenomic-processing utilities.

MitoTrawlR depends on PhyloProcessR, but PhyloProcessR does not depend on MitoTrawlR. Marker FASTA files, PHYLIP alignments, feature tables, and sample identifiers provide the interoperability boundary; the packages are not intended to be merged.

Prerequisites

MitoTrawlR requires R 4.0 or later. R dependencies are declared in DESCRIPTION. External programs are required only by the stages that invoke them.

Stage	External programs
Iterative recruitment and assembly	BBMap, SPAdes, CAP3, BLAST+
Annotation	BLAST+, CAP3, tRNAscan-SE
Marker alignment	MAFFT
Optional trimming	TrimAl
Optional phylogeny	IQ-TREE 3

Create the complete environment

Clone the repository to obtain the Conda environment and workflow templates:

git clone https://github.com/PhyloForge/MitoTrawlR.git
cd MitoTrawlR/setup-configuration_files

Create and activate the environment:

conda env create --file environment.yml
conda activate MitoTrawlR

The helper script performs the same environment creation step:

./create_mitotrawlr_environment.sh

The environment is written with packages available through Conda on Linux and macOS. Platform-specific solver availability can differ, so preserve the resolved environment export or container digest used for a published analysis.

Install the R packages

Install PhyloProcessR first, followed by MitoTrawlR:

install.packages("remotes")
remotes::install_github("PhyloForge/PhyloProcessR")
remotes::install_github("PhyloForge/MitoTrawlR", dependencies = TRUE)

For a local checkout inside the prepared environment:

remotes::install_local(".", upgrade = "never", dependencies = FALSE)

Do not reinstall a moving development branch inside an analysis script. Record the package versions or Git commits used for each run.

Check the programs required by the standard workflow:

MitoTrawlR::setupCheck()

NULL path arguments search PATH. A Conda environment can be checked explicitly with:

MitoTrawlR::setupCheck(
  anaconda.environment = Sys.getenv("CONDA_PREFIX")
)

Run the supplied workflow

Copy and edit both files in setup-configuration_files/:

• mitotrawlr_configuration-file.R
• mitotrawlr_workflow.R

Set full paths for the project, processed reads, reference FASTA, annotation, and optional program overrides. Then run:

Rscript /absolute/path/to/mitotrawlr_workflow.R

The workflow does not install or update R packages at runtime. Existing output files are reused when overwrite = FALSE, subject to the behavior documented for each stage.

The principal output directories are:

Directory	Contents
reference/	Reference genome, markers, and parsed feature table
draftContigs/	Recovered mitochondrial assembly contigs by sample
Annotations/	Marker FASTA files, used contigs, CSV summaries, and optional GFF3
Alignments/	Unaligned markers and per-marker alignments
genomes/	Concatenated matrices, reference-order markers, oriented assemblies, logs, and figures
Phylogeny/	IQ-TREE input partitions and results

Prepare a reference

For GFF3 input, download the mitochondrial sequence as FASTA and its annotation as a standard nine-column GFF3 file. Then run:

MitoTrawlR::buildReference(
  reference.fasta = "reference_mitogenome.fasta",
  annotation.file = "reference_mitogenome.gff3",
  annotation.type = "gff",
  reference.name = "reference",
  overwrite = TRUE
)

This creates:

• reference/refGenome.fa
• reference/refMarkers.fa
• reference/referenceTable.txt

For a GenBank flat file, use annotation.type = "genbank"; this optional path requires the Bioconductor package genbankr. Table input requires columns compatible with the documented feature table.

Compose a modular analysis

The complete workflow is a reference implementation. Functions can also be called independently:

MitoTrawlR::buildReference(...)
MitoTrawlR::mitochondrialCapture(...)
MitoTrawlR::annotateMitoContigs(...)
MitoTrawlR::markerAlignment(...)
MitoTrawlR::trimMitoAlignments(...)
MitoTrawlR::alignMitogenomes(...)
MitoTrawlR::buildMitogenomes(...)
MitoTrawlR::buildPhylogeny(...)

Use explicit package namespaces when MitoTrawlR and PhyloProcessR are attached together because both packages retain some legacy wrapper names such as runSpades() and runCap3().

Development status

The iterative recruitment strategy and downstream annotation heuristics are being evaluated in a comparative benchmark. Sensitivity to phylogenetically divergent references should be treated as a testable method hypothesis, not an established performance claim.

Citation and license

Citation metadata will be added before a formal software release. MitoTrawlR is distributed under the GNU General Public License, version 3 or later.