Edit on GitHub

starplast.evidence

Versioned observations and reviewable literature assertions.

Gene-level matrices remain useful model inputs, but they are derived summaries. This module preserves source, biological entity, condition, uncertainty and missingness before aggregation. Parquet files use JSON scalar values so booleans, numbers and text keep their types without a mixed-type Arrow column.

EVIDENCE_STATUSES = {'model_prediction', 'unclassified', 'orthology_transfer', 'measured', 'computed'}

MISSING_STATES = {'failed_qc', 'below_detection', 'observed', 'not_assayed', 'ambiguous_mapping', 'unknown'}

ENTITY_TYPES = {'host_gene', 'transcript', 'protein', 'allele', 'pair', 'residue', 'metabolite', 'gene'}

@dataclass(frozen=True)

class Observation:

One source-specific observation; contradictory records are retained separately.

Observation( entity_id: str, trait: str, value: object, source_id: str, organism: str, entity_type: str = 'gene', entity_version: str = 'unspecified', source_version: str = 'unspecified', source_url: str = '', source_location: str = '', unit: str = 'unspecified', context: dict = <factory>, replicate: str = '', uncertainty: float | None = None, uncertainty_kind: str = 'unspecified', missing_state: str = 'observed', evidence_status: str = 'measured', derived_from: tuple = ())

entity_id: str

trait: str

value: object

source_id: str

organism: str

entity_type: str = 'gene'

entity_version: str = 'unspecified'

source_version: str = 'unspecified'

source_url: str = ''

source_location: str = ''

unit: str = 'unspecified'

context: dict

replicate: str = ''

uncertainty: float | None = None

uncertainty_kind: str = 'unspecified'

missing_state: str = 'observed'

evidence_status: str = 'measured'

derived_from: tuple = ()

record_id

Content identity distinguishes source versions and experimental conditions.

def write_observations(observations, path):

Write a deduplicated, immutable-content snapshot and return its SHA-256.

def read_observations(path):

Reconstitute typed observations and validate each stored content identity.

def from_gene_table(nodes, organism, source_version, columns=None, include_missing=False):

Yield source-linked gene summaries without inventing unavailable assay detail.

The existing table is already aggregated. Original replicate, dose and time information cannot be recovered from a summary column. Those fields should enter as separate Observation records when raw source tables are imported.

@dataclass(frozen=True)

class LiteratureAssertion:

A sourced claim proposed for review, distinct from a measured observation.

LiteratureAssertion( entity_id: str, relation: str, object: str, source_id: str, source_url: str, passage: str, source_location: str = '', context: dict = <factory>, negated: bool = False, review_status: str = 'pending', reviewer: str = '', reviewed_at: str = '')

entity_id: str

relation: str

object: str

source_id: str

source_url: str

passage: str

source_location: str = ''

context: dict

negated: bool = False

review_status: str = 'pending'

reviewer: str = ''

reviewed_at: str = ''

def review(self, accepted, reviewer):

Return a reviewed copy; retain the source passage and original claim.

def observation(self, organism):

Convert an accepted claim to a sourced literature observation; pending claims cannot enter features.

def propose_assertions(passages, gene_index):

Extract simple relation phrases as review candidates, never accepted facts.

Each input supplies text, source_id, source_url and optional location/context. Ambiguous multi-gene sentences are omitted. This conservative rule extractor does not resolve coreference, infer missing contexts or establish truth.

def save_assertions(assertions, path):

Save review status and evidence passages as portable JSON lines.

def load_assertions(path):

Read and validate assertions without changing their review status.