Documentation

GLEAM-DB is designed as a reusable evidence layer between variant-linked literature resources and downstream ACMG/AMP interpretation workflows.

Overview

The current release implements CoGenEx-PM3, which focuses on PM3 allelic-configuration evidence. Each released record is defined by a PMID and a query variant, and includes evidence labels, source provenance and release metadata.

What GLEAM-DB provides

PMID × variant evidence records
PM3 evidence labels and PM3 genotype context
Main/supplement provenance and processing diagnostics
Query-specific TSV exports and downloadable release-resource files

What GLEAM-DB does not provide

Final pathogenicity classification
Complete ACMG/AMP classification
Medical advice
Redistributed copyrighted full text or supplementary tables

Data access model

GLEAM-DB provides searchable PMID × variant records through the web interface. Users can export the current search result set as TSV for targeted review. Downloads provide release metadata, field definitions, schema files, example queries, aggregate summaries, quality summaries, manifests and checksums for the current release.

Open files are limited to structured metadata, release documentation, quality summaries and aggregate statistics. Copyrighted full-text articles, supplementary material files, copied source tables, long evidence contexts, raw source documents, raw LLM outputs, internal logs and intermediate processing artifacts are not redistributed.

Controlled record-level archive files are listed in the Downloads page and remain pending public archive deposition if required by journal or repository policy.

Data model

Document layerPair/evidence layerEvidence item layerProvenance layerRelease layer

The document layer stores PMID-level literature metadata. The pair/evidence layer stores PMID × variant evidence records. The evidence item layer stores structured evidence items without copyrighted long-text redistribution. The provenance layer records reviewed source, document format, supplement usage and processing status. The release layer covers versioning, checksums, release metadata and downloadable files.

Evidence status definitions

Phase-confirmed PM3 evidenceExplicit phase-confirmed PM3-relevant allelic-configuration evidence for this PMID x variant record.

Phase-unconfirmed biallelic evidenceBiallelic or allelic-configuration evidence without phase confirmation in the retained structured record.

Other Patient-Level EvidenceRetained patient-level evidence was found, but not PM3-relevant allelic-configuration evidence.

No PM3 Evidence IdentifiedNo PM3-relevant evidence and no retained patient-level evidence were identified for this record.

Evidence status is assigned at the PMID × variant level. It should not be interpreted as a final variant-level pathogenicity classification.

PM3 evidence model

CoGenEx-PM3 captures structured allelic-configuration evidence, including in-trans evidence, compound heterozygous evidence, homozygous evidence, biallelic evidence, partner variants and patient-level evidence. Phase-confirming evidence may include explicit in-trans statements, parental information, haplotype evidence or equivalent evidence where captured by structured adjudication.

Variant normalization and aliases

GLEAM-DB records transcript-level c.HGVS, Gene:c.HGVS, protein HGVS, rsID, genomic HGVS where available, and literature aliases captured in the current release. Online search is strongest for c.HGVS inputs in this implementation. Variant normalization may be affected by transcript ambiguity, outdated nomenclature, incomplete protein-level expressions and non-standard literature aliases.

Source and provenance

Source provenance distinguishes evidence detected in the main article from evidence detected in supplementary materials. This distinction is important because allelic-configuration evidence is frequently reported in tables, supplementary tables or patient-level appendices.

Common values describe whether the reviewed evidence came from the main article, supplementary material, both source types or an unavailable source. Document format labels include JATS/NXML full text, BioC full text, HTML full text and related source-availability notes.

Field dictionary

Field name	Category	Description	Displayed	Download
`pair_id`	Identifier	Stable PMID x variant record identifier.	yes	yes
`pmid`	Publication metadata	PubMed identifier for the source article.	yes	yes
`query_variant`	Variant	Variant expression audited by CoGenEx-PM3.	yes	yes
`gene`	Variant	Gene symbol associated with the query variant when available.	yes	yes
`evidence_status`	Evidence label	PM3 evidence conclusion at the PMID x variant level.	yes	yes
`pm3_genotype_summary`	Allelic configuration	Website-facing PM3 genotype context derived from structured partner evidence.	yes	yes
`evidence_source_display`	Provenance	Whether main text, supplement, both or unknown source was reviewed.	yes	yes
`main_source_resolved_format`	Provenance	Reviewed document format such as JATS/NXML, BioC, HTML or unknown.	detail	yes
`problem_tier`	Processing diagnostics	Source availability or processing status, shown on the website as a user-facing processing note.	detail	yes

Usage guide

How to search by variant: enter a transcript-level c.HGVS query such as NM_000277.3:c.158G>A, or use Gene:c.HGVS such as PAH:c.158G>A when transcript context is unavailable.

How to interpret query normalization: review recognized gene, normalized c.HGVS and PM3-positive record counts before interpreting the table.

How to interpret a result table: each row is one PMID × variant record. Evidence status applies to that record only. Query-evidence confidence is a separate audit label: high means the exact query c.HGVS was found, low indicates a same-position ref/alt mismatch, needs review indicates an ambiguous or incomplete token match, and not assessed means the record is outside the current simple-SNV audit scope.

How to open and read a record detail page: use the Open action to inspect record identity, variant fields, evidence classification, partner variants and source provenance.

How to export data: use Search to download query-specific TSV results, and use Downloads for release metadata, schema, examples, aggregate summaries, quality resources and checksums.

How to cite GLEAM-DB: cite the manuscript and dataset DOI after publication.

How to report an issue: contact and issue-reporting details will be added before public release.

Programmatic access

GLEAM-DB provides a small read-only JSON API for programmatic access to search results, individual records and the release-resource manifest. The API exposes structured metadata and evidence labels only; it does not expose copyrighted full text, supplementary source files, long evidence contexts, raw source documents, raw LLM outputs, internal logs or intermediate artifacts.

API responses are JSON. Search responses contain query normalization fields, pagination metadata and a records array. Record responses contain publication, variant, evidence, source_provenance, target_validation and processing objects.

Search endpoint: /api/v1/search?q=NM_000277.3:c.158G>A&page_size=20. Supported filter query parameters match the Search page filters, including gene, pmid, evidence_status, pm3_positive, evidence_source, year_start, year_end and journal.

Record endpoint: /api/v1/record/{record_id}. The response includes publication metadata, normalized variant fields, PM3 evidence status, query-evidence confidence, PM3 context, retained partner variants, source provenance and target-validation summaries.

Downloads manifest endpoint: /api/v1/downloads. The response lists current release resources, status, checksums and download links.

Operational note: For large-scale access, use the downloadable release resources when available. API clients should respect standard retry responses and the Retry-After header.

Limitations

GLEAM-DB does not provide final ACMG/AMP classifications and does not replace expert clinical interpretation. The current release focuses on CoGenEx-PM3. Non-open-access articles, image-only tables, inaccessible supplements and non-standard variant descriptions may lead to missing or unresolved evidence.

The release does not redistribute copyrighted full text or supplementary tables. Future releases are planned to extend the framework to other literature-derived ACMG/AMP evidence types.

Related resources

GLEAM-DB complements PubMed, LitVar, ClinVar and AutoPM3. PubMed provides citation discovery, LitVar supports variant-centered literature retrieval, ClinVar aggregates submitted clinical assertions, and AutoPM3 represents an automated PM3 extraction method. GLEAM-DB provides a distinct versioned PMID × variant evidence layer with source-aware provenance.

FAQ

Is GLEAM-DB a clinical decision system? No. It supports evidence review and curation; it does not provide final classifications or medical advice.

What is the basic unit? The basic audit unit is a PMID × variant evidence record.

What is CoGenEx-PM3? It is the first released evidence module in GLEAM-DB and focuses on PM3 allelic-configuration evidence.

Why can a variant have multiple records? The same variant may appear in multiple publications, and each PMID × variant pair is audited independently.

Why are original text snippets not shown? To avoid redistribution of copyrighted material, GLEAM-DB provides structured evidence records and provenance metadata rather than long full-text excerpts.