Product input needed: Feature Sample ontology (FieldSeeker larval/inspection samples) #253

New issue

Open

opened 2026-09-24 21:18:49 +00:00 by eliribble · 0 comments

eliribble commented

2026-09-24 21:18:49 +00:00

Owner

Context

The FieldSeeker → Nidus import (see doc/nidus/fieldseeker-mapping/) has landed Site, Feature, Inspection (incl. notes), Treatment (incl. treated areas + the Product catalog) and Production State (Removed), plus the district's resident service requests as Communications. The next leg is the inspection-derived larval sample — the Feature Sample.

Product has settled the naming: Trap Sample (§25, adult, trap-derived) stays as it is; the inspection-derived larval sample is a distinct entity, the Feature Sample. Product owns the reference-ontology edit.

Deferred: the import is otherwise understood and ready to build; it is deferred until the entity and vocabularies below are settled.

Source data (Delta MVCD, org 1)

fieldseeker.inspectionsample — 3,458 versioned rows over 1,729 samples; insp_id resolves to the Inspection (mosquitoinspection.globalid) on 3,456 of them.
fieldseeker.inspectionsampledetail — 3,814 rows over 1,907 globalids (3,708 resolve to a sample).
A sample's processed (0/1) looks like the analysis state (0 = 936, 1 = 2,522); sampleid is its identifier (blank on 76).
Each detail row pairs a field identification (genus + counts: fieldspecies = Culex / Aedes / "Aedes, Culex") with a lab identification (species + counts: labspecies = Cx quinquefasciatus, Ae aegypti, Cx stigmatosoma, …); either side is often blank (field blank on 3,274 / 3,814; lab blank on 2,000).
Six count columns are always present (0 = none): flarvcount / fpupcount / feggcount (field) and llarvcount / lpupcount / leggcount (lab).
flstages is blank on 3,804 / 3,814; fdomstage is a dominant-stage text; fadultact is an adult-activity text.

What we need from Product

The Feature Sample entity. No Feature Sample definition exists in doc/nidus/reference/ontology/ today. Confirm/define: produced by exactly one Inspection, belongs to exactly one Feature, states Analyzed / Unanalyzed, an Identifier/Label, and supporting Type 1 (body/comments).
The count entity's axis is life stage, not sex. §26 Species Count is species-and-sex; a larval count is species-and-stage (instar 1–4, pupae, eggs). Confirm a Feature-Sample count keyed on (species, life stage) — and whether it must also carry sex for the adult aspiration / landing-count workflows (which are their own workflows).
Species vocabulary. §26 requires a controlled vocabulary; the source is free text, with genus-level (field) and species-level (lab) identifications and abbreviated genera (Cx, Ae, Cs). Is there a Nidus larval-species list, and is a genus-level identification a distinct thing from a species-level one?
One identification or two? Should each source row yield two counts (each tagged with its identification method — field vs lab), or normalise to the lab species when present?
Stage vocabulary. Is {instar 1, 2, 3, 4, pupae, eggs} the canonical set? (The six count columns are the signal; flstages / fdomstage look vestigial.)

Scope (already decided — no input needed)

A Feature Sample hangs off the Inspection (and hence its Feature); latest version per globalid.
Only non-zero counts are stored (§26 Rule 2 — no zero rows; absence is derived).
Excluded: the 2 samples whose insp_id resolves to no imported Inspection, and detail rows with no resolvable sample.

References

doc/nidus/fieldseeker-mapping/inspection.md — the Inspection mapping and its supporting artifacts.
doc/nidus/fieldseeker-ontology-mapping.md — shared scope; the larval-sample gap.
doc/nidus/fieldseeker-mapping/feature-import-plan.md — the settled decisions; this leg is recorded there as deferred pending the ontology.

## Context The FieldSeeker → Nidus import (see `doc/nidus/fieldseeker-mapping/`) has landed **Site**, **Feature**, **Inspection** (incl. notes), **Treatment** (incl. treated areas + the Product catalog) and **Production State** (`Removed`), plus the district's resident service requests as **Communications**. The next leg is the inspection-derived larval sample — the **Feature Sample**. Product has settled the naming: **Trap Sample** (§25, adult, trap-derived) stays as it is; the inspection-derived larval sample is a distinct entity, the **Feature Sample**. Product owns the reference-ontology edit. **Deferred:** the import is otherwise understood and ready to build; it is deferred until the entity and vocabularies below are settled. ## Source data (Delta MVCD, org 1) - `fieldseeker.inspectionsample` — 3,458 versioned rows over **1,729 samples**; `insp_id` resolves to the Inspection (`mosquitoinspection.globalid`) on 3,456 of them. - `fieldseeker.inspectionsampledetail` — 3,814 rows over 1,907 `globalid`s (3,708 resolve to a sample). - A sample's `processed` (0/1) looks like the analysis state (0 = 936, 1 = 2,522); `sampleid` is its identifier (blank on 76). - Each detail row pairs a **field** identification (genus + counts: `fieldspecies` = `Culex` / `Aedes` / `"Aedes, Culex"`) with a **lab** identification (species + counts: `labspecies` = `Cx quinquefasciatus`, `Ae aegypti`, `Cx stigmatosoma`, …); either side is often blank (field blank on 3,274 / 3,814; lab blank on 2,000). - Six count columns are always present (0 = none): `flarvcount` / `fpupcount` / `feggcount` (field) and `llarvcount` / `lpupcount` / `leggcount` (lab). - `flstages` is blank on 3,804 / 3,814; `fdomstage` is a dominant-stage text; `fadultact` is an adult-activity text. ## What we need from Product 1. **The Feature Sample entity.** No Feature Sample definition exists in `doc/nidus/reference/ontology/` today. Confirm/define: produced by exactly **one Inspection**, belongs to exactly **one Feature**, states **Analyzed / Unanalyzed**, an Identifier/Label, and supporting Type 1 (body/comments). 2. **The count entity's axis is life _stage_, not _sex_.** §26 Species Count is species-and-**sex**; a larval count is species-and-**stage** (instar 1–4, pupae, eggs). Confirm a Feature-Sample count keyed on **(species, life stage)** — and whether it must also carry **sex** for the adult aspiration / landing-count workflows (which are their own workflows). 3. **Species vocabulary.** §26 requires a controlled vocabulary; the source is free text, with genus-level (field) and species-level (lab) identifications and abbreviated genera (`Cx`, `Ae`, `Cs`). Is there a Nidus larval-species list, and is a genus-level identification a distinct thing from a species-level one? 4. **One identification or two?** Should each source row yield **two counts** (each tagged with its identification method — field vs lab), or normalise to the lab species when present? 5. **Stage vocabulary.** Is `{instar 1, 2, 3, 4, pupae, eggs}` the canonical set? (The six count columns are the signal; `flstages` / `fdomstage` look vestigial.) ## Scope (already decided — no input needed) - A Feature Sample hangs off the **Inspection** (and hence its Feature); latest version per `globalid`. - Only **non-zero** counts are stored (§26 Rule 2 — no zero rows; absence is derived). - Excluded: the 2 samples whose `insp_id` resolves to no imported Inspection, and detail rows with no resolvable sample. ## References - `doc/nidus/fieldseeker-mapping/inspection.md` — the Inspection mapping and its supporting artifacts. - `doc/nidus/fieldseeker-ontology-mapping.md` — shared scope; the larval-sample gap. - `doc/nidus/fieldseeker-mapping/feature-import-plan.md` — the settled decisions; this leg is recorded there as deferred pending the ontology.

eliribble referenced this issue from a commit

2026-09-24 21:24:54 +00:00

docs: defer Feature Samples pending the ontology, tracked as issue #253