AllenNeuralDynamics / AllenNeuralDynamics/aind-file-standards
Follow-up pass on the exaSPIM standard
- Ngôn ngữ chính
- Không có dữ liệu ngôn ngữ
- Star
- 0
- Fork
- 0
- Chỉ số merge pull request
- Không có pull request nào được merge trong 30 ngày
Mô tả
The exaSPIM specification that was merged in #69 doesn't yet line up with the conventions the rest of the repository follows, and with a few TODOs still in the text, it reads to me as though it's still being drafted. As it stands I don't think there's quite enough detail for someone to reproduce the format from the document alone.
Since it's already on main, the most useful thing is probably to treat this as a follow-up pass rather than undo the merge. The points below are what I'd suggest picking up.
One process thought for next time, not aimed at anyone in particular: for specifications like this, it might be worth leaving the PR open until the document is at a point where someone outside the team could reproduce the format from it. Standards are a bit unusual in that the published version is what people build against, so there's less room to merge and iterate than with code.
(Disclaimer: I drafted the points below with help from an LLM, giving it the repository standards and the merged specification as context. I've kept each one to a couple of lines and cut a fair amount of granular feedback to avoid stalling this, so happy to expand on any of them if that is useful. Finally, some of them may stem from my lack of familiarity with the format itself; apologies for that.)
## Summary
The document is a really useful first pass: it is the only written account of the exaSPIM primary and derived asset layout, and it captures pipeline knowledge that previously lived only in people's heads. Most of what follows is about carrying that description the rest of the way into something implementers and validators can lean on.
`contributing.md` asks contributions to follow the template structure and stay consistent with the `Core Standards`, and its standards-vs-documentation table describes specifications as **prescriptive** ("should be") rather than **descriptive** ("as is"). The document currently sits closer to the descriptive end, and since it is published on the docs site it is what readers will reach for as the exaSPIM standard — so it seems worth closing the gap.
## Import fixes
### 1. Requirements language (RFC 2119)
The document is written descriptively and doesn't yet use the RFC 2119 keywords adopted in [#55](https://github.com/AllenNeuralDynamics/aind-file-standards/issues/55), so the required components at [`:25`](docs/file_formats/exaspim.md#L25), the "possibly with a copy" at [`:48`](docs/file_formats/exaspim.md#L48), the raw-tier exclusion at [`:13`](docs/file_formats/exaspim.md#L13), and the QA rule at [`:83`](docs/file_formats/exaspim.md#L83) all read as description rather than requirement. Reworking these with `MUST` / `SHOULD` / `MAY` is probably the single change that does most to move the document from documentation toward standard.
### 2. Placement: file format vs. modality
By the taxonomy adopted in [#76](https://github.com/AllenNeuralDynamics/aind-file-standards/issues/76) and written into `contributing.md`, exaSPIM looks more like a **modality** than a self-contained reusable format, since it maps to a modality folder and composes several formats (OME-Zarr, `nii.gz`, `mat`, CSV). Suggest moving to `docs/modalities/exaspim.md`; the nav is generated by `docs/_mkdocs_hooks/_build.py`, so no manual edit is needed.
### 3. Immutability exception could use more explanation
Primary data is deleted after processing ([`:19`](docs/file_formats/exaspim.md#L19)) and derived assets are explicitly "not immutable" ([`:72-73`](docs/file_formats/exaspim.md#L72-L73)), both of which sit outside the asset model in `template.md`. Very likely the right calls given exaSPIM's data volumes, and easier to rely on with the reasoning in the body rather than an aside: what stands in for immutability, how a consumer tells that an asset is complete, and what the `.deleted` placeholder holds.
### 4. TODO markers still in the text
Two remain: `(*document columns*)` at [`:64`](docs/file_formats/exaspim.md#L64), where the soma table columns, units, and coordinate frames would be the highest-value thing to pin down, and the bare `- ...` stubs closing both Quality Assurance lists at [`:84`](docs/file_formats/exaspim.md#L84) and [`:88`](docs/file_formats/exaspim.md#L88).
## Mostly just clearing up some of the content
### 5. Status of `soma_detection`
[`:62`](docs/file_formats/exaspim.md#L62) documents a `soma_detection` subfolder that appears in neither the required components at [`:25`](docs/file_formats/exaspim.md#L25) nor the "other processes" list at [`:66`](docs/file_formats/exaspim.md#L66), so it is worth saying whether it is required, conditional, or optional.
### 6. Format details worth adding
Several formats are named without the detail a consumer needs: the OME-NGFF version at [`:19`](docs/file_formats/exaspim.md#L19) (v0.4 and v0.5 differ in how the asset is opened), the channel order and container type for `fused.zarr` at [`:42`](docs/file_formats/exaspim.md#L42), the CSV rules for `soma_locations.csv` at [`:64`](docs/file_formats/exaspim.md#L64), whether the transform names at [`:46`](docs/file_formats/exaspim.md#L46) follow a pattern beyond the one subject ID shown, and the contents of the seven `tile_alignment` subfolders at [`:30-38`](docs/file_formats/exaspim.md#L30-L38). Two small typos at [`:46`](docs/file_formats/exaspim.md#L46) as well, `formates` and `ANTS`.
### 7. Versioning
Closing items 4, 5, and 6 would change file names, columns, and requirements that `0.1.0` already specifies, which is more than a patch under the SemVer pillar in `contributing.md`, so it is worth deciding up front how the version moves (perhaps a single `0.2.0` for the whole pass).
Hướng dẫn đóng góp
Chưa lập chỉ mục được hướng dẫn đóng góp cho kho mã nguồn này
Đánh giá
Issue này chưa được đánh giá.