v1.5.9

Breaking changes

• NCBI names. The NCBI setup arguments are now mapping_ncbi and fetch_ncbi (were mapping_biosample and fetch_biosample), since they take SRA accessions as well as BioSamples. fetch_biosample() is now fetch_ncbi(), and its biosamples argument is now ncbi_ids. The mapping-file column still defaults to BioSample, and existing projects need no changes.

New Features

• Run reports. After every Assemble or Annotate run, MitoPilot writes a plain-language report: the result, task counts, failed tasks with a likely cause (for example, out of memory), and samples that failed with their notes. This works for runs started in the app and for runs submitted to a cluster or run in the background from a saved script. A "New run reports available" message appears when new reports are ready, and the Run Reports button (next to Work Dirs) lists every run for the active panel. Click a run to read its report, copy it, or open its folder. Runs still in progress show live task progress read from the Nextflow log.
• Tidier run files. Each run's submission script, scheduler log, Nextflow log, and report now share one name and live under a hidden .runs/ folder in the project, instead of loose files in the project folder. Older projects keep working; their existing logs stay where they are.
• Test projects come with sample metadata. new_test_project() and new_test_project_userAsmb() now fetch each sample's NCBI metadata from its SRA run and follow links to GBIF and GEOME.
• One window for metadata fields. The Metadata button now picks both which metadata fields show as table columns (Show) and which can be used at export (Export), replacing the separate Set Export Metadata button. Tick both together sets both with one click, header boxes tick every row in view, GenBank-ready and Ticked only narrow the list, sample counts show gaps, and a click copies a field's template text. Choose fields in Export Data opens the same window filtered to that source.
• Copy sequence in the sequence viewers. The Annotate sequence viewer and the MapToRef coverage viewer have a Copy sequence button that copies the bases currently in view as FASTA, at any zoom level. In MapToRef, the reference and consensus are copied as two records.
• NMNH user switch in Export Data. Adds the [specimen_voucher=] and [voucherURI=] modifiers NMNH requires on GenBank submissions, fills them per sample from your mapping file, GBIF, NCBI, or GEOME, checks the voucher codes and EZIDs (a tissue EZID is replaced with its parent specimen), and reports samples that are missing or wrong. Fix them in the report or with a CSV upload. See vignette("Specimen-Metadata").
• Sample metadata from the voucher report. Click a sample ID in the NMNH voucher report to open its metadata, then return to the report. The metadata window now has a copy button on every value and Export CSV to save all of a sample's metadata.
• Non-NMNH samples and chosen fields in the voucher report. Tick Not NMNH for samples that are not NMNH specimens: their voucher and URI are used as found, without NMNH checks, and they stay in the report so you can untick them. For any sample, pick the mapping-file column or metadata field its specimen_voucher or voucherURI comes from (Choose fields adds more).
• NMNH user is remembered per project. Export Data opens with the switch as you last left it. The voucher report's field lists are sorted and offer None to leave a modifier out.
• Hydra setup runs automatically. On the NMNH Hydra cluster, library(MitoPilot) and opening the app with MitoPilot::MitoPilot() run hydra_setup() when the job scheduler is not yet on PATH, so you no longer need to call it yourself.
• Empty source modifiers are left out of FASTA headers. When a sample has no value for a [modifier={field}] in the header template, that modifier is dropped from its header instead of being written empty or as NA.
• Redesigned Export Data window. Header templates and the available metadata sit side by side, each column scrolling on its own (stacked, with metadata in a bottom drawer, on narrow screens). Fields missing for some samples are underlined, and a live preview shows a real header example.
• Header checks catch more problems. Export warns when a header uses the same source modifier twice (NCBI accepts each once) and names header columns that are empty for some samples. Checks now look only at the chosen export group.
• BioSample and BioProject in FASTA headers. The NCBI BioSample and BioProject fields now insert [BioSample=] and [BioProject=] source modifiers. New ncbi_biosample_sra and ncbi_bioproject_sra fields hold the values from the SRA record when a sample was linked through an SRA accession.

Changes

• Linking to GBIF by voucher now follows Darwin Core standards. When a GEOME or NCBI record has no Smithsonian EZID, MitoPilot searches GBIF for the specimen voucher in every field that can hold one (specimen_voucher, genbankSpecimenVoucher, materialSampleID, voucherCatalogNumber, otherCatalogNumbers, bio_material, or a bare catalog number with the institution code). It reads triplets, doublets, urn:catalog: prefixes, and USNM 419933-style spacing, no longer rejects the only match over a differing collection code, and skips GBIF occurrences copied from GenBank or BOLD.
• geome_specimen_voucher uses genbankSpecimenVoucher when GEOME has it, and gbif_specimen_voucher drops a catalog number's leading repeat of the institution code.
• In the metadata viewer's Compare tab, coordinates that match only within the 0.01 degree tolerance now show the status agree (rounding) instead of plain "agree". The values shown are always the original stored values.
• The export's sample_info.csv has a new ref_accession column holding just the GenBank reference accession (blank when the reference was flagged as poor). It replaces the ref_comparison column and its "compared sample ... to GenBank accession ..." sentence.

Bug Fixes

• NCBI metadata fetches ignored the project's ncbi_api_key and the NCBI_API_KEY environment variable, reading only ENTREZ_KEY, so they ran at the slower keyless rate. They now use the same key as BLAST and reference fetches.
• Opening the app on a project with no extra mapping-file columns and no fetched GEOME, GBIF, or NCBI metadata (for example a fresh test project) failed with "replacement has 1 row, data has 0".

Note
Run MitoPilot::backwards_compatibility() on older projects to move the container line in .config to macguigand/mitopilot:1.5.9. Scripts that call fetch_biosample() or pass mapping_biosample or fetch_biosample need the new names.

Full Changelog: 1.5.8...1.5.9

v1.5.8

New Features

• NCBI BioSample metadata. Samples can now be linked to an NCBI BioSample, directly or through an SRA accession (SRR, ERR, DRR, SRX, or SRS), with mapping_biosample at setup, fetch_biosample(), or the new NCBI tab in the sample metadata viewer. MitoPilot stores every BioSample attribute plus the linked BioProjects, adds NCBI to the Compare tab and the export conflict warning, and offers GenBank-ready ncbi_* fields at export. See Sample metadata.
• Follow links between GEOME, GBIF, and NCBI. With link_sources = TRUE at setup (or Follow links between databases in the sample metadata viewer), each fetched record is read for IDs of the other databases, and missing ones are added and fetched: BioSample to GEOME tissue and Smithsonian voucher, GEOME to BioSample and voucher, GBIF to BioSample. Other museums' vouchers are matched to GBIF by catalog number, and only linked when exactly one specimen of the right species is found. Your own IDs are never replaced, and every linked ID shows where it came from.
• Remove fetched metadata. Remove fetched data... in the sample metadata viewer, or remove_metadata(), deletes fetched GEOME, GBIF, or NCBI records for one sample or all. Mapping-file columns and the IDs you supplied are always kept.
• Curation ruleset browser tweaks. Each clade now shows a representative image from Wikipedia, credited to its author and license with links to the Wikimedia Commons file

Bug Fixes

• Assemblies keep their N gaps after annotation. Bases with no read coverage, mostly the runs of N that map-to-reference assembly produces where no reads map, were dropped from the saved sequence when annotation finished. Gene coordinates stayed on the full sequence, so every feature after the first dropped run of Ns had incorrect annotation coordinates. The coverage table now has one row per base (depth 0 over gaps), the saved sequence comes from the curated assembly the annotations were built on, and annotation stops with an error instead of saving a sequence that does not match its coverage. Coverage files from earlier versions are completed automatically when annotation runs, so Assemble does not need to be re-run. Re-run annotation on affected samples and re-export them.

Note
To update older MitoPilot projects, please run MitoPilot::backwards_compatibility(). This will add any missing fields to the SQL database and attempt to update the Docker/Singularity container version in your project .config file.

Full Changelog: 1.5.7...1.5.8

v1.5.7

New Features

Sample metadata from GEOME and GBIF

• Link samples to GEOME and GBIF records. Add a column of GEOME BCIDs or GBIF occurrence IDs to the mapping file and name it with mapping_geome or mapping_gbif in new_project(), new_project_userAsmb(), add_samples(), or update_sample_metadata(). Records are fetched at setup, or later with fetch_geome() and fetch_gbif(). Smithsonian NMNH records can be linked by their EZID (an ark:/65665/... identifier or a collections.nmnh.si.edu link) in place of a gbifID. See the new article Sample metadata: GEOME and GBIF.
• Metadata column. The Assemble, Annotate, and Export tables have a Metadata column with a GEOME or GBIF logo per linked source and a flag when sources disagree. Click it to open the sample metadata viewer: GEOME and GBIF tabs to view, add, or refresh records, and a Compare tab that checks your mapping file, GEOME, and GBIF against each other (coordinates, dates, country, voucher, taxon, and more). MitoPilot flags disagreements but never merges values. set_metadata_columns() or Mapfile columns... in the Compare tab picks which mapping-file columns are compared.
• Show any metadata field as a table column. A new Metadata button next to each table's Columns picker lists every field with data: your extra mapping-file columns, then GEOME and GBIF fields, searchable and with sample counts and examples. Ticked fields appear as columns in all three tables, with source logos in their headers, resizable widths, and an optional three-line text wrap. Mapping-file fields are shown by default; GEOME and GBIF fields are off. The choice is saved in the project, and the Metadata entry in the Columns picker hides them all at once.
• Metadata in exported files. Set Export Metadata in the Export toolbar picks which GEOME and GBIF fields can be used in header templates, including GenBank-ready lat_lon, collection_date, geo_loc_name, and specimen_voucher. Export warns when a template uses an item the sources disagree on.
• Export Data window. Usable columns are listed under Available columns (collapsed by default), grouped by type in one box (Basics, Your mapfile columns, GEOME, GBIF, Reference, Assembly and annotation), and insert at the cursor. A column turns orange when it is empty for some records in the chosen export group; hover it for the count. The summary of what will be written now sits at the top, the gene export options sit next to the headers, and each header's validity check sits just above its box. Choose fields returns to Export Data with everything as you left it.

Tables and app

• # Paths and # Scaffolds report ignored contigs, for example "1 (2 ignored)", and sort on the kept count. Counts are read from the assembled contigs, so they no longer go stale. A joined scaffold assembly counts its fragments as ignored scaffolds; a multi-path consensus counts its source paths as ignored paths.
• All BLAST Hits sits next to Top BLAST Hit and belongs to the BLAST column group. The All BLAST Hits, Output, and Details buttons are icons only, with tooltips.
• The Columns picker groups the time stamp and note columns as Notes. In Export, the Exported column stays pinned beside Export Group.
• Pinned column groups on either side of every table have a soft edge shadow where content scrolls under them.
• Row lock and state icons are clickable in the Assemble and Annotate tables. Clicking a row's lock toggles that row's lock; clicking its state icon opens Set state for that row alone. Neither changes the current selection; the toolbar buttons still handle several rows at once.
• The Assemble and Annotate details windows have a Lock button that locks the sample and keeps the window open, now read-only.
• Repeat confirmations can be skipped. Unlocking, editing options beyond the selection, and marking a circular assembly as partial now offer "Don't ask again this session".
• Export rows are deselected after assigning an export group, and a "hold tight" message shows while the PCG outlier review is being prepared.

Changes

• Feature tables always use the SeqID. The .tbl Feature header now always carries the record's SeqID; a GenBankAccession mapping-file column is no longer used there.

Bug Fixes

• Ignored contigs stay visible in user-assembly projects. In the Assemble table, an ignored contig's length disappeared from Raw Length instead of being marked in red as in reads-based projects.
• Circular user assemblies no longer gain a base. In a no-reads user-assembly project, a circular assembly that already started at the start gene came out of annotation one base longer, with base 1 copied onto the end. The stored sequence, its length, and every export carried the extra base. Reads-based projects could hit the same bug when an assembly happened to start exactly at the start gene. Re-run annotation on affected samples to correct them.
• The app launches from RStudio Server. 1.5.6 stopped with cannot coerce type 'closure' to vector of type 'character' when MitoPilot() was run inside RStudio, which sets its own browser handler.

Note
Existing projects work as they are: the app creates the new sample metadata tables and columns the first time it opens a project. MitoPilot::backwards_compatibility() adds them too and moves the container line in .config to macguigand/mitopilot:1.5.7.

Full Changelog: 1.5.6...1.5.7

v1.5.6

New Features

• Install without containers. inst/native/install_mitopilot_native.sh builds every pipeline tool into a user-owned install directory with micromamba, mamba, conda, or pixi, and generate_config(container_engine = "none", native_prefix = ...) writes a config whose tasks use it. native_setup() and native_check() wire up and verify an R session. Works for a single user or as a shared install by a cluster administrator. See the new article Installing without containers.

Bug Fixes

• export_files() summary CSV covers every exported unit. The per-sample sample_info CSV was built from the Export tab's locked view, so a direct call that exported samples never locked in Annotate wrote the files but a header-only CSV. The summary now describes exactly the units written.
• Mapping-file metadata is back in the Export table. The 1.5.5 redesign hid every column it did not declare, which dropped the user's own mapping-file columns from the Export table. They now render as a Metadata column group, shown by default and toggled together from the Columns picker.

Note
To update older MitoPilot projects, please run MitoPilot::backwards_compatibility(). This will add any missing fields to the SQL database and attempt to update the Docker/Singularity container version in your project .config file.

Full Changelog: 1.5.5...1.5.6

v1.5.5

New Features

This release adds a third assembler, MapToRef, a redesigned app interface, and a sequence viewer in the annotation window.

Map-to-reference assembly

• MapToRef maps your reads to a reference mitogenome you supply and builds a consensus from the read pileup. The reference only places reads; every base in the result comes from your reads. The consensus is re-used as the reference and mapping repeats until the sequence stops changing.
• One reference per sample. Add a Reference column to the mapping file (a file path, a URL, or an NCBI accession, which is downloaded for you), set references later with set_maptoref_refs(), or click a sample's MapToRef Ref cell in the Assemble table. A FASTA reference also needs a Reference_topology. References are checked when they are set, and every problem is reported at once.
• Choice of mapper. bowtie2 (default), bwa-mem, or bwa-aln for short or damaged reads such as ancient DNA. The first pass against your reference uses relaxed settings so a distant reference still recruits reads.
• Uncovered sites are called N and mixed sites get IUPAC codes. A circular reference is only published as circular when reads span the junction; otherwise the assembly is linear and a note says so. A note also warns when the reference looks too divergent for the sample.
• The assembly details window opens a sequence viewer on the reference: read depth with uncovered positions marked, the reference's genes, the reference and consensus with differences outlined, and, zoomed in, the individual reads.
• See the new Choosing an assembly method article for a comparison of GetOrganelle, MitoFinder, and MapToRef.

Redesigned app interface

• The three modules are numbered steps (1 Assemble, 2 Annotate, 3 Export) in a header that names the project and version, with a Help link.
• One vocabulary everywhere. Pipeline states are On hold, Ready to run, In progress, Success, and Failed, with the same icons in every table and dialog. Lock and State are proper columns. Toolbar buttons are Lock, State, Update, Assign Group, Clear Group, and Export Data; table buttons are Output, Details, and View.
• Every table has the same filter row and a "Showing N of N" line; column headers are spelled out (Assembly Length (bp), # PCGs, Ambiguous Bases); topology, state, and review flags are colored pills; long notes wrap instead of clipping; table headers stay put while you scroll.
• Every options window uses one form layout with CPUs and Memory first, help beside each field, and a Save button that says it re-queues the sample. Options are read-only on locked rows.
• The annotation details window puts the review flags and their Mark buttons in the header, has one footer with Lock & Close, and honours the lock. The assembly details window explains what the lock blocks and keeps one primary action per panel.
• Every action reports back: locking, state changes, group writes, and exports confirm what they did; destructive actions ask first; errors are explained in plain language.
• Keyboard focus is visible, a skip link and screen-reader landmarks are in place, and motion is reduced when your system asks for it.
• Table downloads are Download selected rows and Download all rows.

Sequence viewer in the annotation window

• The annotation details window has a Sequence section: read depth and error rate tracks, the annotated genes drawn in lanes, the nucleotides, and the translated amino acids of every protein-coding gene under their codons. Click a gene in the table to jump to it; drag, scroll, or zoom to move around; a circular assembly wraps through its origin. Edits in the window show immediately. It replaces the Coverage Map section.

Export

• Internal stop codons are flagged. The PCG outlier review lists any protein-coding gene whose translation contains a stop codon before its end, the HTML report has an Internal Stop Codons section, and MitoPilot warns before writing files that would fail NCBI validation.
• The FASTA header no longer carries the [note=annotation compared to GenBank accession ...] field, which GenBank no longer wants. The reference is recorded in the export's sample_info.csv instead, in a new ref_comparison column.

Project setup

• Pre-flight checks. new_project() and new_project_userAsmb() check the mapping file, read and assembly files, reference databases, and every parameter before creating anything, and report all problems together.
• The mapping file may be comma-, tab-, or semicolon-delimited; ragged rows, stray quotes, and Excel files are detected and explained. Sample IDs are capped at 40 characters, GenBank's limit for a SeqID.

Preprocessing

• Remove duplicate reads checkbox in the Preprocess options runs fastp with --dedup. Off by default; it lowers depth and rarely changes calls.

Container

• samtools upgraded to 1.24 and bwa 0.7.19 added for MapToRef.

Bug Fixes

• Annotate and curate tasks are back in the Work Dirs browser; they were missing for any sample with more than one assembly.
• Marking an assembly reviewed, problematic, or partial no longer clears your row selection in the Annotate table.
• A joined Path 0 sets the sample to Success instead of leaving it Failed.
• Annotate tasks no longer fail on Docker Desktop with exit 125 when the project has no MitoFinder database.
• Copying the nucleotide sequence of a minus-strand gene gives the reverse complement, as it should.
• Genes joined across scaffolds are spliced correctly in the outlier review and the HTML report.
• The alignment editor lets you override the segment-overlap block when you know the overlap is real.

Documentation

• Every app screenshot is refreshed for the new interface, and the walkthroughs use the new names for buttons, columns, and states.
• New article: Choosing an assembly method.
• The Your Own Project arguments are grouped by topic, and the MapToRef reference columns are documented with the mapping file.

Note
Projects created with an earlier release should be updated with MitoPilot::backwards_compatibility(), which adds the MapToRef columns; the app refuses to open an un-migrated project and tells you so. Pass update_config = FALSE to leave your .config alone, then change its container line to macguigand/mitopilot:1.5.5 by hand. Reference is now a reserved mapping-file column; rename it if you used it for something else. The package has new R dependencies (read.gb, Rsamtools, IRanges), so reinstall rather than update in place.

Full Changelog: 1.5.4...1.5.5

mito_metazoa BLAST DB 2026-08-14

Local BLAST database for MitoPilot native (no-container) installs. Container images
already carry this database at /ref_dbs/mito_metazoa; only bootstrap_native.sh
downloads it.

Asset: mito_metazoa_blastdb.tar.gz (275 MiB, 835 MiB unpacked)
SHA-256: 1723b874423e118ec13baa50058ceebb0a4e74001faa33fc766f76310150dbbc

Built 2026-08-14 from GenBank nuccore
(Metazoa[Organism] AND mitochondrion[filter] AND 8000:100000[SLEN]):
134,560 sequences, 2,201,289,510 bases, byte-identical duplicates removed
(37,355 dropped). BLAST DB v5 with taxonomy4blast.sqlite3, so -taxids
restrictions work. Requires BLAST+ 2.16 or newer.

Unpack anywhere and point the project config at it:

tar -xzf mito_metazoa_blastdb.tar.gz
blastdbcmd -db mito_metazoa/mito_metazoa -info

v1.5.4

New Features

This release is about user-supplied assemblies. MitoPilot can now take a whole draft genome rather than a finished mitogenome, find the mitochondrial contig(s) in it, and circularize them if evidence is present. Also includes bug fixes to deal with basepair ambiguities.

Finding the mitogenome in a whole assembly

• Point MitoPilot at a FASTA holding a whole assembly, thousands or millions of contigs, and it will locate the mitochondrial contigs before anything else runs. Off by default; enable with new_project_userAsmb(find_mitogenome = TRUE). You must also supply a MitoFinder database for your clade.
• Contigs are screened against a bundled metazoan mitogenome database, the best candidates are confirmed by annotating them, and only confirmed contigs continue through the pipeline. A sample with no confirmed mitochondrial contig is flagged and stops there; the rest of the batch carries on.
• Nuclear insertions (NUMTs) are filtered out by requiring the match to cover a large fraction of the contig.
• A sample carrying more than one species' mitogenome can return each mitogenome it finds, so you can review them and decide which to drop.
• A new Mito Search column reports the outcome, and the evidence behind each contig it kept or dropped.
• The search is built for large inputs: a full genome assembly of 1.4 million contigs reduces to its single mitochondrial contig in under four minutes.

Circularizing user-supplied assemblies

• Assemblers often report a circular mitogenome as a linear contig whose end repeats its start. MitoPilot can now trim that redundant overlap and circularize the sequence during the Assemble module. Off by default; enable with new_project_userAsmb(attempt_circularization = TRUE).
• When raw reads are available, reads must span the new junction before the assembly is called circular, so a repeat is not mistaken for a real circle.
• Circularization is attempted for each contig when a sample has multiple mitochondrial contigs.
• A new Circularization column reports the outcome. Clicking it shows the overlap alignment alongside the read depth across the seam.

Scaffold joining for user-supplied assemblies

• A fragmented single-path assembly can now be ordered against its BLAST reference into one joined sequence, the same step the regular pipeline already had. Off by default; enable with new_project_userAsmb(join_scaffolds = TRUE).
• Samples whose contigs match different reference mitogenomes are left separate for review, so a contaminated sample is never spliced together.
• A new Scaffold Join Notes column reports what the join did, or why it was refused.
• Redo join in pipeline, a button in a sample's assembly details window, queues a fresh join for the next pipeline update. It becomes Cancel queued pipeline join while one is waiting, and says why if a sample cannot be queued.
• Both the column and the button appear in every project, not just user-assembly ones.

Fragmented assemblies are annotated contig by contig

• A user assembly split across several contigs could not be locked for annotation until you ignored all but one contig, and only that contig was ever annotated. Every contig is now its own annotation unit and is annotated, curated, and exported like any other sequence.

Ambiguous bases are counted and shown

• The Assemble table of a user-assembly project has a new Ambig. Bases column, right after the assembly length, counting the bases that are not A, C, G, or T. It is filled in for samples with a single active contig; a sample with several contigs shows the count per contig in the assembly details window instead.
• The annotation alignment viewer warns when the gene on screen contains ambiguous bases, for protein-coding genes and rRNAs alike. The count updates as you nudge the gene ends with the +/- buttons.

Topology is now optional

• The Topology column in the mapping file is optional. Leave it out, or leave a cell blank, and a single-contig assembly is treated as linear. An earlier release refused to build the project without the column.
• It applies only to single-contig assemblies. An assembly holding more than one contig is recorded as multi and whatever you declared is ignored; declaring such a sample circular prints a warning. Each contig then carries its own topology, which stays unknown unless circularization is switched on, and an unknown contig is handled as linear.
• The same rules apply to samples you add to an existing project.

Test project for user assemblies

• new_test_project_userAsmb() builds a ready-to-run project from nine user-supplied assemblies cut from real data, with examples of linear, circular, not-yet-circularized, and multi-contig assemblies.

Default MitoFinder reference database

• New projects now assemble against a ten-species fish mitogenome sampler rather than a single zebrafish record. This applies to every new project, regular and user-assembly alike. Existing projects keep the database they were created with. Pass mitofinder_db to use a database for your own clade.

Bug Fixes

• A gene containing ambiguous bases no longer kills the sample or the app. A protein-coding gene holding bases that are not A, C, G, or T was refused outright by translation, so curation died partway through with an unreadable error, and clicking the +/- START or STOP codon buttons in the annotation editor hung the app behind a spinner that never cleared. Ambiguous bases arrive both from the N spacers MitoPilot inserts when joining scaffolds and from consensus assemblies called against a reference, which carry IUPAC codes at uncertain sites. Those codons are now translated to an amino acid where only one is possible and to X otherwise, and the gene is flagged with an ambiguous bases in CDS warning for review.
• An error while editing codons no longer freezes the annotation window. Anything that went wrong while walking the START or STOP codon left the "Updating alignment, hold tight..." overlay on screen forever and no other sample would open. The overlay now clears and the problem is reported.
• The Assemble table reports the lengths of the contigs that are actually active. The length and scaffold counts were a snapshot taken before any join, so a joined sample kept describing the fragments it replaced, and ignoring or restoring a contig afterwards changed nothing. They are now refreshed whenever a join, an edit, or an ignore toggle changes what is active, and equal-length fragments are listed individually rather than collapsed into one value that looks like a total.
• Gaps in a joined assembly are declared on export. Every run of Ns that MitoPilot inserted when joining fragments is written as a gap feature carrying its estimated length, however short the run. Runs of Ns that arrived with your own sequence are left alone, since they may be ambiguous base calls rather than gaps. Any coding feature containing unknown bases carries a note saying how many.
• A junction that cannot be sized is no longer padded. MitoPilot used to insert a fixed 100 Ns where the reference could not estimate a gap. NCBI expects the number of Ns to be the estimated length, so such a sample is now left fragmented with a note; its contigs can be submitted as several sequences under one BioSample. This applies to regular projects too, so a sample that joined under an earlier release may now be left in pieces, with the reason given in the Scaffold Join Notes column. If you joined a fragmented assembly under an earlier release, redo the join before exporting: MitoPilot cannot recognize the old fixed padding and will not declare those gaps.
• A contig with no read coverage no longer stops annotation. Every base of an uncovered contig looked masked, so coverage trimming cut the contig down to 50 bp and annotation then failed with an unreadable error that ended the run. Such contigs are now kept whole and carry a no read coverage: trim skipped note.
• A contig with no genes no longer stops the run. MITOS2 writes an empty result file for a contig it finds nothing on, and reading that file failed. Now that every contig is annotated on its own, a contig with no genes is normal and simply returns no annotations.
• The combined export files are written by R rather than shell commands. cat and cp are not available everywhere and broke on paths containing a space, so a submission group's combined FASTA and feature table could go missing with no error.
• The redo scaffold join button is no longer blocked on every sample. The check for a recorded BLAST reference was looking the sample up by an ID it never read, so it found nothing and reported that no sample had a reference.
• Export reads each record's own topology rather than applying one value across a mixed unit.
• The Annotate update dialog counts sequences, not samples, which is what it has always queued.

Documentation

• User-assembly material now has its own article, covering the mitogenome search, circularization, and scaffold joining, with the FAQ and reference index updated to match.

Note
Projects created with an earlier release should be updated with MitoPilot::backwards_compatibility(). Give it your executor, for example backwards_compatibility(executor = "slurm"). It adds the new database fields and rebuilds your project .config from that executor's template, so re-apply any hand edits afterwards. The rebuild matters on a cluster: the new mitogenome-search and circularization steps have their own memory and scheduler settings, and a .config written by an earlier release does not have them. A project pinned to a custom container image is left alone by ...

v1.5.3

Bug Fixes

Origin-spanning features on circular assemblies

A feature that runs across the origin of a circular assembly is stored with its start position after its end position. Nothing downstream expected that, so a single wrapping feature could stop a project outright.

• Curation no longer crashes on a wrapping feature. Every boundary adjustment handed those coordinates straight to a sequence-extraction call that refuses a start after an end, so the whole curation step exited with an error and the run stopped. Sequence extraction and length are now wrap-aware, and extension or trimming may cross the origin on a circular contig. Linear assemblies behave exactly as before.
• Export writes a wrapping feature as two intervals in the submission table. A single line spanning the origin does not mean "wraps" to table2asn, it means "minus strand", so the feature was being submitted backwards. Also fixed in export: the 3' end of a transl_except, minus-strand exon coordinates in the GFF, and a crash in the PCG outlier review when an exon wrapped.
• Validation checks are circular-aware. Overlap, containment, and length tests measured a wrapping feature as if it ran the long way around the genome, so genuine overlaps went unreported and non-overlapping features were flagged.
• The control region keeps its extension when a neighbour wraps. An origin-adjacent OH call is now bounded by the wrapping feature rather than by the contig edge. Three test samples were finishing with a stunted control region and a spurious "below minimum length" warning.
• The annotation editor handles wrapping throughout: nudging boundaries, copy FASTA, rRNA alignment, the boundary viewer, the zoom track, the linearize guard, and merge / un-merge.
• Rotating an assembly now warns when the requested start gene is not present, and when the new origin would cut through a feature.
• MITOS2 annotations use the right contig length. On a multi-contig unit the first contig's length was applied to every contig, which mis-placed wrap calculations on all the others.

Database writes

• Scaffold mappings could be wiped. The delete and insert halves of a scaffold-mapping update were sent as two independent database operators with no guaranteed ordering, so the delete could land last and leave the table empty. Both now run inside a single transaction from the pipeline driver.

HPC

• NOAA SEDNA memory now scales with the retry attempt, matching every other cluster profile. A retry was re-requesting the same memory that had just failed, so a step that ran out of memory would fail again identically.

Container builds

• A stale package archive can no longer be shipped in the image. The Dockerfile picks up the package archive by name order, so a leftover build of an older version won out over the new one and the container quietly shipped the wrong MitoPilot. All three deploy scripts now clear old archives first.

Documentation

• The website has been rewritten and reorganized: Get Started is now a full tutorial built around the bundled test project, the README is a landing page with installation moved to its own article, and the curation documentation is clade-neutral with the ruleset chosen in the app rather than hand-written.
• The article on handling difficult assemblies replaces the old multiple-assemblies page, the reference index is grouped by topic, screenshots are regenerated for the current app, and a citation file is included with the package.
• A maintainer guide for building the container was added, and the legacy GenBank download script was retired.

Note
To update older MitoPilot projects, please run MitoPilot::backwards_compatibility(). This will add any missing fields to the SQL database and attempt to update the Docker/Singularity container version in your project .config file.

Full Changelog: 1.5.2...1.5.3

v1.5.2

New Features

Local BLAST database

• MitoPilot now finds each sample's closest reference mitogenome by searching a local BLAST database packaged in the container, rather than querying NCBI over the network. The database holds all annotated metazoan mitogenomes in GenBank (134,560 sequences).
• The search takes 1-2 seconds per sample instead of minutes, needs no internet connection and no NCBI API key, and is reproducible: a remote search returns whatever GenBank held that day, so the same project could pick a different reference on a re-run.
• Verified against saved remote results: accession, percent identity, and query coverage are identical for every sample in the test project.
• Annotations for the winning reference are still fetched from NCBI, so an internet connection is still required for that step.

New BLAST options

• Remote BLAST searches NCBI over the network instead of the bundled database, for reaching sequences the local database does not contain.
• Fall back to remote BLAST when no local hit (on by default) retries a sample against NCBI when the local search finds nothing, which covers lineages with no mitogenome in the database. Turn it off for strictly offline, reproducible runs.
• Restrict search to taxon IDs limits the search to one or more numeric NCBI taxon IDs (for example 7711 for Chordata). The same restriction is applied if the remote fallback runs.
• The Entrez query field now applies only to remote searches and is shown only when Remote BLAST is ticked. Existing projects that set a custom Entrez query are switched to Remote BLAST when the project is upgraded, so they keep behaving as before.

Version and database provenance

• The BLAST options window shows when the bundled database was built and how many sequences it holds, so it is clear which reference set produced a project's assignments. The build date is also recorded alongside each sample's results.
• Opening a project whose container version does not match the installed MitoPilot now shows a warning naming both versions. It does not block the app: the project still works, it simply runs the pipeline code baked into the older image.

Scaffold-join editor

• The base-pair alignment zoom now opens windows up to 1000 bp, up from the previous cap. This is the widest window that renders on every display.
• Row labels stay in a fixed panel in the base-pair zoom, so it remains clear which scaffold each row belongs to while the alignment scrolls sideways.
• Build joined assembly now shows a progress spinner while Path 0 is being built, instead of appearing to hang.

Bug Fixes

BLAST results

• BLAST hits could be silently lost. The assembly record and the BLAST result were written to the project database by two independent processes with no guaranteed ordering, so a hit could be overwritten moments after it was stored. The sample then showed a reference in the Assemble panel but a blank one in Annotate, with nothing reporting a problem. Observed on one sample of fourteen in a single run.
• A path with no BLAST hit is now scored as one. A missing hit was treated as missing information and simply left out of an assembly path's score, so a path that matched nothing was never penalized and could outrank a path with a genuine, if distant, match. For the same reason the "possible NUMT/contaminant" flag never fired for those paths, which is exactly where it is most useful.
• Automatic scaffold joining is no longer cancelled by a no-hit scaffold. A scaffold that matched nothing was counted as a second, disagreeing reference, so MitoPilot held back the join and left the sample fragmented without explanation.

Annotation editing

• The synteny plot no longer mis-registers after editing an assembly. Linearize left the cached reference alignment untouched, so the plot was silently shifted by the rotation offset, and Trim deleted the alignment with nothing rebuilding it. Both operations now repair the cached alignment exactly, and an alignment that cannot be repaired is recomputed on demand when the window opens.
• The Trim control re-measures after annotation edits. Deleting, restoring, merging, or adjusting the boundaries of an annotation now updates the unannotated flanks shown in the Trim control and its confirmation dialog, which previously kept reporting the pre-edit measurement.
• The PCG outlier review no longer shows the pre-edit alignment after returning through Back to Review. The review now decides for itself what changed by comparing against the project database, and recomputes only the genes that actually moved.
• Mouse-wheel scrolling is no longer translated into horizontal scrolling on the coverage map and synteny views.

App

• Fixed a crash when opening annotation options. Ignoring every scaffold of a sample and then un-ignoring one left that sample with no parameter sets assigned, showing "undefined" for the annotate, curate, and ORF sets; clicking one closed the app. Affected samples are repaired automatically.

HPC

• Fixed the reference fetch step being killed by scheduler memory limits. On nodes with many cores, R reserved several GB of address space before doing any work, which schedulers that cap address space (such as SGE on Hydra) treated as an overrun, killing the task before it made a single request. Raising the memory request did not help, because the reservation grows with the node's core count. All R pipeline steps are now capped to a single compute thread.
• The NMNH Hydra profile now uses a fixed memory reservation for its annotation steps rather than one that scaled with the retry attempt.

Note

To update older MitoPilot projects, please run MitoPilot::backwards_compatibility(). This will add any missing fields to the SQL database (including the new assembly_backup table) and attempt to update the Docker/Singularity container version in your project .config file.

Full Changelog: 1.5.1...1.5.2

v1.5.1

New Features

Trim unannotated assembly ends

• New Trim unannotated ends control in the annotate-details window cuts a linear assembly back to its outermost annotated feature. Export already performed this cut in memory for linear units; doing it in the app makes it visible, undoable, and applied to everything the app shows rather than only to what is submitted. Because the boundary is a feature boundary, no feature is ever dropped or truncated, so feature counts, spans, and gene order are unchanged.
• New Restore assembly control undoes every in-app assembly edit for a unit, returning the sequence, feature model, coverage track, and annotate-stage files to the pipeline's own output. Linearize is now covered by the same undo.
• Snapshots are stored in a new assembly_backup table; a row exists only while a unit carries an un-restored edit.
• Guarded throughout: circular assemblies must be linearized first, the coverage track must line up with the assembly or the trim is refused rather than desynchronizing them, user-supplied multi-contig units are refused outright, and soft-deleted annotations stay tombstoned at position zero. Any edit drops the unit's cached blast_ref_alignment, which WF1 regenerates on the next run, so the synteny view can never silently mis-register against an edited sequence.

Stale assembly-output detection

• ASSEMBLE publishes to out/<ID>/assemble/<assemble_opts>/, so the option-set name doubles as a directory name and every downstream stage rebuilds that path. Reassigning a sample to a different parameter set after it has assembled left the published output under the old name, and nothing noticed: WF2 annotate / curate / ORF, the coverage viewer, and the output-folder button all pointed somewhere that was never created, so runs either failed obscurely or completed with no reference hits at all.
• MitoPilot now detects this and reports it at three points: on app startup (a warning, keeping the app open, since the fix requires the app), at lock time (the affected samples are held back, the rest are locked, and both remedies are spelled out), and when the parameter set is reassigned. The check mirrors the WF2 gate exactly and tests for the per-path assembly FASTA, not merely the directory, so an empty publish directory does not silence it.
• ANNOTATE additionally logs a warning naming the parameter-set directories that do exist for the sample. The unit is still emitted either way, so annotate() fails as loudly as it always has.
• Coverage-details reads and writes are checked before anything is written, so a missing output can no longer leave a half-written Path 0 behind. The check reports but never creates: a directory holding only the Path 0 files would look complete while the raw path assemblies stayed orphaned.

Scaffold-join editor: live verification views

• The mapping plot and base-pair zoom now read a live layout that overlays your current reverse-complement and include choices, so manual edits are reflected immediately without re-running the reference mapping.
• Exclusion reasons are surfaced ("low reference coverage", "unmapped", "subsumed by scaffold N") in the editor, the mapping plot, and the join note, so it is clear why a scaffold was left out of Path 0.
• Sparse placements are hatched in the mapping plot. A bar spans the union extent of a scaffold's alignment blocks, so a sparse placement was previously drawn solid over reference it does not actually cover, which is what made the base-pair zoom look like it disagreed with the overview.
• Scaffolds that are included but have no reference placement are now called out ("appended with N gap") instead of being absent from the plot entirely, and empty zoom rows say why they are empty rather than reading as missing data.
• Switching the reference recomputes the layout and snaps back to the last good accession if the recompute fails, so the dropdown can never disagree with the layout the build step actually uses.

Bug Fixes

Scaffold placement and joining

• Origin-wrap and repeat blocks no longer balloon a scaffold's placement. A scaffold's alignment blocks are reduced to a single colinear chain before the reference extent is taken, so a block on the far side of the origin can no longer stretch the extent across the whole reference and manufacture a genome-scale negative gap at the next junction. Query coverage is still scored over all blocks, so a genuinely rearranged scaffold is not dropped.
• The sparseness test is now relative to the sample's own scaffolds rather than an absolute match-density floor. Match density falls with reference divergence, so the old fixed threshold was cleared by everything against a conspecific reference and by nothing against an ~83%-identity one, switching the guard off exactly where fragmented assemblies need it most.
• Contained scaffolds are excluded from Path 0 instead of forcing a large negative gap that trimmed real bases out of the container. Guarded so a scaffold still carrying substantial unaligned sequence is never discarded, and a scaffold that is itself excluded cannot be cited as another's container.
• Junction overlaps must now be genuine. A confirmed overlap has to reach the 3' terminus of the preceding scaffold, have ungapped and near-identical terminal columns, and not be low-complexity. On real data a dragged alignment scored 5/10 at the terminus with 42 indel bases where a true junction scored 100%, so short AT-rich matches were previously confirming junctions that were not there and trimming real bases.
• Overlap consensus no longer manufactures ambiguity codes. The coverage-majority consensus pairs the two scaffolds by index, so it now runs only when the overlap is base-alignable (no indels, and the aligned length matches the trim taken). Otherwise the preceding scaffold's bases are kept and the junction note says so, instead of quoting an identity that does not describe what was written.
• A scaffold fully consumed by overlap trimming is dropped rather than appended as an empty piece, which previously desynchronized the source-position map. The following junction is re-measured against the scaffold actually present.
• Origin rotation only happens when a block actually reaches reference position 0. Extrapolating to the origin from a distant block is wrong across N gaps and non-colinear scaffolds, where the colinear offset is not constant.
• An unticked Circular box no longer silently emits the origin region twice. Redundant-end detection always runs; when trimming is not authorized, the join note warns that the duplication is present.
• Coverage tracks stay in register. Per-position strings now preserve their position count (empty cells become NA, outlier-mask prefixes are stripped) and are padded or truncated to the sequence length. Numeric mapping columns are also coerced back after SQLite returns them as text, which it does whenever unmapped scaffolds store empty strings.

Base-pair zoom rendering blank

• The zoom's scaffold sub-region is estimated from a single anchor block, so its error grows with distance from that anchor and with every indel in between; scaffolds that showed a bar in the overview could render blank. The estimate now widens in proportion to the drift, candidate alignments are scored against the reference window and rejected below an identity floor, and a whole-scaffold realignment is tried when the estimate covers less than half the window. A drifted estimate now yields an honest blank instead of confidently wrong bases.

BLAST reference synteny orientation

• The whole-genome aligner aligns on whichever strand scores higher, so a sample stored on the opposite strand from its reference came back reverse-complemented, putting the synteny view in a different frame from the coverage map and the sequence editor: the same sample, with gene order and orientation mirrored between two plots sitting side by side. Alignments are now normalized on load so the sample is always drawn in its stored orientation and the reference carries the flip, labelled "shown reverse-complemented". Independent of the ref_based_rc curation option, which already flips the assembly before alignment.
• Origin-wrapping features keep their gene label on both arcs. Labelling only the longer arc left an unidentified arrow at the opposite edge of the linearized layout.

Path 0 attribution in the join editor

• The joined assembly now inherits its BLAST hit from the accession the layout was actually built from, not the raw dropdown value, so a reference whose recompute failed can no longer mislabel Path 0.
• Manual layouts carry their reference coordinates and recompute junction gaps rather than blanking them. An all-empty gap vector switched off the overlap probe at every junction, turning each one into a blind 100-N spacer with the shared bases duplicated, including junctions the user never touched.
• Per-sample join state is cleared when the window opens, so a stale accession or orientation from a previously viewed sample cannot be stamped onto another sample's Path 0.

Join-group ids in the annotation editor

• The next join-group id was derived from an unanchored group= search over the notes field, and applied a non-vectorized operator to a whole column. A free-text note mentioning group= anywhere could steal or inflate the id, and a notes column holding only NULLs raised an error instead of returning the first id. The id is now derived from the anchored JOIN: marker, matching the readers used by export and the un-join action.

Cluster configuration

• memory in .config is a plain number of gigabytes, but a bare number is interpreted as bytes by Nextflow. scaffold_join, coverage, and coverage_userAsmb now convert it explicitly and scale t...