dcnum 0.25.6__py3-none-any.whl → 0.25.8__py3-none-any.whl

dcnum/__init__.py

@@ -1,2 +1,25 @@
+"""Base library for deformability cytometry postprocessing
+MIT License
+
+Copyright (c) 2023 Paul Müller
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+"""
 # flake8: noqa: F401
 from ._version import __version__, __version_tuple__

dcnum/_version.py

@@ -17,5 +17,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '0.25.6'
-__version_tuple__ = version_tuple = (0, 25, 6)
+__version__ = version = '0.25.8'
+__version_tuple__ = version_tuple = (0, 25, 8)

dcnum/feat/event_extractor_manager_thread.py

@@ -35,8 +35,8 @@ class EventExtractorManagerThread(threading.Thread):
             with segmenter"), so that the segmenter can compute a new
             chunk of labels.
         slot_chunks:
-            For each slot in `slot_states`, this shared array defines
-            on which chunk in `image_data` the segmentation took place.
+            For each slot in ``slot_states``, this shared array defines
+            on which chunk in ``image_data`` the segmentation took place.
         fe_kwargs:
             Feature extraction keyword arguments. See
             :func:`.EventExtractor.get_init_kwargs` for more information.
@@ -47,36 +47,51 @@ class EventExtractorManagerThread(threading.Thread):
             fills up, we take a break.
         debug:
             Whether to run in debugging mode which means only one
-            event extraction thread (`num_workers` has no effect).
+            event extraction thread (``num_workers`` has no effect).
         """
         super(EventExtractorManagerThread, self).__init__(
               name="EventExtractorManager", *args, **kwargs)
         self.logger = logging.getLogger(
             "dcnum.feat.EventExtractorManagerThread")
-        #: Keyword arguments for class:`.EventExtractor`
+
         self.fe_kwargs = fe_kwargs
-        #: Data instance
+        """Keyword arguments
+        for :class:`event_extractor_manager_thread.py.QueueEventExtractor`
+        instances"""
+
         self.data = fe_kwargs["data"]
-        #: States of the segmenter-extractor pipeline slots
+        """Data instance"""
+
         self.slot_states = slot_states
-        #: Chunks indices corresponding to `slot_states`
+        """States of the segmenter-extractor pipeline slots"""
+
         self.slot_chunks = slot_chunks
-        #: Number of workers
+        """Chunk indices corresponding to ``slot_states``
+        """
+
         self.num_workers = 1 if debug else num_workers
-        #: Queue for sending chunks and label indices to the workers
+        """Number of workers"""
+
         self.raw_queue = self.fe_kwargs["raw_queue"]
-        #: List of chunk labels corresponding to `slot_states`
+        """Queue for sending chunks and label indices to the workers"""
+
         self.labels_list = labels_list
-        #: Shared labeling array
+        """List of chunk labels corresponding to ``slot_states``
+        """
+
         self.label_array = np.ctypeslib.as_array(
             self.fe_kwargs["label_array"]).reshape(
             self.data.image.chunk_shape)
-        #: Writer deque to monitor
+        """Shared labeling array"""
+
         self.writer_dq = writer_dq
-        #: Time counter for feature extraction
+        """Writer deque to monitor"""
+
         self.t_count = 0
-        #: Whether debugging is enabled
+        """Time counter for feature extraction"""
+
         self.debug = debug
+        """Whether debugging is enabled"""
 
     def run(self):
         # Initialize all workers

dcnum/feat/feat_background/base.py

@@ -21,7 +21,7 @@ mp_spawn = mp.get_context('spawn')
 class Background(abc.ABC):
     def __init__(self, input_data, output_path, compress=True, num_cpus=None,
                  **kwargs):
-        """
+        """Base class for background computation
 
         Parameters
         ----------
@@ -56,28 +56,35 @@ class Background(abc.ABC):
         # Using spec is not really necessary here, because kwargs are
         # fully populated for background computation, but this might change.
         spec = inspect.getfullargspec(self.check_user_kwargs)
-        #: background keyword arguments
+
         self.kwargs = spec.kwonlydefaults or {}
+        """background keyword arguments"""
         self.kwargs.update(kwargs)
 
         if num_cpus is None:
             num_cpus = mp_spawn.cpu_count()
-        #: number of CPUs used
+
         self.num_cpus = num_cpus
+        """number of CPUs used"""
 
-        #: number of images in the input data
         self.image_count = None
-        #: fraction images that have been processed
+        """number of images in the input data"""
+
         self.image_proc = mp_spawn.Value("d", 0)
+        """fraction images that have been processed"""
 
-        #: HDF5Data instance for input data
         self.hdin = None
-        #: input h5py.File
+        """HDF5Data instance for input data"""
+
         self.h5in = None
-        #: output h5py.File
+        """input h5py.File"""
+
         self.h5out = None
-        #: reference paths for logging to the output .rtdc file
+        """output h5py.File"""
+
         self.paths_ref = []
+        """reference paths for logging to the output .rtdc file"""
+
         # Check whether user passed an array or a path
         if isinstance(input_data, pathlib.Path):
             if str(input_data.resolve()) == str(output_path.resolve()):
@@ -96,10 +103,11 @@ class Background(abc.ABC):
         else:
             self.input_data = input_data
 
-        #: shape of event images
         self.image_shape = self.input_data[0].shape
-        #: total number of events
+        """shape of event images"""
+
         self.image_count = len(self.input_data)
+        """total number of events"""
 
         if self.h5out is None:
             if not output_path.exists():

dcnum/feat/feat_background/bg_copy.py

@@ -4,6 +4,10 @@ from .base import Background
 
 
 class BackgroundCopy(Background):
+    def __init__(self, *args, **kwargs):
+        """Copy the input background data to the output file"""
+        super().__init__(*args, **kwargs)
+
     @staticmethod
     def check_user_kwargs():
         pass

dcnum/feat/feat_background/bg_roll_median.py

@@ -42,7 +42,7 @@ class BackgroundRollMed(Background):
         batch_size: int
             Number of events to process at the same time. Increasing this
             number much more than two orders of magnitude larger than
-            `kernel_size` will not increase computation speed. Larger
+            ``kernel_size`` will not increase computation speed. Larger
             values lead to a higher memory consumption.
         compress: bool
             Whether to compress background data. Set this to False
@@ -64,39 +64,47 @@ class BackgroundRollMed(Background):
                              f"size {len(self.input_data)} is larger than the "
                              f"kernel size {kernel_size}!")
 
-        #: kernel size used for median filtering
         self.kernel_size = kernel_size
-        #: number of events processed at once
+        """kernel size used for median filtering"""
+
         self.batch_size = batch_size
+        """number of events processed at once"""
 
-        #: mp.RawArray for temporary batch input data
         self.shared_input_raw = mp_spawn.RawArray(
             np.ctypeslib.ctypes.c_uint8,
             int(np.prod(self.image_shape)) * (batch_size + kernel_size))
-        #: mp.RawArray for temporary batch output data
+        """mp.RawArray for temporary batch input data"""
+
         self.shared_output_raw = mp_spawn.RawArray(
             np.ctypeslib.ctypes.c_uint8,
             int(np.prod(self.image_shape)) * batch_size)
+        """mp.RawArray for temporary batch output data"""
+
         # Convert the RawArray to something we can write to fast
         # (similar to memoryview, but without having to cast) using
         # np.ctypeslib.as_array. See discussion in
         # https://stackoverflow.com/questions/37705974
-        #: numpy array reshaped view on `self.shared_input_raw` with
-        #: first axis enumerating the events
         self.shared_input = np.ctypeslib.as_array(
             self.shared_input_raw).reshape(batch_size + kernel_size, -1)
-        #: numpy array reshaped view on `self.shared_output_raw` with
-        #: first axis enumerating the events
+        """numpy array reshaped view on `self.shared_input_raw`.
+        The first axis enumerating the events
+        """
+
         self.shared_output = np.ctypeslib.as_array(
             self.shared_output_raw).reshape(batch_size, -1)
-        #: current batch index (see `self.process` and `process_next_batch`)
+        """numpy array reshaped view on `self.shared_output_raw`.
+        The first axis enumerating the events
+        """
+
         self.current_batch = 0
+        """current batch index (see `self.process` and `process_next_batch`)"""
 
-        #: counter tracking process of workers
         self.worker_counter = mp_spawn.Value("l", 0)
-        #: queue for median computation jobs
+        """counter tracking process of workers"""
+
         self.queue = mp_spawn.Queue()
-        #: list of workers (processes)
+        """queue for median computation jobs"""
+
         self.workers = [WorkerRollMed(self.queue,
                                       self.worker_counter,
                                       self.shared_input_raw,
@@ -104,6 +112,7 @@ class BackgroundRollMed(Background):
                                       self.batch_size,
                                       self.kernel_size)
                         for _ in range(self.num_cpus)]
+        """list of workers (processes)"""
         [w.start() for w in self.workers]
 
     def __enter__(self):
@@ -131,7 +140,7 @@ class BackgroundRollMed(Background):
         batch_size: int
             Number of events to process at the same time. Increasing this
             number much more than two orders of magnitude larger than
-            `kernel_size` will not increase computation speed. Larger
+            ``kernel_size`` will not increase computation speed. Larger
             values lead to a higher memory consumption.
         """
         assert kernel_size > 0, "kernel size must be positive number"
@@ -283,7 +292,7 @@ def compute_median_for_slice(shared_input, shared_output, kernel_size,
         in the original image, batch_size + kernel_size events are
         stored in this array one after another in a row.
         The total size of this array is
-        `batch_size` * `kernel_size` * `number_of_pixels_in_the_image`.
+        ``batch_size * kernel_size * number_of_pixels_in_the_image``.
     shared_output: multiprocessing.RawArray
         Used for storing the result. Note that the last `kernel_size`
         elements for each pixel in this output array are junk data

dcnum/feat/feat_background/bg_sparse_median.py

@@ -21,8 +21,8 @@ class BackgroundSparseMed(Background):
 
         In contrast to the rolling median background correction,
         this algorithm only computes the background image every
-        `split_time` seconds, but with a larger window (default kernel size is
-        200 frames instead of 100 frames).
+        ``split_time`` seconds, but with a larger window (default kernel
+        size is 200 frames instead of 100 frames).
 
         1. At time stamps every `split_time` seconds, a background image is
            computed, resulting in a background series.
@@ -103,16 +103,20 @@ class BackgroundSparseMed(Background):
                 f"size {len(self.input_data)}. Setting it to input data size!")
             kernel_size = len(self.input_data)
 
-        #: kernel size used for median filtering
         self.kernel_size = kernel_size
-        #: time between background images in the background series
+        """kernel size used for median filtering"""
+
         self.split_time = split_time
-        #: cleansing threshold factor
+        """time between background images in the background series"""
+
         self.thresh_cleansing = thresh_cleansing
-        #: keep at least this many background images from the series
+        """cleansing threshold factor"""
+
         self.frac_cleansing = frac_cleansing
-        #: offset/flickering correction
+        """keep at least this many background images from the series"""
+
         self.offset_correction = offset_correction
+        """offset/flickering correction"""
 
         # time axis
         self.time = None
@@ -142,48 +146,59 @@ class BackgroundSparseMed(Background):
             self.time = np.linspace(0, dur, self.image_count,
                                     endpoint=True)
 
-        #: duration of the measurement
         self.duration = self.time[-1] - self.time[0]
+        """duration of the measurement"""
 
         self.step_times = np.arange(0, self.duration, self.split_time)
-        #: array containing all background images
+
         self.bg_images = np.zeros((self.step_times.size,
                                    self.image_shape[0],
                                    self.image_shape[1]),
                                   dtype=np.uint8)
+        """array containing all background images"""
 
-        #: mp.RawArray for temporary batch input data
         self.shared_input_raw = mp_spawn.RawArray(
             np.ctypeslib.ctypes.c_uint8,
             int(np.prod(self.image_shape)) * kernel_size)
-        #: mp.RawArray for the median background image
+        """mp.RawArray for temporary batch input data"""
+
         self.shared_output_raw = mp_spawn.RawArray(
             np.ctypeslib.ctypes.c_uint8,
             int(np.prod(self.image_shape)))
+        """mp.RawArray for the median background image"""
+
         # Convert the RawArray to something we can write to fast
         # (similar to memoryview, but without having to cast) using
         # np.ctypeslib.as_array. See discussion in
         # https://stackoverflow.com/questions/37705974
-        #: numpy array reshaped view on `self.shared_input_raw` with
-        #: first axis enumerating the events
         self.shared_input = np.ctypeslib.as_array(
             self.shared_input_raw).reshape(kernel_size, -1)
+        """numpy array reshaped view on `self.shared_input_raw`.
+        The First axis enumerating the events
+        """
+
         self.shared_output = np.ctypeslib.as_array(
             self.shared_output_raw).reshape(self.image_shape)
-        #: multiprocessing pool for parallel processing
+        """numpy array reshaped view on `self.shared_output_raw`.
+        The First axis enumerating the events
+        """
+
         self.pool = mp_spawn.Pool(processes=self.num_cpus)
+        """multiprocessing pool for parallel processing"""
 
-        #: counter tracking process of workers
         self.worker_counter = mp_spawn.Value("l", 0)
-        #: queue for median computation jobs
+        """counter tracking process of workers"""
+
         self.queue = mp_spawn.Queue()
-        #: list of workers (processes)
+        """queue for median computation jobs"""
+
         self.workers = [WorkerSparseMed(self.queue,
                                         self.worker_counter,
                                         self.shared_input_raw,
                                         self.shared_output_raw,
                                         self.kernel_size)
                         for _ in range(self.num_cpus)]
+        """list of workers (processes)"""
         [w.start() for w in self.workers]
 
     def __enter__(self):

dcnum/feat/feat_contour/volume.py

@@ -35,7 +35,7 @@ def volume_from_contours(
     average is then used.
 
     The volume is computed radially from the center position
-    given by (`pos_x`, `pos_y`). For sufficiently smooth contours,
+    given by (``pos_x``, ``pos_y``). For sufficiently smooth contours,
     such as densely sampled ellipses, the center position does not
     play an important role. For contours that are given on a coarse
     grid, as is the case for deformability cytometry, the center position
@@ -111,7 +111,7 @@ def vol_revolve(r, z, point_scale=1.):
       V = \frac{h \cdot \pi}{3} \cdot (R^2 + R \cdot r + r^2)
 
     Where :math:`h` is the height of the cone and :math:`r` and
-    `R` are the smaller and larger radii of the truncated cone.
+    ``R`` are the smaller and larger radii of the truncated cone.
 
     Each line segment of the contour resembles one truncated cone. If
     the z-step is positive (counter-clockwise contour), then the

dcnum/feat/gate.py

@@ -9,8 +9,8 @@ from ..meta.ppid import kwargs_to_ppid, ppid_to_kwargs
 
 
 class Gate:
-    #: the default value for `size_thresh_mask` if not given as kwarg
     _default_size_thresh_mask = 10
+    """the default value for `size_thresh_mask` if not given as kwarg"""
 
     def __init__(self, data, *,
                  online_gates: bool = False,
@@ -19,7 +19,7 @@ class Gate:
 
         Parameters
         ----------
-        data: .HDF5Data
+        data: .hdf5_data.HDF5Data
             dcnum data instance
         online_gates: bool
             set to True to enable gating with "online" gates stored
@@ -27,14 +27,14 @@ class Gate:
             deformability cytometry before writing data to disk during
             a measurement
         size_thresh_mask: int
-            Only masks with more pixels than `size_thresh_mask` are
+            Only masks with more pixels than ``size_thresh_mask`` are
             considered to be a valid event; Originally, the
-            `bin area min`/`trig_thresh` value defaulted to 200 which is
+            ``bin area min / trig_thresh`` value defaulted to 200 which is
             too large; defaults to 10 or the original value in case
-            `online_gates` is set.
+            ``online_gates`` is set.
         """
-        #: box gating (value range for each feature)
         self.box_gates = {}
+        """box gating (value range for each feature)"""
 
         if online_gates:
             # Deal with online gates.
@@ -46,13 +46,13 @@ class Gate:
                 size_thresh_mask = data.meta_nest.get(
                     "online_contour", {}).get("bin area min")
 
-        #: gating keyword arguments
         self.kwargs = {
             "online_gates": online_gates,
             # Set the size threshold, defaulting to `_default_size_thresh_mask`
             "size_thresh_mask":
                 size_thresh_mask or self._default_size_thresh_mask
         }
+        """gating keyword arguments"""
 
     def _extract_online_gates(self, data):
         ogates = {}
@@ -168,10 +168,10 @@ class Gate:
                      data: numbers.Number | np.ndarray):
         """Return boolean indicating whether `data` value is in box gate
 
-        `data` may be a number or an array. If no box filter is defined
-        for `feat`, `True` is always returned. Otherwise, either a boolean
-        or a boolean array is returned, depending on the type of `data`.
-        Not that `np.logical_and` can deal with mixed argument types
+        ``data`` may be a number or an array. If no box filter is defined
+        for ``feat``, True is always returned. Otherwise, either a boolean
+        or a boolean array is returned, depending on the type of ``data``.
+        Not that ``np.logical_and`` can deal with mixed argument types
         (scalar and array).
         """
         bound_lo, bound_up = self.box_gates[feat]

dcnum/feat/queue_event_extractor.py

@@ -12,7 +12,7 @@ import numpy as np
 
 from ..os_env_st import RequestSingleThreaded, confirm_single_threaded
 from ..meta.ppid import kwargs_to_ppid, ppid_to_kwargs
-from ..read import HDF5Data
+from ..read.hdf5_data import HDF5Data
 
 from .feat_brightness import brightness_features
 from .feat_contour import moments_based_features, volume_from_contours
@@ -48,9 +48,9 @@ class QueueEventExtractor:
 
         Parameters
         ----------
-        data: HDF5Data
+        data: .hdf5_data.HDF5Data
             Data source.
-        gate: Gate
+        gate: .gate.Gate
             Gating rules.
         raw_queue:
             Queue from which the worker obtains the chunks and
@@ -84,41 +84,57 @@ class QueueEventExtractor:
             The index to increment values in `worker_monitor`
         """
         super(QueueEventExtractor, self).__init__(*args, **kwargs)
-        #: Worker index for populating
+
         self.worker_index = worker_index or 0
-        #: Data instance
+        """Worker index for populating"""
+
         self.data = data
-        #: Gating information
+        """Data instance"""
+
         self.gate = gate
-        #: queue containing sub-indices for `label_array`
+        """Gating information"""
+
         self.raw_queue = raw_queue
-        #: queue with event-wise feature dictionaries
+        """queue containing sub-indices for ``label_array``"""
+
         self.event_queue = event_queue
-        #: queue for logging
+        """queue with event-wise feature dictionaries"""
+
         self.log_queue = log_queue
-        #: invalid mask counter
+        """queue for logging"""
+
         self.invalid_mask_counter = invalid_mask_counter
-        #: worker busy counter
+        """invalid mask counter"""
+
         self.worker_monitor = worker_monitor
+        """worker busy counter"""
+
         # Logging needs to be set up after `start` is called, otherwise
         # it looks like we have the same PID as the parent process. We
         # are setting up logging in `run`.
         self.logger = None
         self.log_level = log_level or logging.getLogger("dcnum").level
-        #: Shared array of length `len(data)` into which the number of
-        #: events per frame is written.
+
         self.feat_nevents = feat_nevents
-        #: Shared array containing the labels of one chunk from `data`.
+        """Number of events per frame
+        Shared array of length `len(data)` into which the number of
+        events per frame is written.
+        """
+
         self.label_array = label_array
-        #: Set to True to let worker join when `raw_queue` is empty.
+        """Shared array containing the labels of one chunk from `data`."""
+
         self.finalize_extraction = finalize_extraction
+        """Set to True to let worker join when `raw_queue` is empty."""
+
         # Keyword arguments for data extraction
         if extract_kwargs is None:
             extract_kwargs = {}
         extract_kwargs.setdefault("brightness", True)
         extract_kwargs.setdefault("haralick", True)
-        #: Feature extraction keyword arguments.
+
         self.extract_kwargs = extract_kwargs
+        """Feature extraction keyword arguments."""
 
     @staticmethod
     def get_init_kwargs(data: HDF5Data,
@@ -127,18 +143,19 @@ class QueueEventExtractor:
                         log_queue: mp.Queue,
                         log_level: int = None,
                         ):
-        """Get initialization arguments for :cass:`.QueueEventExtractor`
+        """Get initialization arguments for :class:`.QueueEventExtractor`
 
         This method was created for convenience reasons:
+
         - It makes sure that the order of arguments is correct, since it
           is implemented in the same class.
         - It simplifies testing.
 
         Parameters
         ----------
-        data: HDF5Data
+        data: .hdf5_data.HDF5Data
             Input data
-        gate: HDF5Data
+        gate: .gate.Gate
             Gating class to use
         num_extractors: int
             Number of extractors that will be used
@@ -330,9 +347,11 @@ class QueueEventExtractor:
         self.worker_monitor[self.worker_index] = 0
         # Don't wait for these two queues when joining workers
         self.raw_queue.cancel_join_thread()
-        #: logger sends all logs to `self.log_queue`
+
         self.logger = logging.getLogger(
             f"dcnum.feat.EventExtractor.{os.getpid()}")
+        """logger that sends all logs to `self.log_queue`"""
+
         self.logger.setLevel(self.log_level)
         # Clear any handlers that might be set for this logger. This is
         # important for the case when we are an instance of

dcnum/logic/ctrl.py

@@ -39,8 +39,6 @@ from .json_encoder import ExtendedJSONEncoder
 # queues and threads and would end up with race conditions otherwise.
 mp_spawn = mp.get_context("spawn")
 
-#: valid states for a job runnter. The states must be in logical ordern,
-#: not in alphabetical order.
 valid_states = [
     "created",
     "init",
@@ -52,6 +50,9 @@ valid_states = [
     "done",
     "error",
 ]
+"""Valid states for a `DCNumJobRunner`.
+The states must be in logical order, not in alphabetical order.
+"""
 
 
 class DCNumJobRunner(threading.Thread):
@@ -59,11 +60,11 @@ class DCNumJobRunner(threading.Thread):
                  job: DCNumPipelineJob,
                  tmp_suffix: str = None,
                  *args, **kwargs):
-        """Run a pipeline as defined by a :class:`DCNumPipelineJob` instance
+        """Run a pipeline as defined by a :class:`.job.DCNumPipelineJob`
 
         Parameters
         ----------
-        job: DCNumPipelineJob
+        job: .job.DCNumPipelineJob
             pipeline job to run
         tmp_suffix: str
             optional unique string for creating temporary files

dcnum/logic/job.py

@@ -67,6 +67,7 @@ class DCNumPipelineJob:
             strategy on how to handle event data; In principle, not all
             events have to be stored in the output file if basins are
             defined, linking back to the original file.
+
             - You can "drain" all basins which means that the output file
               will contain all features, but will also be very big.
             - You can "tap" the basins, including the input file, which means
@@ -89,8 +90,9 @@ class DCNumPipelineJob:
             else:
                 basin_strategy = "tap"
 
-        #: initialize keyword arguments for this job
         self.kwargs = {}
+        """initialize keyword arguments for this job"""
+
         spec = inspect.getfullargspec(DCNumPipelineJob.__init__)
         locs = locals()
         for arg in spec.args: