dcnum 0.25.5__tar.gz → 0.25.7__tar.gz

{dcnum-0.25.5 → dcnum-0.25.7}/.github/workflows/check.yml

@@ -12,6 +12,7 @@ jobs:
       matrix:
         python-version: ['3.10', '3.x']
         os: [macos-latest, ubuntu-latest, windows-latest]
+      fail-fast: false
     timeout-minutes: 30
 
     steps:

{dcnum-0.25.5 → dcnum-0.25.7}/.readthedocs.yml

@@ -5,6 +5,8 @@ build:
   os: ubuntu-22.04
   tools:
     python: "3.11"
+sphinx:
+  configuration: docs/conf.py
 python:
   install:
     - requirements: docs/requirements.txt

{dcnum-0.25.5 → dcnum-0.25.7}/CHANGELOG

@@ -1,3 +1,8 @@
+0.25.7
+ - enh: `HDF5Writer.store_log` returns created dataset
+ - docs: add code reference using apidoc
+0.25.6
+ - maintenance release
 0.25.5
  - enh: support unnamed table data in `HDF5Data`
  - setup: pin scipy<1.15 due to https://github.com/scipy/scipy/issues/22333
@@ -218,7 +223,7 @@
  - ref: increment DCNUM_PPID_GENERATION to 6
 0.13.3
  - fix: correctly raise KeyError for missing image-based feature from
-   HDF5Data._image_cache
+   `HDF5Data._image_cache`
 0.13.2
  - fix: properly convert variable-length string logs in `copy_metadata`
 0.13.1

{dcnum-0.25.5 → dcnum-0.25.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: dcnum
-Version: 0.25.5
+Version: 0.25.7
 Summary: numerics toolbox for imaging deformability cytometry
 Author: Maximilian Schlögel, Paul Müller, Raghava Alajangi
 Maintainer-email: Paul Müller <dev@craban.de>

dcnum-0.25.7/docs/.gitignore

@@ -0,0 +1 @@
+autoapi

{dcnum-0.25.5 → dcnum-0.25.7}/docs/conf.py

@@ -33,7 +33,7 @@ author = 'Paul Müller'
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = ['sphinx.ext.autodoc',
-              'sphinx.ext.autosummary',
+              'autoapi.extension',
               'sphinx.ext.intersphinx',
               'sphinx.ext.mathjax',
               'sphinx.ext.viewcode',
@@ -63,7 +63,7 @@ html_theme = 'sphinx_rtd_theme'
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+html_static_path = []
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -81,7 +81,6 @@ numfig = True
 # include source of matplotlib plots
 plot_include_source = True
 
-# http://www.sphinx-doc.org/en/stable/ext/autodoc.html#confval-autodoc_member_order
-# Order class attributes and functions in separate blocks
-autodoc_member_order = 'groupwise'
-autoclass_content = 'both'
+autoapi_dirs = ['../src/dcnum']
+autoapi_python_class_content = "init"
+autoapi_keep_files = True  # for debugging docstrings

{dcnum-0.25.5 → dcnum-0.25.7}/docs/index.rst

@@ -10,6 +10,7 @@ Welcome to dcnum's documentation!
    :maxdepth: 2
    :caption: Contents:
 
+   sec_design
 
 
 Indices and tables

{dcnum-0.25.5 → dcnum-0.25.7}/docs/requirements.txt

@@ -3,5 +3,7 @@ h5py
 ipython
 matplotlib
 numpy
-sphinx==4.2.0
-sphinx_rtd_theme==1.0
+sphinx>=5
+sphinx_rtd_theme
+sphinx-autoapi
+

dcnum-0.25.7/docs/sec_design.rst

@@ -0,0 +1,88 @@
+.. _sec_design:
+
+The design of dcnum
+===================
+
+
+Submodule Structure
+-------------------
+
+The general idea of dcnum is to have a toolset for processing raw DC data,
+which includes reading images, segmenting events, extracting features for
+each event, and writing to an output file.
+
+Each of the individual submodules serves one particular aspect of the
+pipeline:
+
+.. list-table:: dcnum submodules
+   :header-rows: 1
+
+   * - Submodule
+     - Description
+
+   * - :mod:`.feat`
+     - Feature extraction from segmented image data.
+
+   * - :mod:`.logic`
+     - | Contains the necessary logic (the glue) to combine all
+       | the other submodules for processing a dataset.
+
+   * - :mod:`.meta`
+     - | Handles metadata, most importantly the pipeline identifiers
+       | (PPIDs).
+
+   * - :mod:`.read`
+     - For reading raw HDF5 (.rtdc) files.
+
+   * - :mod:`.segm`
+     - | Event segmentation finds objects in an image and returns a
+       | binary mask for each object.
+
+   * - :mod:`.write`
+     - For writing data to HDF5 (.rtdc) files.
+
+
+Pipeline sequence
+-----------------
+
+A pipeline (including its PPID) is defined via the
+:class:`.logic.job.DCNumPipelineJob` class which represents the recipe for a
+pipeline. The pipeline is executed with the :class:`.logic.ctrl.DCNumJobRunner`.
+Here is a simple example that runs the default pipeline for an .rtdc file.
+
+.. code:: python
+
+    from dcnum.logic import DCNumPipelineJob, DCNumJobRunner
+
+    job = logic.DCNumPipelineJob(path_in="input.rtdc")
+    with logic.DCNumJobRunner(job=job) as runner:
+        runner.run()
+
+Take a look at the keyword arguments that the classes mentioned above
+accept. Note that you can specify methods for background correction as
+well as segmentation, and that you have full access to the keyword arguments
+for every step in the pipeline. Also note that a reproducible PPID is derived
+from these keyword arguments (:meth:`.logic.job.DCNumPipelineJob.get_ppid`).
+
+The following happens when you run the above code snippet:
+
+1. The file `input.rtdc` is opened using the module :mod:`.read`.
+2. The ``DCNumJobRunner`` creates two managers:
+
+   - :class:`.segm.segmenter_manager_thread.SegmenterManagerThread` which spawns
+     segmentation workers (subclasses of :class:`.segm.segmenter.Segmenter`)
+     in separate subprocesses.
+   - :class:`.feat.event_extractor_manager_thread.EventExtractorManagerThread`
+     which spawns feature extraction workers
+     (:class:`.feat.queue_event_extractor.QueueEventExtractor`) in
+     separate subprocesses.
+3. The segmentation workers read a chunk of image data and return the label
+   image (integer-valued labels, one mask per event in a frame).
+4. The label images are fed via a shared array to the feature extraction
+   workers.
+5. The feature extraction workers put the event information (one event per
+   unique integer-labeled mask in the label image) in the event queue.
+6. A :class:`write.queue_collector_thread.QueueCollectorThread` puts the
+   events in the right order and stages them for writing in chunks.
+7. A :class:`write.dequeue_writer_thread.DequeWriterThread` writes the
+   chunks to the output file.

{dcnum-0.25.5 → dcnum-0.25.7}/src/dcnum/_version.py

@@ -1,8 +1,13 @@
-# file generated by setuptools_scm
+# file generated by setuptools-scm
 # don't change, don't track in version control
+
+__all__ = ["__version__", "__version_tuple__", "version", "version_tuple"]
+
 TYPE_CHECKING = False
 if TYPE_CHECKING:
-    from typing import Tuple, Union
+    from typing import Tuple
+    from typing import Union
+
     VERSION_TUPLE = Tuple[Union[int, str], ...]
 else:
     VERSION_TUPLE = object
@@ -12,5 +17,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '0.25.5'
-__version_tuple__ = version_tuple = (0, 25, 5)
+__version__ = version = '0.25.7'
+__version_tuple__ = version_tuple = (0, 25, 7)

{dcnum-0.25.5 → dcnum-0.25.7}/src/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-0.25.5 → dcnum-0.25.7}/src/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-0.25.5 → dcnum-0.25.7}/src/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-0.25.5 → dcnum-0.25.7}/src/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-0.25.5 → dcnum-0.25.7}/src/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-0.25.5 → dcnum-0.25.7}/src/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-0.25.5 → dcnum-0.25.7}/src/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]