Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

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

  1. 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/.
  2. 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).
  3. Record the runnable transcript + any artifact under article/reproducibility/ (so it is reproducible, like the other evidence).
  4. 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 in supplementary_figures.tex after Phase 03 and keep S-numbering contiguous.
  5. Build gate (lualatex ×2, bibtex if 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.tex conflict. 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.