Documentation

What is MFannotWeb?

MFannotWeb is a browser front end for two organelle-genome tools developed in the Lang lab: MFannot (mitochondrial and plastid genome annotation) and RNAweasel (RNA model search). Both pipelines run server-side in containers; you submit a FASTA file and get back the same outputs you would on the command line.

There are three ways to interact with the service:

• The web UI on the home page — drop in a file, watch the log scroll, download the zip.
• The HTTP API at /api/v1 — see the API reference.
• The mfw CLI — a stdlib-only Python wrapper for the API, in cli/ in the source tree.

Pipelines

Pick a tab on the home page to switch between the two pipelines.

MFannot

Annotates a mitochondrial or plastid genome: predicts protein-coding genes, tRNAs, rRNAs, and group I/II introns. Required parameter:

• Genetic code — the NCBI translation table that matches your organism. The default (4) covers the most common case (mold/protozoan/coelenterate mitochondria, mycoplasma). The full set is listed in the pipeline discovery endpoint.

RNAweasel

Searches a sequence for known RNA models. Required parameters:

• Genetic code — same dropdown as MFannot.
• RNA models — at least one of: tRNA, intronI, intronII, rnpB, rrn5, rns, ssrA. Order matters internally — ssrA uses CMsearch covariance models; the rest use HMM-based RNAfinder.

Submitting a job

1. Open the home page and pick the MFannot or RNAweasel tab.
2. Provide the FASTA either by uploading a file or pasting it into the textarea.
3. Choose the genetic code that matches your organism.
4. For RNAweasel, tick the RNA models you want to search for.
5. Click Submit. The page replaces the form area with a live job card.

The job is queued immediately and starts as soon as a worker is free. A worker processes one job at a time per slot.

FASTA requirements

• One FASTA file per submission.
• Maximum size: 1 MB (configurable by the operator).
• Must begin with a > header line.
• Sequence characters must be A C G T U N (case-insensitive). Whitespace is stripped.
• The original filename is kept only as a label and shown next to the job — it is not used as a path on disk.

Watching progress

The job card subscribes to a server-sent event stream and shows the pipeline log as it’s produced. Up to 500 lines are replayed when you open or revisit the card; new lines stream in live.

• The log auto-scrolls while you’re at the bottom; if you scroll up to read something, it stops following so the text doesn’t jump.
• A Jump to live button appears when you’ve scrolled away from the tail.
• The status badge updates as the job moves through queued → running → done (or failed/cancelled).
• You can navigate away and come back: visit the home page with ?job=<id> to reopen a live view, or open the job from the recent jobs table.

Getting your results

When a job reaches done, the card shows a Download link and the recent jobs table grows a download action. The download is a .zip archive containing the full pipeline output (the same files you’d get from a local run): annotated GFF/EMBL output, summary HTML where applicable, and the run log.

Programmatic clients can also fetch a JSON manifest of the archive contents (file names, sizes, SHA-256 digests) or stream a single file out of the zip without downloading the whole thing — see the API reference’s Results section.

Accounts & anonymous use

You don’t need an account to submit a job. Anonymous submissions are tied to a signed browser cookie, and your recent jobs table will follow that cookie around — until you clear it or switch device, at which point you’ll lose access to those jobs.

Creating an account gets you:

• Job history that persists across browsers and devices.
• Higher concurrency (3 in-flight jobs vs. 2 for anonymous).
• Bearer-token authentication for the API and the mfw CLI.

When you sign up or log in, any jobs you submitted from the same browser while anonymous are claimed into your account. A toast on the home page confirms the count.

Account page

Your account page shows every job tied to your user, with status filters (queued, running, done, failed) and direct links to download or watch each one.

Limits & retention

Defaults shown above; an operator can raise or lower them. Use GET /api/v1/me/usage to read the live values for your account.

A nightly cleanup marks expired jobs as expired and removes their work directories. Once that happens the result archive can’t be retrieved — re-submit if you still need it.

Working from a script

The HTTP API and the mfw CLI both authenticate with bearer tokens. To create one:

1. Sign in to your account.
2. Hit POST /api/v1/tokens with cookie auth — see the Tokens section of the API reference for the exact payload, scope vocabulary, and expiry options.
3. Copy the plaintext field from the response. It’s the only time you’ll see it.
4. Set it as MFW_TOKEN (or pass it directly via Authorization: Bearer mfw_…) in your client.

Each user can hold up to 10 active tokens. Lost a token? Revoke it via DELETE /api/v1/tokens/{id} and create a new one.

Troubleshooting

My job failed with no obvious reason

The job card shows the pipeline’s standard error stream. Common causes: wrong genetic code for the organism, FASTA contains characters other than A/C/G/T/U/N, or the sequence is too short for the requested RNA models.

Submit returns 409 concurrency_limit_exceeded

You’ve hit the per-account in-flight cap. Wait for one of your queued/running jobs to finish, or cancel one from the recent jobs view.

The download link is gone

Job results are kept for the retention window (7 days by default). After that, the status flips to expired and the archive is deleted. Re-submit to regenerate it.

I lost access to my anonymous jobs

Anonymous jobs live in a browser cookie. If you cleared cookies, opened the site in a different browser, or switched devices, those jobs are no longer visible to you. Sign up before submitting if you need a job to outlive your browser session.