BioWeaver: detailed user guide

Scope: the shared-design release prepared on 2026-09-29. Start at BioWeaver. The Tools navigation connects every application; this guide is available from Documentation in that navigation.

Contents

1. Choose a tool
2. Understand the evidence
3. Prepare gene identifiers and lists
4. Loom
5. Evidence Map
6. Unresolved
7. Unseen
8. Evidence Audit
9. Orthology Workbench
10. Evidence Trail
11. Cross-species Comparator
12. Evidence Changes
13. Review retired NCBI identifiers
14. Projects, reports and downloads
15. Move between tools
16. Privacy and reproducibility
17. Troubleshooting

Choose a tool

Evidence Map, Unresolved and Unseen use their Cloudflare Pages addresses because their advertised BioWeaver subdomains do not currently resolve. The shared menu uses the working destinations. Their data remains in separate static deployments.

Project/report and optional NCBI history controls are available in Audit, Orthology Workbench, Trail and Comparator. Do not expect those controls in every older tool or in Loom merely because all belong to BioWeaver.

Understand the evidence

States are part of the result

“Direct” can mean annotated to the exact disease term rather than a descendant. It does not necessarily mean experimentally curated rather than inferred. Treat term scope and inference as separate questions.

Phenotype descriptions may be source text. Do not assume they carry standardized ontology identifiers or support a similarity calculation. GO qualifiers, evidence codes and references matter: NOT and ND must not be interpreted as ordinary positive functional annotations.

Counts need a denominator

An input-row count, unique-gene count, annotation count and source-record count can all differ legitimately. A duplicated input remains two rows. One gene can have multiple proteins, transcripts or annotations. Multiple sources may repeat the same underlying evidence. Read the displayed scope and retain it in your report.

Source snapshots are dated datasets, not live queries against every upstream database. A current upstream page may legitimately differ from the saved release.

Prepare gene identifiers and lists

For Audit and Orthology Workbench:

1. Paste one identifier per line, or open a text/TSV file.
2. For a tab-separated table, choose the identifier column explicitly. The visible column control is one-based: column 1 is the first column.
3. Enable the header option only if the first nonblank row is a header. The tool does not guess that a gene-like value is a heading.
4. Choose species where the tool offers them. Audit is human-specific.
5. Run the tool and inspect identifier resolution before interpreting evidence.

The parser supports quoted TSV cells, escaped quotes and newline-separated input. Blank rows are skipped. The selected identifier token is trimmed, while original row text is retained. An unclosed quoted cell is an input error. Comma-separated CSV is not the documented input format; convert it to TSV or paste a single column.

A deliberately illustrative input is:

BRCA1
BRCA1
__unmatched_public_example__

The duplicate tests preservation of repeated rows. The last token is an intentional non-gene example, not a biological identifier. Do not replace uncertain user input with a plausible symbol simply to obtain a resolved row.

For Trail and Comparator, start with one gene symbol or stable identifier and the appropriate species. Their single-gene input is not a list-upload substitute.

Loom

Entry: https://bioweaver.org/loom. Old loom.bioweaver.org paths redirect to this location, preserving the path and query.

1. Search a public example such as BRCA1 or browse diseases/models.
2. Inspect the organism and stable identifier on a result before opening it.
3. On a gene page, examine the available profile, orthologs, diseases and phenotypes.
4. Follow a disease link to inspect the term-specific evidence and available scope.
5. Use the relevant downloads when you need the displayed data outside the page.
6. Preserve the URL and source context with your research notes.

Loom's existing local navigation includes Search, Diseases, Models, Advanced and Ask. These are sections of Loom, not separate BioWeaver tools. Ask is a separate query workflow; the static-tool claim that lists remain in the browser must not be generalized to text submitted to a server endpoint or model-backed query feature.

Stable IDs can appear in normalized URLs, such as /loom/gene/HGNC_1100. Use the application's generated links rather than manually changing namespace punctuation. Some source-only genes lack an indexed Loom page; the other tools deliberately avoid inventing a working link for them.

Evidence Map

Entry: https://evidence-4y8.pages.dev/.

1. Read the legend and introductory scope before reading the grid.
2. Use “Find a disease” to narrow the disease rows.
3. Compare the separate curated, inferred-only and missing states across species.
4. Follow a disease link into Loom for more detail where available.
5. Use “Show more” if the desired row is outside the currently rendered subset.

An apparently populated cell can represent inferred evidence. The grid is not a count of independent experimental confirmations, and its visual density must not be described as curated coverage without checking the legend.

Unresolved

Entry: https://unresolved-bqp.pages.dev/.

1. Read the displayed ClinVar and constraint definitions and scope.
2. Search for a gene of interest.
3. Compare “All genes” with “Highly constrained only” when that restriction is relevant to the research question.
4. Inspect the gene-level interpretation summary and linked gene context.
5. Retain the source/version and denominator when reporting a fraction or count.

This tool examines human gene-level summaries. It does not determine whether an individual variant is pathogenic. Constraint is not an interpretation guarantee; the page's finding that constraint does not predict interpretability must remain part of the result, even when it weakens a proposed story.

Unseen

Entry: https://unseen-bpy.pages.dev/.

1. Read the scope: reviewed human protein annotation and the fields inspected.
2. Search the available gene/protein rows.
3. Choose All gaps, Never observed, No function, No GO term or Silent on all three.
4. Interpret each gap in the context of its named UniProt field and source release.
5. Follow a valid gene link when available and inspect the underlying source.

“Never observed” is the tool's source-defined protein-observation state; it is not a claim that no laboratory has ever looked at the gene. Missing function/GO text does not mean the protein has no function. The page's comparison showing little selection among its gaps is scientifically relevant and must not be omitted.

Evidence Audit

Entry: https://bioweaver.org/audit/.

1. Enter a human gene list or open a text/TSV file.
2. Set column/header controls and select “Audit evidence”.
3. Inspect resolved, unresolved and ambiguous inputs first.
4. Choose an evidence category: identifier resolution, constraint, ClinVar, proteins, diseases or mouse models.
5. Choose a state filter if you want to isolate missing records, unavailable sources, ambiguous matches, excluded records or uninterpretable results.
6. Expand available details to identify which source supports a cell.
7. Download visible rows as TSV for the filtered table, or a session manifest for input/options provenance. Save a project for the archived evidence and notes.

The visible filter changes the view. A project retains its captured evidence and filter settings; it is not interchangeable with a visible-rows TSV. Do not assume that a short filtered export contains every input or all underlying detail.

Mouse-model summaries require their stated production/allele evidence. A missing particular IMPC state is not proof that no knockout exists in MGI or elsewhere.

Orthology Workbench

Entry: https://bioweaver.org/orthology/.

1. Choose From species and To species.
2. Enter the list and column/header settings.
3. Select “Map gene list”.
4. Inspect method support and the available reciprocal/method filters.
5. Review excluded candidates as well as included candidates when explaining a selection. A candidate excluded by your settings is still a source record.
6. Select candidate models explicitly. Keep one-to-many mappings visible.
7. Choose the export scope: all candidates and exclusions, included candidates, or your selections.
8. Download mapping TSV, unique targets, a session manifest, or a project/report.

“Unique targets” intentionally deduplicates a list for downstream use; it is not a substitute for the mapping table when input duplicates or many-to-one mappings matter. Directional flags such as Yes_Adjusted retain their original meaning. Changing a query can clear selections; save the project before starting another.

This is a workbench over the supplied Alliance/DIOPT-derived predictions. It does not calculate new sequence alignments or claim better orthology prediction accuracy.

Evidence Trail

Entry: https://bioweaver.org/trail/.

1. Choose a species and enter one gene.
2. Select “Trace evidence”.
3. Inspect the annotation-type filter. Its initial value is Orthology-inferred; choose All annotations if you want the complete set of categories.
4. Filter by disease name or DOID where useful.
5. Read the relationship, polarity, donor genes and references for each record.
6. Distinguish the exact-term local-curation check from the original inferred record.
7. Download filtered TSV, evidence JSON or a session manifest; save a project to retain the captured evidence and your interpretation separately.

Donors come from the source's basedOnGenes data. The donor species, disease term and reference are part of the explanation. A positive-looking relationship name alone is insufficient to determine polarity: source-generated relationship text can carry negation. The tool retains that distinction.

Cross-species Comparator

Entry: https://bioweaver.org/compare/.

1. Choose the query species and enter one gene.
2. Choose target species and select “Find ortholog candidates”.
3. Inspect candidate identities and supporting orthology evidence.
4. Select the candidates you actually want to compare.
5. Select “Compare selected candidates”.
6. Inspect each evidence category and its missing/ambiguous/quality state.
7. Download evidence TSV, comparison JSON or a session manifest, or save a project.

GO annotation totals are not functional-distance scores. Computational and experimental evidence are different categories. NOT and ND have special meaning. Human gnomAD constraint versions must retain their version/transcript/quality context. FlyBase complementation retains its direction, assay and references; it does not prove full functional equivalence between two genes.

Empty evidence for a selected candidate remains an explicit result. It must not silently remove the candidate from the comparison or make another one look stronger.

Evidence Changes

Entry: https://bioweaver.org/changes/.

The current page says Baseline only. It exposes baseline provenance and links to Evidence Trail so a researcher can preserve reviewed evidence. It does not accept a recurring watchlist or report biological additions/removals.

The local comparison engine has tests for disease-record comparisons, including source availability and exporter differences. Those tests do not establish that a real comparable historical pair exists. A changed exporter or missing source can make snapshots incomparable; it must not appear as biological withdrawal.

Review retired NCBI identifiers

Available in Audit, Orthology Workbench, Trail and Comparator.

1. Enter explicit identifiers beginning NCBIGene: or NCBI_Gene: and select the relevant species. Symbols and bare numbers are outside this history workflow.
2. Select “Review retired NCBI IDs”.
3. Read the result and complete replacement chain.
4. If a unique available terminal replacement is offered, choose “Accept replacement” or “Keep unresolved”.
5. Run the tool again to apply the decision. The original input text remains intact.
6. Save the project to retain the decision, chain and history snapshot reference.

Accepting a suggestion does not override an already resolved current stable ID. Opening a saved project clears active history suggestions from the previous work. A fresh analysis requires renewed review; the archived report remains readable.

The retained human-history input contains 166,633 retired IDs, of which 21,221 terminal replacements have a unique owner in the measured catalogue. These are snapshot-level measurements, not a promised recovery rate for your list. Exact denominators and chain outcomes are in the measurement report.

Projects, reports and downloads

Save a project

1. Run the tool and complete the selections you want to retain.
2. Enter the research question and researcher notes in “Project and report”.
3. Select “Save project”. Keep the JSON file in storage appropriate for its contents.
4. Select “Download report” for a standalone readable HTML report.
5. Use “Print report” if you want the browser's print workflow. Actual print-dialog behavior has not yet been verified in the latest release environment.

Notes are researcher-authored interpretation. They are not presented as source annotations. The project includes original inputs, row identities, decisions, evidence, view settings and a closed set of source-snapshot dependencies.

Reopen a project

1. Open the same tool that created it.
2. Use “Open project” to select the JSON file. The current import ceiling is 25 MiB.
3. Read the restored archived report and restored input/control settings.
4. Edit the notes/question and save again if only those need changing.
5. Run the tool again only when you intend to analyze against current hosted data.

Importing a project does not fetch evidence from URLs embedded in the project. A project from a different tool is rejected with the corresponding tool context. Unsupported schemas, invalid dependencies and malformed content are rejected. The size ceiling is a parsing bound, not a guarantee of fast printing at that size.

Choose the right artifact

Saved HTML reports carry their content and styling. Live URLs in them still need network access when followed. Saving a report does not archive every linked paper or database page.

Move between tools

Every tool has the same BioWeaver navigation. On a wide screen it stays in the left sidebar; on a smaller screen open Tools near the top of the page. The current tool has a visible marker. Escape closes the compact navigation and returns keyboard focus to Tools. All tools, Documentation and About & sources are available below the tool groups.

Appearance offers System, Light and Dark. System follows the operating system; the other options override it. Preference storage is local to each origin, so a separate Pages tool may have a different saved preference. If browser storage is blocked, the control still works for the current page. Without JavaScript, the expanded native navigation remains usable.

A sidebar link is navigation. It must not silently transfer your list, notes, accepted replacements or private project to another tool. Save work before leaving an analysis you need. A browser back button is not a durable storage mechanism.

Useful manual workflows include:

• Audit → Trail: identify a gene whose disease evidence needs explanation, then inspect that gene and the relevant annotation category in Trail.
• Orthology → Comparator: identify candidate orthologs, then explicitly select the candidates in Comparator and review their recorded evidence.
• Evidence Map → Loom: identify a disease/species coverage state, then inspect the relevant disease page and distinguish exact-term/inherited evidence.
• Unresolved or Unseen → Audit: take a public candidate into a broader source review, retaining the original gap definition rather than treating it as a score.

These workflows do not imply that every step currently has an automated handoff. Project files from one tool should not be imported into a different tool as though their evidence and selections have the same meaning.

Privacy and reproducibility

Static research-tool lists are processed in the browser; public catalogues and partitions are downloaded as needed. Project files and notes are saved locally. This is not a claim that the browser makes no network requests, or that every BioWeaver application has identical request behavior: Loom uses server endpoints.

The site does not add analytics or require an account. Downloaded reports can contain the identifiers and notes you entered. Sharing a report shares that content; inspect it before sending it outside your intended audience.

For reproducible work, retain the project, source snapshot IDs, source releases, view/filter settings, original input, accepted history decisions and your notes. An operator can additionally preserve the complete verified snapshots. A later re-analysis can differ because data, catalogue ownership or exporter behavior changed; it should not overwrite what the old report said.

Troubleshooting

When reporting an issue, include the tool URL, public example input if possible, selected species/filters, expected and actual behavior, error text and snapshot ID. Remove private notes and identifiers before posting a public issue. Operators should reproduce on local data before spending production database reads.