Frequently Asked Questions • MitoPilot

How do I fix a specific error message?

Can I annotate my own mitogenome assemblies with MitoPilot?

Can MitoPilot find the mitogenome in my whole-genome assembly?

Yes. Create the project with new_project_userAsmb(find_mitogenome = TRUE) and supply a MitoFinder database for your clade via mitofinder_db. Each sample’s contigs are BLASTed against the metazoan mitogenome database bundled with MitoPilot, the best candidates are confirmed by annotating them with MitoFinder, and only confirmed contigs continue through the pipeline.

The search is built for large inputs: MitoPilot drops contigs shorter than 500 bp, then splits the rest of the FASTA into chunks and searches them in parallel. The largest assembly tested held 1.4 million contigs.

MitoPilot filters out nuclear mitochondrial insertions (NUMTs) by requiring the BLAST hit to cover at least half the contig’s own length. A nuclear scaffold carrying a mitochondrial insertion matches only a sliver of itself, so it is rejected.

See “Finding the mitogenome in a whole assembly” for details.

Can MitoPilot circularize my mitogenome assemblies?

Yes, if the ends of a contig overlap by at least 220 bp and the two copies are at least 99% identical. Both thresholds are adjustable.

Create the project with new_project_userAsmb(attempt_circularization = TRUE). During the Assemble module MitoPilot BLASTs each contig against itself, trims the redundant overlap, and relabels that contig circular. If you supplied raw reads, it also maps them across the new junction and keeps the assembly linear unless enough reads span it, so a repeat is not mistaken for a real circle.

It cannot invent sequence that is missing. A contig with a genuine gap between its ends stays linear no matter how the thresholds are set.

Every sample is considered except a single-contig assembly you declared circular in the mapping file; a declaration on a multi-contig assembly is ignored, so those contigs are attempted too. Results appear in the Circularization column of the Assemble table, and the thresholds live in the Circularize Opts. modal. See “Circularizing linear assemblies” for details.

Can MitoPilot join a fragmented assembly into one sequence?

Yes, if the contigs match the same reference mitogenome and that reference can estimate the size of every gap between them.

Create the project with new_project_userAsmb(join_scaffolds = TRUE). During the Assemble module MitoPilot orders the sample’s contigs against its BLAST reference and joins them into one sequence. If the contigs instead match different reference mitogenomes, MitoPilot leaves them separate for review rather than joining them, so a contaminated sample is never spliced into a chimera. It also leaves a sample fragmented when the reference cannot size a junction between two contigs, rather than padding it with a made-up number of Ns. Either way it says why in the Scaffold Join Notes column.

On whole-genome assemblies, pair it with find_mitogenome = TRUE. Otherwise any multi-contig assembly is eligible, not just mitochondrial contigs. You can review and adjust the join in the sample’s assembly details window, where Redo join in pipeline queues a fresh join for the next pipeline update. See “Joining fragmented assemblies” for details.

What happens if my assembly contains ambiguous bases?

Nothing breaks. Ambiguity codes (N, R, Y, and the rest) are common in consensus sequences called against a reference, and MitoPilot annotates and exports those assemblies normally.

A codon holding an ambiguous base becomes the one amino acid it can be, or X when more than one is possible, and the gene carries an <n> ambiguous bases in CDS warning so you can review it. Counts are shown per sample in the Ambig. Bases column of the Assemble table, per contig in the assembly details window, and per gene at the top of the annotation alignment. See “Assemblies containing ambiguous bases”.

How do I skip processing certain samples?

There are two ways to make MitoPilot skip a set of samples when running the Assembly or Annotate modules.

If the samples successfully finished all steps of the current module, you can lock them. To do this, select the samples and click the LOCK button. Locking will also make those samples available for the next module.

Alternatively, instead of locking the samples, you can modify their state. To do this, select the samples, click on the STATE button, then choose Pre-Assembly (wait) or Pre-Annotate (wait). This can be applied to any samples, regardless of whether they completed the current module.

Setting the state to wait can help you skip samples that produce unexpected errors and interrupt the workflow.

Where can I find complete scripts and logs for each process?

MitoPilot copies the most important output files to the out directory. However, all of the scripts, logs, and outfiles created by Nextflow are saved in the work directory.

The work directory is automatically set up by Nextflow and can be difficult to navigate. To help with this, we provide NF_work_dir_PROCESS-NAME.txt files for each sample in the out directory. These files contain the path to the Nextflow working directory for a specific process and sample.

Note that in the Nextflow working directories, many files are hidden, including scripts and log files. You can list hidden files on the command line with ls -a.

How can I export information found in the GUI tables?

From within the GUI, each module table (Assemble, Annotate, and Export) has “Export Selected to CSV” and “Export All to CSV” buttons that download the current table contents as a CSV file.

For exporting outside the GUI, we have included an R function MitoPilot::export_db_to_csv. Please keep in mind that the CSV file generated by this function will be a snapshot of the database. If you go back into MitoPilot and make any changes, you will need to export the database again.

Alternatively, if you are familiar with SQL, you can directly pull the necessary information from the .sqlite database located in your project directory.

How do I restore annotations after manual editing?

If you simply wish to bring back a deleted annotation, select the deleted annotation in the table and click the Restore button.

To completely restore the original annotations, rerun the sample with the Nextflow -resume flag. This will quickly generate clean, unedited annotations from previously completed results in the work directory. This approach could be used to fix any mistakes made during manual edits.

Note that rerunning a sample will erase all manual edits and notes.

To rerun specific samples:

change the state of the target samples to “Ready to Annotate”
lock all other samples
make sure your Nextflow command contains the -resume flag

Why does it take so long to edit a start/stop codon position?

Every time you make a manual edit to the start or stop codon position, MitoPilot has to re-do the sequence alignment. This may take a long time if you have many reference sequences that are a close match to your target gene.

To speed up the process of manual editing, we have included the Align fewer refs checkbox. Clicking this checkbox limits your alignments to a maximum of five reference sequences (automatically selecting the top BLAST hits). Note that this will re-run the alignment algorithm, so your alignment results may change.

Why is my MitoPilot project folder so large?

If you are working with many samples or lots of sequence data, your MitoPilot project folder could balloon to multiple TB. This is because MitoPilot doesn’t clean up intermediate files in the work directory, just in case you need them later.

The safest option to save disk space is deleting sub-directories in work that contain failed processes. The following bash one-liner can help identify directories to remove.

# list subdirectories in `work` that contain failed analyses
for f in work/*/*/.exitcode; do [ "$(cat "$f")" != "0" ] && echo "${f%/.exitcode}"; done
# then manually delete these directories

If you are completely done with your project, consider running nextflow clean. This command will delete all temporary folders and files in work. USE WITH CAUTION.

Warning: Use caution when deleting files and directories in work. Nextflow’s caching and resuming system relies on these intermediate files. We recommend not cleaning up the work directory until you are finished with a project.