id: https://sniff.world/schema/discovery name: sniff_discovery title: "Sniff Discovery: a fact about dogs stored as a query, a control and a floor" version: 0.2.0 license: https://creativecommons.org/licenses/by/4.0/ description: >- LinkML root for the discoveries registry: the facts about dog genetics that Sniff surfaces (which breeds are related, what a breed was built from, how diverse a breed is), each stored as the question it answers, the method that answers it, the controls the method must pass, and the smallest number of dogs a result may stand on. A discovery is never a typed sentence. Every data release re-runs every entry, and an entry either shows, or is withheld with a typed cause. Withheld reuses the coverage frame's DarkCauseEnum, so a discovery that failed its control is dark for the same typed reasons, and carries the same meaning, as a dark cell anywhere else in the substrate: method_limited says our method fails on data that holds the answer, unstudied says nobody has looked. A validity control must recover something already known from an independent source; stability alone proves nothing, because a wrong method can be perfectly stable. The register says whose claim it is. documented: a cited source records it and Sniff renders it without inference. genetics: Sniff's own analysis of genotypes. agreement: Sniff's genetics and an independent source both find it, and the source is named beside it. The three never blend on a page. prefixes: linkml: https://w3id.org/linkml/ sniff: https://sniff.world/schema/ dcterms: http://purl.org/dc/terms/ default_prefix: sniff default_range: string imports: - linkml:types - sniff-coverage-frame see_also: - https://sniff.world/schema/coverage-frame - https://sniff.world/schema/citation keywords: - validity controls - typed absence - re-run every release classes: DiscoveryRegistry: description: The one store of discoveries, shown and withheld, re-run every data release. tree_root: true attributes: registry_version: description: The date of the registry edit, as YYYY-MM-DD. required: true discoveries: description: Every discovery, shown or withheld. range: Discovery multivalued: true inlined_as_list: true required: true Discovery: description: >- One fact family question, answered by a named method, with its controls, its floor, and its latest run. Shown only when every control passed and the floor is met; withheld otherwise, with a cause. attributes: id: description: A stable id, the prefix disc and a slug. Never reused. identifier: true pattern: "^disc:[a-z0-9-]+$" family: description: Which family of fact this is. range: DiscoveryFamilyEnum required: true question: required: true description: The plain question the discovery answers, as an owner would ask it. register: description: Whose claim it is; never blended on a page. range: DiscoveryRegisterEnum required: true method: required: true description: What computes the answer, named by the file that runs it. controls: description: Every test the method must pass. At least one. range: Control multivalued: true inlined_as_list: true required: true minimum_cardinality: 1 control_verdict: range: VerdictEnum required: true description: >- passed only when every control passed. Denormalized for this schema's rules; the build re-derives it from each control's result and bar and fails when the two disagree. n_floor: range: integer minimum_value: 1 description: Smallest number of dogs per subject a result may stand on. n_observed: range: integer minimum_value: 0 description: Fewest dogs any shown subject actually has. floor_verdict: range: FloorVerdictEnum description: Re-derived by the build from n_observed and n_floor. status: description: Shown or withheld, after the latest run. range: DiscoveryStatusEnum required: true withheld_cause: description: Why it is withheld, typed as a dark cause shared with the coverage frame. range: DarkCauseEnum cites: multivalued: true description: Work ids in the Sniff citation catalog (https://sniff.world/schema/citation), each a DOI record. last_run: description: When the controls were last scored, on what data, and where the run lives. range: Run inlined: true required: true reader_reason: description: >- Why it is withheld, in the words an owner would use. The question box answers a capability question with this sentence, so it is plain, has no jargon, and names no internal file. applies_to: multivalued: true pattern: "^OMIA:[0-9]{6}-[0-9]+$" description: >- The conditions this discovery is specifically about, by OMIA id, each listed only after its causal variant was checked against the OMIA record. A question about one of them reads this entry. surfaces: multivalued: true description: Where a shown discovery renders. A withheld one renders nowhere. rules: - description: Shown requires every control passed and no withheld cause. preconditions: slot_conditions: status: equals_string: shown postconditions: slot_conditions: control_verdict: equals_string: passed withheld_cause: value_presence: ABSENT - description: Withheld names why, as a typed cause. preconditions: slot_conditions: status: equals_string: withheld postconditions: slot_conditions: withheld_cause: required: true - description: >- A claim that rests on Sniff's genetics states its floor, and shows only when the floor is met. preconditions: slot_conditions: register: any_of: - equals_string: genetics - equals_string: agreement status: equals_string: shown postconditions: slot_conditions: n_floor: required: true n_observed: required: true floor_verdict: equals_string: met Control: description: One test the method must pass, with its bar fixed before the run. attributes: name: description: What the control measures, in plain words. required: true kind: description: Validity, stability or integrity. range: ControlKindEnum required: true benchmark: description: What it is scored against; a citation id when it is an independent source. bar_op: description: Whether the result must be at least or at most the bar. range: BarOpEnum required: true bar: description: The threshold, fixed before the run. range: float required: true result: description: The latest run's value. range: float required: true verdict: description: Passed or failed. The build re-derives it from result, bar and bar_op. range: VerdictEnum required: true Run: description: One scoring run of a discovery. attributes: date: description: The day of the run. range: date required: true data_release: required: true description: The data the run read, named by its release. evidence: required: true description: Where the full run lives (a scorecard, a generated artifact). enums: DiscoveryFamilyEnum: description: The families of fact the registry holds. permissible_values: relatives: description: Which breeds are genetically close. lineage: description: What a breed was built from. diversity: description: How diverse a breed is, and how narrow its bottleneck. gene_concentration: description: Variants concentrated in one type of dog. translational: description: Genes shared with human research. traits: description: Coat, size and other trait markers. kit: description: >- What a kit sequence can and cannot read at its depth: a dog's place in the atlas and breed mix, single disease variants, insertions and deletions. The subject is the method, scored on dogs whose truth is known from another source; the dog floor counts real kit files scored against an independent result. DiscoveryRegisterEnum: description: Whose claim a discovery is. permissible_values: documented: description: A cited source records it; Sniff renders without inference. genetics: description: Sniff's own analysis of genotypes. agreement: description: Sniff's genetics and an independent source both find it; the source is named. ControlKindEnum: description: What a control tests. permissible_values: validity: description: The method recovers something already known from an independent source. stability: description: The result survives resampling, holds within each study, and across studies. integrity: description: The rendered output is exactly what the rule and its source allow. BarOpEnum: description: The direction a bar runs. permissible_values: at_least: {} at_most: {} VerdictEnum: description: The outcome of one control, or of all of them. permissible_values: passed: {} failed: {} FloorVerdictEnum: description: Whether the dog floor is met. permissible_values: met: {} below: {} DiscoveryStatusEnum: description: Whether a discovery may render. permissible_values: shown: description: Every control passed and the floor is met; it may render. withheld: description: It renders nowhere, and the registry says why.