Merge pull request #139 from khanlab/copilot/update-documentation-output-file-renaming

docs: update output directory structure to reflect naming refactor

Author: akhanf

docs/faq.md

@@ -160,14 +160,16 @@ Cohen's d interpretation:
 
 ### Where are my results?
 
-Results are in the output directory under `spimquant/`:
+Results are in the output directory under `spimquant/`. Outputs are organized across several subdirectories by type:
 ```
 output/spimquant/
 ├── sub-01/
-│   └── micr/
-│       ├── *_space-template_SPIM.nii.gz
-│       ├── *_dseg.nii.gz
-│       └── *_segstats.tsv
+│   ├── micr/       - registered images (*_space-{template}_SPIM.nii.gz) and masks
+│   ├── seg/        - full-resolution segmentation data (*_SPIM.ome.zarr)
+│   ├── parc/       - atlas parcellation maps (*_from-{template}_dseg.nii.gz)
+│   ├── tabular/    - statistics tables (*_segstats.tsv, *_regionpropstats.tsv, etc.)
+│   └── xfm/        - registration transforms
+└── group/          - group-level results (*_groupstats.tsv, *_groupstats.png, etc.)
 ```
 
 ### What format are the statistics in?

docs/getting_started/quickstart.md

@@ -97,25 +97,15 @@ Processing time depends on:
 
 ## Step 5: View Results
 
-After processing completes, find your results in the output directory:
-
-```
-output/
-└── spimquant/
-    ├── sub-01/
-    │   └── micr/
-    │       ├── sub-01_space-template_SPIM.nii.gz
-    │       ├── sub-01_space-template_dseg.nii.gz
-    │       └── sub-01_segstats.tsv
-    └── qc/
-        └── sub-01_registration_overlay.png
-```
+After processing completes, find your results in the output directory.
 
 Key output files:
 
-- `*_space-template_SPIM.nii.gz`: Registered SPIM data
-- `*_dseg.nii.gz`: Segmentation results
-- `*_segstats.tsv`: Quantitative statistics by brain region
+- `micr/*_space-{template}_SPIM.nii.gz`: Registered SPIM data in template space
+- `seg/*_mask.ozx`: Full-resolution segmentation results
+- `parc/*_from-{template}_dseg.nii.gz`: Atlas-based parcellation maps
+- `tabular/*_segstats.tsv`: Quantitative statistics by brain region
+- `group/*_groupstats.tsv`: Group-level statistical results
 
 ## Step 6: Generate a Report
 
@@ -204,4 +194,4 @@ pixi run spimquant ./bids ./output group \
   --contrast_column treatment \
   --contrast_values control drug \
   --cores all
-```
+```

docs/reference/outputs.md

@@ -7,59 +7,106 @@ Reference for SPIMquant output files and formats.
 ## Directory Structure
 
 ```
-output/
-└── spimquant/
-    ├── sub-01/
-    │   └── micr/
-    │       ├── *_space-template_SPIM.nii.gz
-    │       ├── *_dseg.nii.gz
-    │       └── *_segstats.tsv
-    └── qc/
+output/spimquant/
+├── sub-01/
+│   ├── micr/
+│   │   ├── *_space-{template}_SPIM.nii.gz
+│   │   ├── *_space-{template}_regqc.html
+│   │   └── *_mask.nii.gz
+│   ├── seg/
+│   │   └── *_SPIM.ome.zarr
+│   ├── parc/
+│   │   └── *_from-{template}_dseg.nii.gz
+│   ├── tabular/
+│   │   ├── *_segstats.tsv
+│   │   ├── *_regionpropstats.tsv
+│   │   ├── *_fieldfracstats.tsv
+│   │   └── *_countstats.tsv
+│   └── xfm/
+│       └── *_xfm.{txt,nii.gz}
+└── group/
+    ├── *_groupstats.tsv
+    ├── *_groupstats.png
+    └── *_groupstats.nii.gz
 ```
 
 ## Participant-Level Outputs
 
-<!-- TODO: Document participant outputs -->
+### Registered Images (`micr/`)
 
-### Registered Images
+`*_space-{template}_SPIM.nii.gz`
 
-`*_space-template_SPIM.nii.gz`
+Registered SPIM data in template space, stored as NIfTI files.
 
-<!-- TODO: Add file format details -->
+### Registration QC Reports (`micr/`)
 
-### Segmentation Maps
+`*_space-{template}_regqc.html`
 
-`*_dseg.nii.gz`
+HTML reports for visually checking registration quality.
 
-<!-- TODO: Add file format details -->
+### Brain Masks (`micr/`)
 
-### Statistics Tables
+`*_mask.nii.gz`
+
+Binary brain mask in subject space.
+
+### Segmentation Data (`seg/`)
+
+`*_SPIM.ome.zarr`
+
+Full-resolution segmentation results stored as OME-Zarr arrays.
+
+### Parcellation Maps (`parc/`)
+
+`*_from-{template}_dseg.nii.gz`
+
+Atlas-based discrete segmentation (parcellation) maps in subject space.
+
+### Statistics Tables (`tabular/`)
 
 `*_segstats.tsv`
 
-<!-- TODO: Add table format details -->
+Per-region segmentation statistics combining region properties, field fraction, and count metrics.
+
+`*_regionpropstats.tsv`
+
+Per-region object-level properties (e.g. volume, centroid).
+
+`*_fieldfracstats.tsv`
+
+Per-region field fraction (percentage of voxels positive) statistics.
+
+`*_countstats.tsv`
+
+Per-region object count statistics.
+
+### Transforms (`xfm/`)
+
+`*_xfm.txt` / `*_xfm.nii.gz`
+
+Affine and deformable registration transforms between subject and template space.
 
 ## Group-Level Outputs
 
-<!-- TODO: Document group outputs -->
+Group-level outputs are stored directly under `output/spimquant/group/` (no subject subdirectory).
 
 ### Statistical Results
 
 `*_groupstats.tsv`
 
-<!-- TODO: Add file format details -->
+Statistical test results (t-statistics, p-values, effect sizes) for each brain region.
 
 ### Visualizations
 
 `*_groupstats.png`
 
-<!-- TODO: Add visualization details -->
+Heatmap visualizations of statistical results across brain regions.
 
 ### Volume Maps
 
-`*_groupstats.nii`
+`*_groupstats.nii.gz`
 
-<!-- TODO: Add file format details -->
+3D volumetric maps of statistical values for visualization in neuroimaging software.
 
 ## Quality Control Outputs