Re-work registration woes, add a bunch of fixes

docs/index.md

@@ -1,4 +1,4 @@
-![https://www.mesoscopy.org](../assets/mesoscopy-logo-banner.png)
+![https://www.mesoscopy.org](assets/mesoscopy-logo-banner.png)
 
 ---
 

docs/typical-workflow.md

@@ -23,12 +23,44 @@ mesoscopy preprocess /path/to/example-recording.nwb
 
 ## Register to the Allen Brain Atlas
 
+First mark the anatomical landmarks on the recording. This opens the napari landmark GUI, seeded
+with a point per landmark: drag each one onto its anatomical location, then press **Save and Close**.
+
 ```bash
-mesoscopy register mark-landmarks /path/to/example-recording.nwb
+mesoscopy register label /path/to/example-recording.nwb
+```
+
+This writes `example-recording_landmarks.csv` to the output directory (`-o`, the current directory
+by default), holding each landmark's `(x, y)` position in the pixel space of the ∆F/F series.
+
+Then warp the recording onto the atlas. The landmarks file is found automatically if it sits next to
+the recording or in the output directory; pass `-r/--recording-points` to point at it explicitly.
+
+```bash
+mesoscopy register landmarks /path/to/example-recording.nwb
+```
+
+The registered frames are written in Allen CCF template space at the atlas's own dimensions, which
+is what `mesoscopy process area-responses` expects. Use `--output-width` / `--output-height` only if
+you are registering onto a different template.
+
+!!! note
+    `-t/--template-points` supplies the *template* landmarks being registered onto, not your
+    recording's landmarks. Leave it unset to use the Allen CCF landmarks that ship with mesoscopy.
+
+Registration reports how far each landmark ends up from its template position, and warns if the fit
+is poor:
+
+```
+Estimating transform from 9 landmarks...
+Landmark fit: RMSE 2.28 px, worst is 'rFP' at 3.94 px (in template pixels).
 ```
 
+To check the alignment visually, generate the QA report for the registered HDF5 file written by the
+step above — its path is echoed as `Saved registered frames at ...`:
+
 ```bash
-mesoscopy register landmarks --template-points example-recording_landmarks.csv /path/to/example-recording.nwb
+mesoscopy report /path/to/example-recording_registered.h5
 ```
 
 ## Extract area responses

src/mesoscopy/io.py

@@ -59,14 +59,16 @@ def read_nwb(path: str, mode: str = "a", return_io: bool = False) -> NWBFile | t
     return nwbfile
 
 
-def write_nwb(path: str, nwbfile: NWBFile, mode: str = "w", io: NWBHDF5IO = None, **kwargs) -> None:
+def write_nwb(path: str, nwbfile: NWBFile, mode: str = "w", io: NWBHDF5IO = None, **kwargs: typing.Any) -> None:
     """Write an NWB file.
 
     Args:
         path (str): Path to the NWB file.
         nwbfile (NWBFile): NWB file object.
         mode (str, optional): File write mode (i.e. write/append). Defaults to "w".
-        **kwargs: Parameters passed to NWBHDF5IO.write.
+        io (NWBHDF5IO, optional): An already open IO object to write through. When given, the file
+            is not reopened and `path` and `mode` are ignored. Defaults to None.
+        **kwargs (typing.Any): Parameters passed to NWBHDF5IO.write.
     """
     if io:
         return io.write(nwbfile, **kwargs)
@@ -188,11 +190,13 @@ def load_deltaf(path: str, nwb: bool = False) -> tuple[str, np.ndarray, np.ndarr
 def read_points(path: str) -> dict[str, tuple[float, float]]:
     """Read a landmark points file.
 
+    Coordinates are read as (x, y) tuples, i.e. (column, row).
+
     Args:
         path (str): Path to the points file.
 
     Returns:
-        dict[str, tuple[float, float]]: Dictionary with the landmark names as keys and their x-y coordinates
+        dict[str, tuple[float, float]]: Dictionary with the landmark names as keys and their (x, y) coordinates
 
     Raises:
         ValueError: If the file format is unsupported.
@@ -293,9 +297,11 @@ def _read_csv_points(path: str) -> dict[str, tuple[float, float]]:
 def write_points(path: str, points: dict[str, tuple[float, float]]) -> None:
     """Write a dictionary of landmark points to a CSV file.
 
+    Coordinates are written as (x, y) tuples, i.e. (column, row).
+
     Args:
         path (str): Path to output CSV file.
-        points (dict[str, tuple[float, float]]): Dictionary with the landmark names as keys and their x-y coordinates
+        points (dict[str, tuple[float, float]]): Dictionary with the landmark names as keys and their (x, y) coordinates
     """
     if not path.endswith(".csv"):
         path += ".csv"

src/mesoscopy/preprocess/__init__.py

@@ -127,10 +127,10 @@ def run_preprocessing(
         chunks (int, optional): Number of chunks to load in memory. Defaults to 100.
         crop (int, optional): Number of pixels to crop from the edges of the recording. Defaults to 0.
         bins (int, optional): Recording pixel binning factor. Defaults to 2.
-        channel_means_only (bool, optional): Extract the channel means and exit without extracting a delta F series.
-        Defaults to False.
-        use_means (bool, optional): Use means histogram instead of standard deviation to separate channels.
-        Defaults to False.
+        channel_means_only (bool, optional): Extract the channel means and exit without extracting a
+            delta F series. Defaults to False.
+        use_means (bool, optional): Use means histogram instead of standard deviation to separate
+            channels. Defaults to False.
         flip_channels (bool, optional): Flip extracted channel order. Defaults to False.
         interim_dir (str, optional): Path to the interim directory. Defaults to "interim/".
         skip_start (int, optional): Number of frames to skip at the start of the recording. Defaults to None.