sl-shared-assets 1.0.0rc14__py3-none-any.whl → 1.0.0rc15__py3-none-any.whl

sl_shared_assets/suite2p/multi_day.py

@@ -0,0 +1,193 @@
+"""This module stores the classes used to configure the multi-day (across-session) sl-suite2p pipeline. This pipeline
+extends the original suite2p code to support tracking the same objects (cells) across multiple days. Both single-day
+(original) and multi-day (extended) pipelines are available as part of the Sun lab maintained sl-suite2p package."""
+
+from typing import Any
+from dataclasses import field, asdict, dataclass
+
+from ataraxis_data_structures import YamlConfig
+
+
+@dataclass()
+class IO:
+    """Stores parameters that control data input and output during various stages of the pipeline."""
+
+    sessions: list[str] = field(default_factory=list)
+    """Specifies the list of sessions to register across days, as absolute paths to their /suite2p directories 
+    e.g: root/project/animal/session/processed_data/suite2p. The suite2p directory is created as part of the 
+    'single-day' suite2p runtime, assuming the default value of the 'save_folder' SingleDayS2PConfiguration class 
+    attribute was not modified. Note, each suite2p directory has to contain the 'combined' plane folder, which is 
+    created if the 'combined' SingleDayS2PConfiguration class attribute is 'True'."""
+
+    mesoscan: bool = True
+    """Indicates whether the processed session /suite2p folders contain registered Mesoscope frames."""
+
+
+@dataclass()
+class CellDetection:
+    """Stores parameters for selecting single-day-registered cells (ROIs) to be tracked across multiple sessions (days).
+
+    To maximize the tracking pipeline reliability, it is beneficial to pre-filter the cells whose identity (as cells)
+    is not certain or that may be hard to track across sessions.
+    """
+
+    probability_threshold: float = 0.85
+    """The minimum required probability score assigned to the cell (ROI) by the suite2p classifier. Cells with a lower 
+    classifier score are excluded from processing."""
+
+    maximum_size: int = 1000
+    """The maximum allowed cell (ROI) size, in pixels. Cells with a larger pixel size are excluded from processing."""
+
+    mesoscope_stripe_borders: list[int] = field(default_factory=list)
+    """Stores the x-coordinates of mesoscope combined image stripe (ROI) borders. For mesoscope images, 'stripes' are 
+    the individual imaging ROIs acquired in the 'multiple-ROI' mode. If this field is not overwritten by the user, the 
+    pipeline will read the border data from the combined plane 'ops.npy' file generated by single-day suite2p pipeline.
+    """
+
+    stripe_margin: int = 30
+    """The minimum required distance, in pixels, between the center-point (the median x-coordinate) of the cell (ROI) 
+    and the mesoscope stripe border. Cells that are too close to stripe borders are excluded from processing to avoid 
+    ambiguities associated with tracking cells that span multiple stripes."""
+
+
+@dataclass()
+class Registration:
+    """Stores parameters for aligning (registering) the sessions from multiple days to the same visual space.
+
+    Registration is used to create a 'shared' visual space, allowing to track the same cells (ROIs) across otherwise
+    variable visual space of each session.
+    """
+
+    image_type: str = "enhanced"
+    """The type of single-day suite2p-generated image to use for across-day registration. Supported options are 
+    'enhanced', 'mean' and 'max'. This 'template' image is used to calculate the necessary deformation (transformations)
+    to register (align) all sessions to the same visual space."""
+
+    grid_sampling_factor: float = 1
+    """Determines to what extent the grid sampling scales with the deformed image scale. Has to be between 0 and 1. By 
+    making this value lower than 1, the grid is relatively fine at the the higher scales, allowing for more 
+    deformations. This is used when resizing session images as part of the registration process."""
+
+    scale_sampling: int = 30
+    """The number of iterations for each level (i.e. between each factor two in scale) to perform when computing the 
+    deformations. Values between 20 and 30 are reasonable in most situations, but higher values yield better results in
+    general. The speed of the algorithm scales linearly with this value."""
+
+    speed_factor: float = 3
+    """The relative force of the deformation transform applied when registering the sessions to the same visual space.
+    This is the most important parameter to tune."""
+
+
+@dataclass()
+class Clustering:
+    """Stores parameters for clustering cell (ROI) masks across multiple registered sessions.
+
+    Clustering is used to track cells across sessions. If a group of ROIs across sessions is clustered together, it
+    is likely that they represent the same cell (ROI) across all sessions. This process involves first creating a
+    'template' mask that tracks a cell using the registered (deformed) visual space and then using this template to
+    track the cell in the original (non-deformed) visual space of each session.
+    """
+
+    criterion: str = "distance"
+    """Specifies the criterion for clustering (grouping) cell (ROI) masks from different sessions. Currently, the only 
+    valid option is 'distance'."""
+
+    threshold: float = 0.75
+    """Specifies the threshold for the clustering algorithm. Cell masks will be clustered (grouped) together if their  
+    clustering criterion is below this threshold value."""
+
+    mask_prevalence: int = 50
+    """Specifies the minimum percentage of all registered sessions that must include the clustered cell mask. Cell masks
+    present in fewer percent of sessions than this value are excluded from processing. This parameter is used to isolate
+    the cells that are present (active) across sessions."""
+
+    pixel_prevalence: int = 50
+    """Specifies the minimum percentage of all registered sessions in which a pixel from a given cell mask must be 
+    present for it to be used to construct the template mask. Pixels present in fewer percent of sessions than this 
+    value are not used to define the 'template' mask coordinates. Template masks are used to extract the cell 
+    fluorescence from the 'original' visual space of every session. This parameter is used to isolate the part of the
+    cell that is stable across sessions."""
+
+    step_sizes: list[int] = field(default_factory=lambda: [200, 200])
+    """Specifies the block size for the clustering process, in pixels. Clustering is applied in blocks of this size, 
+    sampled across the processed plane image, to reduce the memory (RAM) overhead."""
+
+    bin_size: int = 50
+    """Specifies the size of bins used to discover cell masks within blocks during clustering. To avoid edge cases, the 
+    algorithm clusters the cell masks within the region defined by the center-point of each cell +- bin_size."""
+
+    maximum_distance: int = 20
+    """Specifies the maximum distance, in pixels, that can separate masks across multiple sessions. The clustering 
+    algorithm will consider cell masks located at most within this distance from each-other across days as the same 
+    cells during tacking."""
+
+    minimum_size: int = 25
+    """The minimum size of the non-overlapping (with other cells) cell (ROI) region, in pixels, that has to be covered 
+    by the template mask, for the cell to be assigned to that template. This is used to determine which template(s) the 
+    cell belongs to (if any), for the purpose of tracking it across sessions."""
+
+
+@dataclass()
+class Demix:
+    """Stores settings used to deconvolve fluorescence signals from cells tracked across multiple days.
+
+    This step applies the suite2p spike deconvolution algorithm to the cell masks isolated during clustering to extract
+    the fluorescence of the cells tracked across multiple sessions (days). Generally, it should use the same parameters
+    as were used by the single-day suite2p pipeline.
+    """
+
+    baseline: str = "maximin"
+    """Specifies the method to compute the baseline of each trace. This baseline is then subtracted from each cell. 
+    ‘maximin’ computes a moving baseline by filtering the data with a Gaussian of width 'sig_baseline' * 'fs', and then 
+    minimum filtering with a window of 'win_baseline' * 'fs', and then maximum filtering with the same window. 
+    ‘constant’ computes a constant baseline by filtering with a Gaussian of width 'sig_baseline' * 'fs' and then taking 
+    the minimum value of this filtered trace. ‘constant_percentile’ computes a constant baseline by taking the 
+    'prctile_baseline' percentile of the trace."""
+
+    win_baseline: float = 60.0
+    """The time window, in seconds, over which to compute the baseline filter."""
+
+    sig_baseline: float = 10.0
+    """The standard deviation, in seconds, of the Gaussian filter applied to smooth the baseline signal."""
+
+    l2_reg: float = 0.1
+    """The L2 regularization strength applied during spike deconvolution."""
+
+    neucoeff: float = 0.7
+    """The neuropil coefficient applied for signal correction before deconvolution."""
+
+
+@dataclass()
+class MultiDayS2PConfiguration(YamlConfig):
+    """Aggregates all parameters for the multi-day suite2p pipeline used to track cells across multiple days
+    (sessions) and extract their activity.
+
+    These settings are used to configure the multiday suite2p extraction pipeline, which is based on the reference
+    implementation here: https://github.com/sprustonlab/multiday-suite2p-public. This class behaves similar to the
+    SingleDayS2PConfiguration class. It can be saved and loaded from a .YAML file and translated to dictionary format,
+    expected by the multi-day sl-suite2p pipeline.
+    """
+
+    cell_detection: CellDetection = field(default_factory=CellDetection)
+    """Stores parameters for selecting single-day-registered cells (ROIs) to be tracked across multiple sessions 
+    (days)."""
+    registration: Registration = field(default_factory=Registration)
+    """Stores parameters for aligning (registering) the sessions from multiple days to the same visual space."""
+    clustering: Clustering = field(default_factory=Clustering)
+    """Stores parameters for clustering (tracking) cell (ROI) masks across multiple registered sessions."""
+    demix: Demix = field(default_factory=Demix)
+    """Stores settings used to deconvolve fluorescence signals from cells tracked across multiple days."""
+    io: IO = field(default_factory=IO)
+    """Stores parameters that control data input and output during various stages of the pipeline."""
+
+    def to_ops(self) -> dict[str, Any]:
+        """Converts the class instance to a dictionary and returns it to caller.
+
+        This dictionary can be passed to sl-suite2p multi-day functions as the 'ops' argument.
+
+        Notes:
+            Unlike the single-day configuration class, the dictionary generated by this method uses section names as
+            top level keys and parameter names as second-level keys. This mimics the original multiday-pipeline
+            configuration scheme.
+        """
+        return asdict(self)

sl_shared_assets/suite2p/multi_day.pyi

@@ -0,0 +1,99 @@
+from typing import Any
+from dataclasses import field, dataclass
+
+from _typeshed import Incomplete
+from ataraxis_data_structures import YamlConfig
+
+@dataclass()
+class IO:
+    """Stores parameters that control data input and output during various stages of the pipeline."""
+
+    sessions: list[str] = field(default_factory=list)
+    mesoscan: bool = ...
+
+@dataclass()
+class CellDetection:
+    """Stores parameters for selecting single-day-registered cells (ROIs) to be tracked across multiple sessions (days).
+
+    To maximize the tracking pipeline reliability, it is beneficial to pre-filter the cells whose identity (as cells)
+    is not certain or that may be hard to track across sessions.
+    """
+
+    probability_threshold: float = ...
+    maximum_size: int = ...
+    mesoscope_stripe_borders: list[int] = field(default_factory=list)
+    stripe_margin: int = ...
+
+@dataclass()
+class Registration:
+    """Stores parameters for aligning (registering) the sessions from multiple days to the same visual space.
+
+    Registration is used to create a 'shared' visual space, allowing to track the same cells (ROIs) across otherwise
+    variable visual space of each session.
+    """
+
+    image_type: str = ...
+    grid_sampling_factor: float = ...
+    scale_sampling: int = ...
+    speed_factor: float = ...
+
+@dataclass()
+class Clustering:
+    """Stores parameters for clustering cell (ROI) masks across multiple registered sessions.
+
+    Clustering is used to track cells across sessions. If a group of ROIs across sessions is clustered together, it
+    is likely that they represent the same cell (ROI) across all sessions. This process involves first creating a
+    'template' mask that tracks a cell using the registered (deformed) visual space and then using this template to
+    track the cell in the original (non-deformed) visual space of each session.
+    """
+
+    criterion: str = ...
+    threshold: float = ...
+    mask_prevalence: int = ...
+    pixel_prevalence: int = ...
+    step_sizes: list[int] = field(default_factory=Incomplete)
+    bin_size: int = ...
+    maximum_distance: int = ...
+    minimum_size: int = ...
+
+@dataclass()
+class Demix:
+    """Stores settings used to deconvolve fluorescence signals from cells tracked across multiple days.
+
+    This step applies the suite2p spike deconvolution algorithm to the cell masks isolated during clustering to extract
+    the fluorescence of the cells tracked across multiple sessions (days). Generally, it should use the same parameters
+    as were used by the single-day suite2p pipeline.
+    """
+
+    baseline: str = ...
+    win_baseline: float = ...
+    sig_baseline: float = ...
+    l2_reg: float = ...
+    neucoeff: float = ...
+
+@dataclass()
+class MultiDayS2PConfiguration(YamlConfig):
+    """Aggregates all parameters for the multi-day suite2p pipeline used to track cells across multiple days
+    (sessions) and extract their activity.
+
+    These settings are used to configure the multiday suite2p extraction pipeline, which is based on the reference
+    implementation here: https://github.com/sprustonlab/multiday-suite2p-public. This class behaves similar to the
+    SingleDayS2PConfiguration class. It can be saved and loaded from a .YAML file and translated to dictionary format,
+    expected by the multi-day sl-suite2p pipeline.
+    """
+
+    cell_detection: CellDetection = field(default_factory=CellDetection)
+    registration: Registration = field(default_factory=Registration)
+    clustering: Clustering = field(default_factory=Clustering)
+    demix: Demix = field(default_factory=Demix)
+    io: IO = field(default_factory=IO)
+    def to_ops(self) -> dict[str, Any]:
+        """Converts the class instance to a dictionary and returns it to caller.
+
+        This dictionary can be passed to sl-suite2p multi-day functions as the 'ops' argument.
+
+        Notes:
+            Unlike the single-day configuration class, the dictionary generated by this method uses section names as
+            top level keys and parameter names as second-level keys. This mimics the original multiday-pipeline
+            configuration scheme.
+        """

sl_shared_assets/{suite2p.py → suite2p/single_day.py}

@@ -1,6 +1,7 @@
-"""This module provides the classes used to store suite2p runtime configuration parameters in .YAML files. This is used
-by the sl-forgery library to configure mesoscope data processing via the suite2p library, both during single-day and
-multiday registration processing."""
+"""This module stores the classes used to configure the single-day (within-session) sl-suite2p pipeline. This is the
+'original' suite2p pipeline used to process brain activity data collected as part of a single continuous recording. It
+is used as the first step of the multi-day brain activity processing pipeline used in the lab. Both single-day
+(original) and multi-day (extended) pipelines are available as part of the Sun lab maintained sl-suite2p package."""
 
 from typing import Any
 from dataclasses import field, asdict, dataclass
@@ -10,7 +11,7 @@ from ataraxis_data_structures import YamlConfig
 
 @dataclass
 class Main:
-    """Stores global settings used to broadly define the suite2p processing configuration."""
+    """Stores global parameters that broadly define the suite2p single-day processing configuration."""
 
     nplanes: int = 3
     """The number of imaging planes in each TIFF file sequence. For Mesoscope frames, this is the number of individual 
@@ -24,16 +25,17 @@ class Main:
 
     tau: float = 0.4
     """The timescale of the sensor, in seconds, used for computing the deconvolution kernel. The kernel is fixed to 
-    have this decay and is not fit to the data. Note, the default value was optimized for GCamp6f animals used in 
-    Weinan's OSM Manuscript."""
+    have this decay and is not fit to the data. Note, the default value is optimized for GCamp6f animals recorded with 
+    the Mesoscope."""
 
     force_sktiff: bool = True
-    """Determines whether to force the use of scikit-image for reading TIFF files. This HAS to be true for our tiff 
-    files, as they are compressed in a way that cannot be read with ScanImage tiff reader."""
+    """Determines whether to force the use of scikit-image for reading TIFF files. Generally, it is recommended to have 
+    this enabled as it forces suite2p to use tifffile library, which has better safety and compatibility than 
+    ScanImage tiff reader for certain types of tiff files."""
 
     fs: float = 10.0014
-    """The sampling rate per plane in Hertz. This is automatically overwritten using ops.json file generated by our 
-    preprocessing pipeline to match the specific acquisition frequency of the processed dataset."""
+    """The sampling rate per plane in Hertz. For instance, if you have a 10 plane recording acquired at 30Hz, then the 
+    sampling rate per plane is 3Hz, so set this to 3."""
 
     do_bidiphase: bool = False
     """Determines whether to perform computation of bidirectional phase offset for misaligned line scanning 
@@ -53,8 +55,8 @@ class Main:
      to process all available frames."""
 
     multiplane_parallel: bool = True
-    """Determines whether to parallelize plane processing for multiplane data. Assuming that this configuration class is
-    used together with Sun lab optimized suite2p, it is always recommended to have this set to True for most runtimes.
+    """Determines whether to parallelize plane processing for multiplane data. Note, while enabling this option improves
+    processing speeds, it also increases the memory (RAM) overhead resulting from processing all planes in-parallel.
     """
 
     ignore_flyback: list[int] = field(default_factory=list)
@@ -63,7 +65,7 @@ class Main:
 
 @dataclass
 class FileIO:
-    """Stores I/O settings used to specify input data file locations, formats, and output storage options."""
+    """Stores general I/O parameters that specify input data location, format, and working and output directories."""
 
     fast_disk: list[str] = field(default_factory=list)
     """Specifies the locations where to store the temporary binary files created during processing. If no directories 
@@ -107,7 +109,9 @@ class FileIO:
 
     save_folder: list[str] = field(default_factory=list)
     """Lists folder names under which the results should be stored. If this is not provided, the pipeline defaults to 
-    using 'suite2p' as the root folder, created under the path specified by save_path0."""
+    using 'suite2p' as the root folder, created under the path specified by save_path0. Note, if the data produced by 
+    the 'single-day' pipeline is also processed using sl-suite2p 'multi-day' pipeline, do not modify this field. The 
+    multi-day pipeline expects the save_folder to be 'suite2p' (default)."""
 
     look_one_level_down: bool = False
     """Determines whether to search for TIFF files in the subfolders when searching for Tiff files. If this is True, 
@@ -123,7 +127,7 @@ class FileIO:
 
 @dataclass
 class Output:
-    """Stores I/O settings used to define the output format and organization of the processing results."""
+    """Stores I/O settings that specify the output format and organization of the data processing results."""
 
     preclassify: float = 0.5
     """The probability threshold for pre-classification of cells to use before signal extraction. If this is set to 
@@ -149,7 +153,7 @@ class Output:
 
 @dataclass
 class Registration:
-    """Stores rigid registration settings used for correcting motion artifacts between frames."""
+    """Stores parameters for rigid registration, which is used to correct motion artifacts between frames."""
 
     do_registration: bool = True
     """Determines whether to run the motion registration."""
@@ -214,7 +218,8 @@ class Registration:
 
 @dataclass
 class OnePRegistration:
-    """Stores additional pre-registration processing settings used to improve the registration of 1-photon datasets."""
+    """Stores parameters for additional pre-registration processing used to improve the registration of 1-photon
+    datasets."""
 
     one_p_reg: bool = False
     """Determines whether to perform high-pass spatial filtering and tapering to improve one-photon image 
@@ -233,7 +238,8 @@ class OnePRegistration:
 
 @dataclass
 class NonRigid:
-    """Stores non-rigid registration settings used to improve motion registration in complex datasets."""
+    """Stores parameters for non-rigid registration, which is used to improve motion registration in complex
+    datasets."""
 
     nonrigid: bool = True
     """Determines whether to perform non-rigid registration to correct for local motion and deformation. This is used 
@@ -253,7 +259,7 @@ class NonRigid:
 
 @dataclass
 class ROIDetection:
-    """Stores ROI detection and extraction settings used to identify cells and their activity signals."""
+    """Stores parameters for cell ROI detection and extraction."""
 
     roidetect: bool = True
     """Determines whether to perform ROI detection and subsequent signal extraction."""
@@ -292,7 +298,8 @@ class ROIDetection:
     """The maximum number of iterations allowed for cell extraction."""
 
     nbinned: int = 5000
-    """The maximum number of binned frames to use for ROI detection to speed up processing."""
+    """The maximum number of binned frames to use for ROI detection. Settings this value to a higher number leads to 
+    more ROIs being detected, but reduces processing speed and increases RAM overhead."""
 
     denoise: bool = False
     """Determines whether to denoise the binned movie before cell detection in sparse mode to enhance performance. 
@@ -301,7 +308,7 @@ class ROIDetection:
 
 @dataclass
 class CellposeDetection:
-    """Stores Cellpose algorithm settings used for cell detection."""
+    """Stores parameters for the Cellpose algorithm, which can optionally be used to improve cell ROI extraction."""
 
     anatomical_only: int = 0
     """Specifies the Cellpose mode for cell detection:
@@ -332,7 +339,7 @@ class CellposeDetection:
 
 @dataclass
 class SignalExtraction:
-    """Stores settings used to extract fluorescence signals from ROIs and surrounding neuropil regions."""
+    """Stores parameters for extracting fluorescence signals from ROIs and surrounding neuropil regions."""
 
     neuropil_extract: bool = True
     """Determines whether to extract neuropil signals."""
@@ -353,10 +360,10 @@ class SignalExtraction:
 
 @dataclass
 class SpikeDeconvolution:
-    """Stores settings used to deconvolve calcium signals to infer spike trains."""
+    """Stores parameters for deconvolve fluorescence signals to infer spike trains."""
 
     spikedetect: bool = True
-    """Determines whether to perform spike deconvolution to convert calcium signals into estimated spike trains."""
+    """Determines whether to perform spike deconvolution."""
 
     neucoeff: float = 0.7
     """The neuropil coefficient applied for signal correction before deconvolution."""
@@ -382,7 +389,7 @@ class SpikeDeconvolution:
 
 @dataclass
 class Classification:
-    """Stores settings used to classify detected ROIs as real cells or artifacts."""
+    """Stores parameters for classifying detected ROIs as real cells or artifacts."""
 
     soma_crop: bool = True
     """Determines whether to crop dendritic regions from detected ROIs to focus on the cell body for classification 
@@ -397,20 +404,22 @@ class Classification:
 
 @dataclass
 class Channel2:
-    """Stores settings for processing the second channel in multichannel datasets."""
+    """Stores parameters for processing the second channel in multichannel datasets."""
 
     chan2_thres: float = 0.65
     """The threshold for considering an ROI registered in one channel as detected in the second channel."""
 
 
 @dataclass
-class Suite2PConfiguration(YamlConfig):
-    """Stores the user-addressable suite2p configuration parameters, organized into subsections.
+class SingleDayS2PConfiguration(YamlConfig):
+    """Stores the user-addressable suite2p configuration parameters for the single-day (original) pipeline, organized
+    into subsections.
 
-    This class is used during processing to instruct suite2p on how to process the data. Specifically, it provides a
-    user-friendly way of specifying all user-addressable parameters through a .YAML file. The sl-forgery library then
-    loads the data from .yaml file and uses it to configure the single-day suite2p pipeline and the multiday suite2p
-    pipeline.
+    This class is used during single-day processing to instruct suite2p on how to process the data. This class is based
+    on the 'default_ops' from the original suite2p package. As part of the suite2p refactoring performed in sl-suite2p
+    package, the 'default_ops' has been replaced with this class instance. Compared to 'original' ops, it allows saving
+    configuration parameters as a .YAML file, which offers a better way of viewing and editing the parameters and
+    running suite2p pipeline on remote compute servers.
 
     Notes:
         The .YAML file uses section names that match the suite2p documentation sections. This way, users can always
@@ -419,17 +428,31 @@ class Suite2PConfiguration(YamlConfig):
 
     # Define the instances of each nested settings class as fields
     main: Main = field(default_factory=Main)
+    """Stores global parameters that broadly define the suite2p single-day processing configuration."""
     file_io: FileIO = field(default_factory=FileIO)
+    """Stores general I/O parameters that specify input data location, format, and working and output directories."""
     output: Output = field(default_factory=Output)
+    """Stores I/O settings that specify the output format and organization of the data processing results."""
     registration: Registration = field(default_factory=Registration)
+    """Stores parameters for rigid registration, which is used to correct motion artifacts between frames."""
     one_p_registration: OnePRegistration = field(default_factory=OnePRegistration)
+    """Stores parameters for additional pre-registration processing used to improve the registration of 1-photon
+    datasets."""
     non_rigid: NonRigid = field(default_factory=NonRigid)
+    """Stores parameters for non-rigid registration, which is used to improve motion registration in complex 
+    datasets."""
     roi_detection: ROIDetection = field(default_factory=ROIDetection)
+    """Stores parameters for cell ROI detection and extraction."""
     cellpose_detection: CellposeDetection = field(default_factory=CellposeDetection)
+    """Stores parameters for the Cellpose algorithm, which can optionally be used to improve cell ROI extraction."""
     signal_extraction: SignalExtraction = field(default_factory=SignalExtraction)
+    """Stores parameters for extracting fluorescence signals from ROIs and surrounding neuropil regions."""
     spike_deconvolution: SpikeDeconvolution = field(default_factory=SpikeDeconvolution)
+    """Stores parameters for deconvolve fluorescence signals to infer spike trains."""
     classification: Classification = field(default_factory=Classification)
+    """Stores parameters for classifying detected ROIs as real cells or artifacts."""
     channel2: Channel2 = field(default_factory=Channel2)
+    """Stores parameters for processing the second channel in multichannel datasets."""
 
     def to_ops(self) -> dict[str, Any]:
         """Converts the class instance to a dictionary and returns it to caller.

sl_shared_assets/{suite2p.pyi → suite2p/single_day.pyi}

@@ -6,7 +6,7 @@ from ataraxis_data_structures import YamlConfig
 
 @dataclass
 class Main:
-    """Stores global settings used to broadly define the suite2p processing configuration."""
+    """Stores global parameters that broadly define the suite2p single-day processing configuration."""
 
     nplanes: int = ...
     nchannels: int = ...
@@ -23,7 +23,7 @@ class Main:
 
 @dataclass
 class FileIO:
-    """Stores I/O settings used to specify input data file locations, formats, and output storage options."""
+    """Stores general I/O parameters that specify input data location, format, and working and output directories."""
 
     fast_disk: list[str] = field(default_factory=list)
     delete_bin: bool = ...
@@ -43,7 +43,7 @@ class FileIO:
 
 @dataclass
 class Output:
-    """Stores I/O settings used to define the output format and organization of the processing results."""
+    """Stores I/O settings that specify the output format and organization of the data processing results."""
 
     preclassify: float = ...
     save_nwb: bool = ...
@@ -54,7 +54,7 @@ class Output:
 
 @dataclass
 class Registration:
-    """Stores rigid registration settings used for correcting motion artifacts between frames."""
+    """Stores parameters for rigid registration, which is used to correct motion artifacts between frames."""
 
     do_registration: bool = ...
     align_by_chan: int = ...
@@ -75,7 +75,8 @@ class Registration:
 
 @dataclass
 class OnePRegistration:
-    """Stores additional pre-registration processing settings used to improve the registration of 1-photon datasets."""
+    """Stores parameters for additional pre-registration processing used to improve the registration of 1-photon
+    datasets."""
 
     one_p_reg: bool = ...
     spatial_hp_reg: int = ...
@@ -84,7 +85,8 @@ class OnePRegistration:
 
 @dataclass
 class NonRigid:
-    """Stores non-rigid registration settings used to improve motion registration in complex datasets."""
+    """Stores parameters for non-rigid registration, which is used to improve motion registration in complex
+    datasets."""
 
     nonrigid: bool = ...
     block_size: list[int] = field(default_factory=Incomplete)
@@ -93,7 +95,7 @@ class NonRigid:
 
 @dataclass
 class ROIDetection:
-    """Stores ROI detection and extraction settings used to identify cells and their activity signals."""
+    """Stores parameters for cell ROI detection and extraction."""
 
     roidetect: bool = ...
     sparse_mode: bool = ...
@@ -110,7 +112,7 @@ class ROIDetection:
 
 @dataclass
 class CellposeDetection:
-    """Stores Cellpose algorithm settings used for cell detection."""
+    """Stores parameters for the Cellpose algorithm, which can optionally be used to improve cell ROI extraction."""
 
     anatomical_only: int = ...
     diameter: int = ...
@@ -121,7 +123,7 @@ class CellposeDetection:
 
 @dataclass
 class SignalExtraction:
-    """Stores settings used to extract fluorescence signals from ROIs and surrounding neuropil regions."""
+    """Stores parameters for extracting fluorescence signals from ROIs and surrounding neuropil regions."""
 
     neuropil_extract: bool = ...
     allow_overlap: bool = ...
@@ -131,7 +133,7 @@ class SignalExtraction:
 
 @dataclass
 class SpikeDeconvolution:
-    """Stores settings used to deconvolve calcium signals to infer spike trains."""
+    """Stores parameters for deconvolve fluorescence signals to infer spike trains."""
 
     spikedetect: bool = ...
     neucoeff: float = ...
@@ -142,7 +144,7 @@ class SpikeDeconvolution:
 
 @dataclass
 class Classification:
-    """Stores settings used to classify detected ROIs as real cells or artifacts."""
+    """Stores parameters for classifying detected ROIs as real cells or artifacts."""
 
     soma_crop: bool = ...
     use_builtin_classifier: bool = ...
@@ -150,18 +152,20 @@ class Classification:
 
 @dataclass
 class Channel2:
-    """Stores settings for processing the second channel in multichannel datasets."""
+    """Stores parameters for processing the second channel in multichannel datasets."""
 
     chan2_thres: float = ...
 
 @dataclass
-class Suite2PConfiguration(YamlConfig):
-    """Stores the user-addressable suite2p configuration parameters, organized into subsections.
-
-    This class is used during processing to instruct suite2p on how to process the data. Specifically, it provides a
-    user-friendly way of specifying all user-addressable parameters through a .YAML file. The sl-forgery library then
-    loads the data from .yaml file and uses it to configure the single-day suite2p pipeline and the multiday suite2p
-    pipeline.
+class SingleDayS2PConfiguration(YamlConfig):
+    """Stores the user-addressable suite2p configuration parameters for the single-day (original) pipeline, organized
+    into subsections.
+
+    This class is used during single-day processing to instruct suite2p on how to process the data. This class is based
+    on the 'default_ops' from the original suite2p package. As part of the suite2p refactoring performed in sl-suite2p
+    package, the 'default_ops' has been replaced with this class instance. Compared to 'original' ops, it allows saving
+    configuration parameters as a .YAML file, which offers a better way of viewing and editing the parameters and
+    running suite2p pipeline on remote compute servers.
 
     Notes:
         The .YAML file uses section names that match the suite2p documentation sections. This way, users can always