Phase 04 — Document one real import→query→export round-trip
Working tree
Repository root. Requires cluster access for the
ingest/query, and the import-source endpoints. Owns a new Methods
subsection; if it adds a supplementary figure it lands in
supplementary_figures.tex after Phase 03 (serialize). Rebase article/
before editing methods.tex if Phase 01 already landed there.
Goal
The manuscript substantiates its interoperability claims (V2.2 Fig 5 import/export + Fig 7 tool integration) with one concrete, reproducible round-trip: import a real dataset from an external source (CAVE / NeuroMorpho / Neuroglancer) into SynDB, query it through the API, and export the result into an external analysis tool (Navis), captured as a Methods code listing (and optionally a small supplementary figure).
Why this matters now
Methods and Discussion claim import from CAVE/Neuroglancer/NeuroMorpho and export to Navis/Seaborn, but no figure or example demonstrates a working round-trip. V2.2 reserved Fig 5 (import/export) and Fig 7 (tool integration) for exactly this; both were never realised. One end-to-end example replaces both aspirational figures with evidence.
Out of scope
- Building new import connectors — use what already exists in
crates/.../etl. - A large multi-tool showcase — one clean round-trip is the deliverable.
- Re-deriving biology — this demonstrates plumbing, not a finding.
Plan
- Pick the lowest-friction real round-trip from existing connectors (e.g.
NeuroMorpho SWC import — already supported — → query cable length via API
→ load into Navis). Confirm the connector path in
crates/tools/etl/. - Execute it end-to-end against the cluster; capture the exact commands and a small result (e.g. a queried morphology rendered/summarised in Navis).
- Record the runnable transcript + any artifact under
article/reproducibility/(so it is reproducible, like the other evidence). - Add a new Methods subsection (“Interoperability round-trip”) with the
command listing and a one-paragraph description. Optionally add one
\suppfigure(e.g. “Fig S12: imported-then-exported morphology”) — if so, land it insupplementary_figures.texafter Phase 03 and keep S-numbering contiguous. - Build gate (
lualatex ×2,bibtexif a citation is added).
Acceptance criteria
- A reproducible transcript under
article/reproducibility/shows a real import → API query → external-tool export that runs end-to-end (exit 0, real data). - A new Methods subsection documents the round-trip with the exact commands.
- If a supplementary figure is added, it is
\suppfigure(S-numbered), build-clean, and does not disturb S1–S11 ordering (it becomes S12). - No claim of a round-trip that wasn’t actually executed.
Files likely touched
article/sections/methods.tex— new “Interoperability round-trip” subsection.article/sections/supplementary_figures.tex— optional Fig S12 (after Phase 03).article/reproducibility/— transcript + artifact.- possibly
article/references.bib(Navis/NeuroMorpho citations already present — reuse).
Pitfalls
- Symptom: import connector needs credentials/network the run lacks. Cause: external source auth. Recovery: choose a source that needs no auth (NeuroMorpho public SWC) for the demonstrated path.
- Symptom:
methods.texconflict. Cause: Phase 01 landed wording edits. Recovery: rebase; your new subsection is additive — re-apply after Phase 01’s paragraph. - Symptom: added Fig S12 renumbers other supp figures. Cause: inserted mid-list. Recovery: append at the end of the supplement figures block so existing S1–S11 are unchanged.
Reference
- Methods §“Interoperability and data import” (the claims this substantiates).
- V2.2 Figs 5 & 7 (
article/archive/SynDB_Manuscript_V2_2_CT.md). - Gap inventory items 5 & 7.