# BioWeaver evidence graph, versions 1 and 2

The browser Graph Explorer and free `bioweaver-client` Python package exchange UTF-8 JSON
documents. This is a portable evidence document, not a paid API contract or signed archive.

Readers accept `schemaVersion` 1 and 2 and refuse every other value (`3`, the string `"2"`,
or a missing field) with the same error. Writers emit version 2. Version 2 is version 1 plus
an optional ChEMBL drug evidence block, described under [Version 2](#version-2-chembl-drug-evidence).

## Envelope

| Field | Required value or structure |
| --- | --- |
| `format` | `bioweaver-evidence-graph` |
| `schemaVersion` | integer `1` or `2` |
| `snapshots` | `{trail: fullManifest, orthology: fullManifest}`; version 2 adds optional `drugs` |
| `inputs` | ordered input occurrences `{line, token, taxon, resolution}` |
| `subjects` | unique loaded `{gene, data: {disease: [...]}}` entries |
| `orthology` | original directed orthology candidate records |
| `view` | `{state, query, references, donors, start, selected}`; version 2 adds optional `drugs` |
| `drugs` | version 2 only, optional: `{targets, compounds, links}` |

Manifests use the existing snapshot schema, version 1. Each artifact entry includes `path`,
`bytes`, `sha256`, `schemaVersion`, and `datasetId`. Artifact paths are safe relative JSON
filenames. Trail's `dependencies.orthology` must equal Orthology's `datasetId`. Downloads
are checksum-verified before use; imports are structurally validated. Neither procedure
authenticates a publisher independently of the supplied manifest. Expansion of an imported
graph requires the same manifests as the configured snapshot roots.

## Inputs and records

`line` is a positive unique input-occurrence number; it is not a gene ID. Repeated tokens
remain separate inputs. `taxon` is a string taxon ID from the snapshot catalogue.
`resolution` retains `input` (the original token), `status`, `method`, and unique `candidates`.
A resolved input has exactly one candidate and its matching loaded subject. Ambiguous inputs
have at least two candidates; unresolved inputs have none. Resolution methods are `stable_id`,
`symbol`, `alias`, or `case_folded`; unresolved method is null. No implicit history substitution
or user-choice acceptance is performed by this format's resolver.

`gene` retains the catalogue record and must include nonempty `id`, `taxon`, and `symbol`.
Subjects are unique by `(taxon, id)`. An empty disease array is a source-scoped lack of matched
records, not a negative biological finding or a statement that no research exists.

Disease records retain `diseaseId`, `disease`, `state`, `relation`, `references`, `donors`,
`evidence`, and any other original fields. References are identifier strings. Donors include
`id`, `taxon`, `symbol`, and, when recorded, boolean `curatedExactTerm`. Unknown states remain
unknown; `curated`, `inferred`, and `negative` must never be combined or inferred from counts.
If `subjectTaxon` is present, it must match the containing gene's taxon.

Orthology records retain `sourceId`, `sourceTaxon`, `targetId`, `targetTaxon`, numeric
nonnegative `support`, string-array `methods`, and all other original fields, including
`outOf`, `best`, and `bestReverse`. Both endpoints must be loaded subjects. These are candidates
from the exported stringent subset, not guarantees of functional equivalence. Missing pair
artifacts are unavailable data; a verified empty match is no record within that subset.

## Graph identity and meaning

Node IDs are JSON-serialized arrays:

- Gene: `["gene", taxon, geneId]`.
- Annotation: `["annotation", trailDatasetId, taxon, geneId, zeroBasedAnnotationIndex]`.
- Disease: `["disease", diseaseId]`.
- Reference: `["reference", referenceId]`.

Annotation identities preserve duplicate occurrences within one snapshot and gene; they are
not stable annotation IDs across releases. Rendering adds `subject_of`, `annotated_to`,
`names_reference`, `names_donor`, and `ortholog_candidate` connections. A donor and reference
co-occurring in an annotation do not imply a donor-reference pairing. Several annotations
naming one reference do not establish independent studies. Layout distance has no biological
meaning. Rendered edge IDs are local to a view and are not persisted evidence identities.

## View and limits

`state` defaults to `all`; other strings match exact record states. `query` is a case-insensitive
substring filter over gene symbol/ID and disease name/ID. `references` and `donors` are booleans.
`start` is a nonnegative annotation offset; the browser clamps it to a page boundary.
`selected` is null or a node identity string. Invisible selections are cleared when rendered.

Document limits: 20 inputs, 40 subjects, 2,000 orthology edges, 20,000 disease annotation
occurrences, and 25 MiB serialized JSON. Identity strings and query text are bounded at 10,000
characters. Exceeding document limits fails; evidence is never silently truncated to fit.

Rendering is separately bounded at 25 annotation occurrences per page and 12 references plus
12 donor entries per displayed annotation. The interface reports omitted context links.
The saved document retains all loaded evidence and input decisions irrespective of filtering.
Filtered TSV includes all matching annotations across pages. PNG includes the displayed
network, scope counts and snapshot IDs; it is not the complete evidence archive.

## Version 2: ChEMBL drug evidence

Version 2 adds two node kinds, `target` (a ChEMBL single-protein target) and `compound` (a
ChEMBL molecule), and three connection kinds. A version 2 document without
`snapshots.drugs` has no target or compound nodes; validation refuses either kind without it.

`snapshots.drugs` is the ChEMBL drug evidence manifest reduced to what the document used:

| Field | Value |
| --- | --- |
| `schemaVersion` | integer `1` (manifest schema) |
| `datasetId` | drug evidence snapshot ID, for example `9a64a2304a60b056fb8f2fcc` |
| `release` | ChEMBL release, for example `ChEMBL_37` |
| `licence` | `{name: "CC BY-SA 3.0", url: "https://creativecommons.org/licenses/by-sa/3.0/"}` |
| `artifacts` | `drugIndex` entry and `shards` keyed by HGNC ID |

Artifact entries are validated as for Trail and Orthology: safe relative JSON path, 64-hex
`sha256`, nonnegative integer `bytes`, and the manifest's `datasetId`. Their `schemaVersion`
is any positive integer, because the drug index is schema 2.

`drugs` holds three arrays:

- `targets`: `{targetChemblId, taxon, label}` plus optional `geneId`, `accession`, `organism`.
  Unique by `targetChemblId`, at most 200.
- `compounds`: `{moleculeChemblId, label, maxPhase}`. `maxPhase` is a number or null; null means
  ChEMBL reports no phase, never phase 0. Unique by `moleculeChemblId`, at most 5,000.
- `links`, at most 20,000:
  - `gene_target`: `{kind, geneId, geneTaxon, targetChemblId, drugState}`. `geneId` is an HGNC ID,
    `geneTaxon` is `9606`, the gene is a loaded subject, the target's taxon is `9606`, and
    `drugState` is `records` or `target_not_queried`. A link from any other gene is refused:
    activity is not transferred across orthology, so a mouse Braf never inherits BRAF's
    compounds.
  - `mechanism`: `{kind, targetChemblId, moleculeChemblId, record: {mechanismId, actionType}}`.
  - `activity`: `{kind, targetChemblId, moleculeChemblId, record: {activityId, activityType,
    pchembl, assayChemblId, documentChemblId}}`. `pchembl` is a number or null.

Records may carry further fields, such as `variant`. One link exists per ChEMBL record, so a
compound measured three times on a target has three `activity` links. ChEMBL IDs match
`CHEMBL` followed by digits.

Node IDs: target `["target", targetChemblId]`, compound `["compound", moleculeChemblId]`.
Rendering draws `gene_target`, `mechanism` and `activity` connections, at most 20 compounds per
target (mechanism compounds first, then highest pChEMBL, then ID) and reports the rest as
omitted. `view.drugs` false hides every target and compound node. The saved document keeps all
of them. Pages showing drug nodes carry the ChEMBL release, the CC BY-SA 3.0 licence and the
sentence "Activity is not transferred across orthology."

### Migration

- Version 1 files still open. They render the same nodes and edges as before; a `drugs` block or
  `snapshots.drugs` inside a version 1 file is ignored, as version 1 readers ignored it.
- Saving a version 1 graph writes version 2 with the same records and no drug evidence.
- Version 2 files do not open in older readers: the browser explorer before this change and
  `bioweaver-client` 0.2.0 and earlier refuse them as an unsupported version.
- Expansion compares only the Trail and Orthology manifests, so a graph holding drug evidence
  still expands against the current snapshots.

## Python usage

Install `libraries/python` from a checkout, or download the source package linked by the
Graph Explorer developer page. The package is not on PyPI. Public usage instructions and a
source archive are built at `/graph/developer.html` and `/graph/bioweaver-client.tar.gz`.
The client accepts local directories or explicit HTTP(S) snapshot roots. `Client.graph()`
and `Client.expand()` generate version 2; `read_document()` and `write_document()` validate
versions 1 and 2 locally, and `targets()` and `compounds()` return a document's drug nodes. The
client does not fetch drug evidence; the Graph Explorer adds it. The package's MIT license covers client code only, not upstream datasets.
