Skip to contents

Using Your Own Assemblies

Source: vignettes/Your-Own-Assemblies.Rmd
Your-Own-Assemblies.Rmd

This page is for projects built from assemblies you already have, whether those are finished mitogenomes or whole draft genomes. Create them with new_project_userAsmb(). MitoPilot will not assemble anything, but you still work through all three modules: the Assemble module prepares and checks your sequences, then you annotate, curate, and export.

Read Starting Your Own Project first. It covers what you need, how the mapping file is laid out, and how a project is set up. This page covers only what differs.

Tip. new_test_project_userAsmb() builds a ready-to-run project from nine example assemblies, covering linear, circular, and multi-contig cases, with the reference database the mitogenome search needs. Try it before running your own data.

Setting up the project

A user-assembly project needs one extra column in the mapping file, plus an optional second:

Column Contents
Assembly File name of the assembly FASTA for the sample (one file per sample)
Topology Optional. circular or linear, for a single-contig assembly only. Leave the cell blank and MitoPilot treats the contig as linear

Topology is your statement about a finished mitogenome you are handing over. Say circular and MitoPilot will not try to circularize it; say linear, leave the cell blank, or leave the column out, and it may. It applies only to an assembly holding a single contig. If the FASTA holds more than one contig, MitoPilot records the sample as multi and ignores anything you declared. Each contig’s own topology is then worked out only if you switch on attempt_circularization (below); otherwise the contigs are left unknown in the Topology column and handled as linear.

The value reaches the submission too. It appears in the FASTA header as [topology=circular] or [topology=linear], and by default a circular record is submitted as a complete genome and a linear one as partial.

Note. assembly_path is the folder holding your assembly FASTA files; the Assembly column gives file names only. MitoPilot counts the contigs when the project is created, so it has to read those files at that moment. If it cannot, for example when assembly_path is a remote bucket or the files are copied to the cluster later, your declaration stands and a circular declaration is applied to every contig in the file. Leave Topology blank for any file that might hold more than one contig.

new_project_userAsmb(
  path = "~/my_assemblies/run_01",
  mapping_fn = "~/my_assemblies/mapping.csv",
  data_path = "~/my_assemblies/raw_data",
  assembly_path = "~/my_assemblies/assemblies",
  executor = "local"
)

By default the Assemble module only maps reads to your assemblies to compute coverage and error rates. The optional steps below add to it.

If you have no reads at all, set no_raw_data = TRUE and omit data_path. You can also leave the R1 and R2 columns out of the mapping file. MitoPilot will skip read mapping entirely and hide the coverage columns that depend on it.

Warning. A project holds either MitoPilot assemblies or externally supplied ones, never both. Use separate projects if you have a mix.

Running the pipeline

The Assemble module is not optional. Nothing you supply is used until it has run, even if your FASTA files are finished, circular mitogenomes. Assemble is where MitoPilot reads your sequences into the project, records their length, topology, and contig count, maps your reads for coverage, and runs any of the optional steps below. Samples are only released to Annotate once you lock them here.

A run looks the same as any other MitoPilot project:

  1. Open the app for the project, MitoPilot() from the project directory. It opens on the Assemble module.
  2. If needed, change any run options.
  3. Click UPDATE, then Run from App or Submit as Job.
  4. When the run finishes, check the results. You should see Length, Topology, and other columns filled in.
  5. Select the samples that came through cleanly and click LOCK. That releases them to Annotate. Switch modules with the dropdown at the top left.

Then continue with Annotate and Export as usual.

Finding the mitogenome in a whole assembly

If your FASTA files hold whole assemblies rather than mitogenomes, thousands or even millions of contigs each, set find_mitogenome = TRUE. MitoPilot will locate the mitochondrial contigs before anything else runs:

# add to the new_project_userAsmb() call above:
  find_mitogenome = TRUE,
  mitofinder_db = "~/MitoPilot_reference_dbs/Percidae_all_2026-06-11/mitofinder_Percidae_all_2026-06-11.gb",

MitoPilot skips contigs shorter than 500 bp, then BLASTs the rest against a bundled metazoan mitogenome database. The best candidates are annotated with MitoFinder, and a contig is confirmed when at least three mitochondrial genes turn up on it. Only confirmed contigs continue through the pipeline, as scaffolds of the sample’s assembly.

A contig is only kept if its match covers at least half the contig’s own length. That is the NUMT filter: a real mitochondrial contig is almost entirely mitochondrial, while a nuclear scaffold carrying a mitochondrial insertion matches only a sliver of itself. A short nuclear contig whose insertion covers most of it can still get through, so check the evidence before trusting a surprising result. A sample carrying two mitogenomes, its own and a contaminant’s, yields both. A sample where nothing is confirmed is marked failed with a note, and the rest of your samples carry on.

Required. The confirmation step needs a MitoFinder GenBank database for your clade. Build one with custom_assembly_db(clade = "<your clade>", db_path = "~/MitoPilot_reference_dbs", db_type = "mitofinder"). It writes a dated, clade-named folder; pass the .gb file inside it as mitofinder_db, using the full path the builder prints when it finishes. Project creation refuses the search without it. See building custom databases.

The Mito Search column of the Assemble table summarizes each sample. Click the summary to open the full evidence: every contig the search scored, its length, the reference it matched, its percent identity, the share of the contig that aligned, the number of mitochondrial genes it carried, and the reason it was kept or dropped. Thresholds live in the Find Mito Opts. modal, including Min. contig length, the size below which a contig is never searched. The count in the summary is the number of contigs searched, not the number in your file. A per-sample log is written to out/<ID>/assemble/user/find_mito.log.

On a real fish genome skim assembled into 1.4 million contigs, the search returned the single 16,891 bp mitochondrial contig in under four minutes.

Circularizing linear assemblies

Assemblers sometimes report a circular mitogenome as a linear contig whose end repeats its start. Set attempt_circularization = TRUE and MitoPilot will try to close linear contigs for you during the Assemble module:

# add to the new_project_userAsmb() call above:
  attempt_circularization = TRUE,

Each eligible contig is compared against itself with BLAST. This self-comparison follows the approach used by MitoHiFi. Every sample is tried except a single-contig assembly you declared circular. A multi-contig assembly is eligible whatever you declared, since the declaration is ignored there, and each of its contigs is attempted on its own. Click a sample’s Circularize Opts. cell to adjust the thresholds.

If a contig’s ends overlap, the duplicate end is trimmed and that contig is relabeled circular. When you have raw reads, MitoPilot also maps them across the new junction and leaves that contig linear unless enough reads span it. That keeps a long terminal repeat from being mistaken for a real circle.

The outcome for every sample appears in the Circularization column of the Assemble table. A sample with more than one contig gets one entry per contig, each starting with the contig name and separated by semicolons:

Note Meaning
circular: trimmed 231 bp overlap, 42 junction reads Closed, with read support
circular: trimmed 231 bp overlap (no reads to confirm) Closed in a no_raw_data project
linear: no self-overlap found The contig ends do not overlap
linear: overlap 150 bp below the 220 bp minimum An overlap was found but was too short
linear: overlap 97.3% identical, below 99% An overlap was found but the two copies did not match closely enough
linear: 231 bp overlap found but only 2 junction reads (5 required) Overlap present, reads did not back it up
not attempted: 4812 contigs exceeds max_contigs (100) Too big to work through contig by contig

That last case only comes up on a whole draft assembly that reached this step without a mitogenome search to narrow it down first. The 100-contig ceiling is fixed and is not one of the Circularize Opts. settings. Turn on find_mitogenome and circularization will see only the confirmed mitochondrial contigs.

Click the summary to see where the overlap sits and the two copies aligned base by base. When reads were mapped across the new junction, you also get the read depth across the seam. A contig whose overlap was found but rejected shows the threshold it missed.

Assemblies containing ambiguous bases

Sequences called against a reference often carry IUPAC ambiguity codes (N, R, Y, and the rest) where the evidence was mixed or coverage dropped out. MitoPilot accepts them.

A codon holding an ambiguous base is translated to the one amino acid it can be, or to X when more than one is possible, and the gene is flagged with an <n> ambiguous bases in CDS warning for review. The Ambig. Bases column of the Assemble table counts them per sample, and a sample’s assembly details window counts them per contig. When you open a gene in the annotation editor, the alignment says how many of its bases are ambiguous.

Runs of Ns that arrive with your own sequence are left as they are: MitoPilot does not treat them as gaps, since they may be ambiguous base calls rather than missing sequence.

Joining fragmented assemblies

Some assemblers leave the mitogenome split into more than one contig. Set join_scaffolds = TRUE and MitoPilot will order a sample’s contigs against its BLAST reference and join them into a single sequence during the Assemble module:

# add to the new_project_userAsmb() call above:
  join_scaffolds = TRUE,

A sample is eligible when its assembly holds more than one contig. Where two contigs do not overlap, MitoPilot inserts a run of Ns the length of the gap the reference predicts between them.

If those contigs 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 estimate the size of a junction: NCBI expects the number of Ns to be the estimated gap length, so MitoPilot will not invent a spacer. Those contigs can still be submitted as several sequences under one BioSample. See Sequences containing unknown bases.

The outcome for every sample appears in the Scaffold Join Notes column of the Assemble table, including how many junctions could not be sized.

Any multi-contig assembly is eligible, not just mitochondrial contigs. On whole-genome assemblies, use join_scaffolds alongside find_mitogenome = TRUE so the join sees only confirmed mitochondrial contigs.

You can review and adjust the joined result by hand in the sample’s assembly details window. The same window has a Redo join in pipeline button, which hands the join back to the pipeline: the sample is queued, and the join re-runs on the next Assemble update using the reference and options on record rather than the layout you edited. The button then reads Cancel queued pipeline join, so a mis-click is easy to undo. If the sample cannot be queued, the button is greyed out and the reason is shown below it.