MFannotWeb
···

Documentation

How MFannotWeb works end to end — from picking a pipeline to retrieving your annotated genome. Looking for the HTTP contract instead? See the API reference.

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 or paste a sequence, watch the job’s progress, 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. The order you tick them in makes no difference: the models other than ssrA are searched together by RNAfinder, and ssrA, if selected, is then searched on its own with CMsearch covariance models.

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. A live job card appears below the form.

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. The web form checks this itself, with the figure built into the page. The server applies its own limit as well (an operator setting, 1 MB by default), so a server set lower can still refuse a file the form accepted.
  • Must begin with a > header line.
  • Each header line may be at most 1,000 characters long.
  • At most 10,000 records (> header lines) per file.
  • Sequence characters must be A C G T U N (case-insensitive). Whitespace is stripped.
  • MFannot masterfile output (e.g. a previous run’s .new or .all file) is accepted directly — its ; comment/annotation lines, left-margin residue line numbers, and ! markers are stripped automatically, and the genetic code from its header is pre-selected.
  • The file’s name is sanitised: any directory part is dropped, characters other than letters, digits, ., _ and - become _, leading dots go, and at most the last 100 characters are kept (input.fasta if nothing is left; pasted text is named pasted.fasta). The sanitised name is the name of the input file inside the job, so the output files derived from it carry it too, and it is the name shown next to the job.

Watching progress

The job card subscribes to a server-sent event stream and shows a live one-line summary of progress: a completion percentage and the name of the pipeline step currently running, alongside the elapsed time.

  • The percentage advances as the pipeline moves through its major stages; the step label names the stage in progress.
  • 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

LimitAnonymousRegistered
Concurrent in-flight jobs23
Job retention before automatic purge7 days7 days
Submit rate, web form (per IP address)10 / hour, 3 / minute10 / hour, 3 / minute
Submit rate, API (per token or session)— (the API needs an account)30 / hour, 5 / minute

The concurrency and retention figures are defaults that an operator can change in the server settings. The submit rates are built into the server and change only with the code. Use GET /api/v1/me/usage to read the live values for your account.

A nightly cleanup deletes the jobs that have outlived the retention window, with 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. Give it to the mfw CLI as the MFW_TOKEN environment variable (it overrides the token saved in ~/.mfwrc; the --token option overrides both), or pipe it in with --token -. Avoid a literal --token value: other users on the machine can see it in the process list. Your own client can send Authorization: Bearer mfw_… instead. The CLI only talks to https:// hosts (plain http:// only for localhost, unless you pass --insecure-http).

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 error message the worker recorded: the cause when the worker recognises one (for example, running out of memory) and otherwise only that the pipeline exited with a non-zero status. The pipeline’s own output is not shown on the page; API clients can read it from GET /api/v1/jobs/{id}/log. 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 429 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 job and its archive are 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.