doc improvements

Author: h-mayorquin

src/probeinterface/neuropixels_tools.py

@@ -353,10 +353,11 @@ def build_neuropixels_probe(probe_part_number: str) -> Probe:
     """
     Build a Neuropixels probe with all possible contacts from the probe part number.
 
-    This function constructs a complete probe geometry including all physical contacts,
-    MUX table information, and probe-level metadata. The resulting probe contains ALL
-    electrodes (e.g., 960 for NP1.0, 1280 for NP2.0), not just the subset that might
-    be recorded in an actual experiment.
+    This function constructs a complete probe geometry based on IMEC manufacturer specifications
+    sourced from Bill Karsh's ProbeTable repository (https://github.com/billkarsh/ProbeTable).
+    The specifications include contact positions, electrode dimensions, shank geometry, MUX routing
+    tables, and ADC configurations. The resulting probe contains ALL electrodes (e.g., 960 for
+    NP1.0, 1280 for NP2.0), not just the subset that might be recorded in an actual experiment.
 
     Parameters
     ----------
@@ -681,65 +682,67 @@ def write_imro(file: str | Path, probe: Probe):
 
 def read_spikeglx(file: str | Path) -> Probe:
     """
-    Read probe position for the meta file generated by SpikeGLX
+    Read probe geometry and configuration from a SpikeGLX metadata file.
 
-    See http://billkarsh.github.io/SpikeGLX/#metadata-guides for implementation.
-    The x_pitch/y_pitch/width are set automatically depending on the NP version.
-
-    The shape is auto generated as a shank.
+    This function reconstructs the probe used in a recording by:
+    1. Reading the probe part number from metadata
+    2. Building the full probe geometry from manufacturer specifications
+    3. Slicing to the electrodes selected in the IMRO table
+    4. Further slicing to channels actually saved to disk (if subset was saved)
+    5. Adding recording-specific annotations
+    6. Add wiring (device channel indices)
 
     Parameters
     ----------
     file : Path or str
-        The .meta file path
+        Path to the SpikeGLX .meta file
 
     Returns
     -------
-    probe : Probe object
+    probe : Probe
+        Probe object with geometry, contact annotations, and device channel mapping
+
+    See Also
+    --------
+    http://billkarsh.github.io/SpikeGLX/#metadata-guides
 
     """
 
     meta_file = Path(file)
     assert meta_file.suffix == ".meta", "'meta_file' should point to the .meta SpikeGLX file"
 
     meta = parse_spikeglx_meta(meta_file)
-
     assert "imroTbl" in meta, "Could not find imroTbl field in meta file!"
-    imro_table = meta["imroTbl"]
 
-    # read serial number
-    imDatPrb_serial_number = meta.get("imDatPrb_sn", None)
-    if imDatPrb_serial_number is None:  # this is for Phase3A
-        imDatPrb_serial_number = meta.get("imProbeSN", None)
-
-    # read other metadata
+    # ===== 1. Extract probe part number from metadata =====
     imDatPrb_pn = meta.get("imDatPrb_pn", None)
-    imDatPrb_port = meta.get("imDatPrb_port", None)
-    imDatPrb_slot = meta.get("imDatPrb_slot", None)
-    imDatPrb_part_number = meta.get("imDatPrb_pn", None)
-
-    # Only Phase3a probe has "imProbeOpt". Map this to NP10101.
+    # Only Phase3a probe has "imProbeOpt". Map this to NP1010.
     if meta.get("imProbeOpt") is not None:
         imDatPrb_pn = "NP1010"
 
-    # ===== Step 1: Build full probe with all contacts =====
-    full_probe = build_neuropixels_probe(imDatPrb_pn)
+    # ===== 2. Build full probe with all possible contacts =====
+    # This creates the complete probe geometry (e.g., 960 contacts for NP1.0)
+    # based on manufacturer specifications
+    full_probe = build_neuropixels_probe(probe_part_number=imDatPrb_pn)
 
-    # ===== Step 2: Parse IMRO table to get active electrode IDs and settings =====
+    # ===== 3. Parse IMRO table to extract recorded electrodes and acquisition settings =====
+    # The IMRO table specifies which electrodes were selected for recording (e.g., 384 of 960),
+    # plus their acquisition settings (gains, references, filters)
+    imro_table = meta["imroTbl"]
     probe_type_num_chans, *imro_table_values_list, _ = imro_table.strip().split(")")
 
     # probe_type_num_chans looks like f"({probe_type},{num_chans}"
     probe_type = probe_type_num_chans.split(",")[0][1:]
 
     probe_features = _load_np_probe_features()
-    _, fields, _ = get_probe_metadata_from_probe_features(probe_features, imDatPrb_pn)
+    _, imro_fields, _ = get_probe_metadata_from_probe_features(probe_features, imDatPrb_pn)
 
     # Parse IMRO table values
-    contact_info = {k: [] for k in fields}
+    contact_info = {k: [] for k in imro_fields}
     for field_values_str in imro_table_values_list:  # Imro table values look like '(value, value, value, ... '
         # Split them by space to get int('value'), int('value'), int('value'), ...)
         values = tuple(map(int, field_values_str[1:].split(" ")))
-        for field, field_value in zip(fields, values):
+        for field, field_value in zip(imro_fields, values):
             contact_info[field].append(field_value)
 
     # Extract electrode IDs from IMRO table
@@ -754,8 +757,8 @@ def read_spikeglx(file: str | Path) -> Probe:
         banks = np.array(contact_info[bank_key])
         elec_ids = banks * 384 + channel_ids
 
-    # ===== Step 3: Slice full probe to active electrodes =====
-    # Find indices in full probe that match the active electrode IDs from IMRO
+    # ===== 4. Slice full probe to IMRO-selected electrodes =====
+    # Match the electrode IDs from IMRO table to contacts in the full probe
     keep_indices = []
     for elec_id in elec_ids:
         # For multi-shank probes, we need to check if shank info is in contact_info
@@ -773,35 +776,38 @@ def read_spikeglx(file: str | Path) -> Probe:
 
     probe = full_probe.get_slice(np.array(keep_indices, dtype=int))
 
-    # ===== Step 4: Add IMRO-specific annotations =====
-    # scalar annotations
+    # Add IMRO-specific contact annotations (acquisition settings)
     probe.annotate(probe_type=probe_type)
-
-    # vector annotations
     vector_properties = ("channel", "bank", "bank_mask", "ref_id", "ap_gain", "lf_gain", "ap_hipas_flt")
-
     vector_properties_available = {}
     for k, v in contact_info.items():
         if (k in vector_properties) and (len(v) > 0):
-            # convert to ProbeInterface naming for backwards compatibility
             vector_properties_available[imro_field_to_pi_field.get(k)] = v
-
     probe.annotate_contacts(**vector_properties_available)
 
-    # add serial number and other annotations
+    # ===== 5. Slice to saved channels (if subset was saved) =====
+    # This is DIFFERENT from IMRO selection: IMRO selects which electrodes to acquire,
+    # but SpikeGLX can optionally save only a subset of acquired channels to reduce file size.
+    # For example: IMRO selects 384 electrodes, but only 300 are saved to disk.
+    saved_chans = get_saved_channel_indices_from_spikeglx_meta(meta_file)
+    saved_chans = saved_chans[saved_chans < probe.get_contact_count()]  # Remove SYS channels
+    if saved_chans.size != probe.get_contact_count():
+        probe = probe.get_slice(saved_chans)
+
+    # ===== 6. Add recording-specific annotations =====
+    # These annotations identify the physical probe instance and recording setup
+    imDatPrb_serial_number = meta.get("imDatPrb_sn") or meta.get("imProbeSN")  # Phase3A uses imProbeSN
+    imDatPrb_port = meta.get("imDatPrb_port", None)
+    imDatPrb_slot = meta.get("imDatPrb_slot", None)
     probe.annotate(serial_number=imDatPrb_serial_number)
-    probe.annotate(part_number=imDatPrb_part_number)
+    probe.annotate(part_number=imDatPrb_pn)
     probe.annotate(port=imDatPrb_port)
     probe.annotate(slot=imDatPrb_slot)
 
-    # sometimes we need to slice the probe when not all channels are saved
-    saved_chans = get_saved_channel_indices_from_spikeglx_meta(meta_file)
-    # remove the SYS chans
-    saved_chans = saved_chans[saved_chans < probe.get_contact_count()]
-    if saved_chans.size != probe.get_contact_count():
-        # slice if needed
-        probe = probe.get_slice(saved_chans)
-    # wire it
+    # ===== 7. Set device channel indices (wiring) =====
+    # Device channel indices map probe contacts to data file channels.
+    # After all slicing, channels are numbered 0, 1, 2, ... N-1 in the order they appear
+    # in the binary data file, so we wire them sequentially.
     probe.set_device_channel_indices(np.arange(probe.get_contact_count()))
 
     return probe