ADD flat_threshold argument in find_bad_by_nan_flat method from NoisyChannels

CITATION.cff

@@ -44,6 +44,9 @@ authors:
       family-names: Bialas
       affiliation: 'Department of Biomedical Engineering, University of Rochester, Rochester, NY, USA'
       orcid: 'https://orcid.org/0000-0003-4472-7626'
+    - given-names: Nabil
+      family-names: Alibou
+      affiliation: 'Biotrial, Neuroscience Department, Rennes, France'
 type: software
 repository-code: 'https://github.com/sappelhoff/pyprep'
 license: MIT

docs/matlab_differences.rst

@@ -18,6 +18,15 @@ PREP's internal math.
     :depth: 3
 
 
+Differences in ``find_bad_by_nan_flat``
+---------------------------------------
+
+Unlike in MATLAB PREP, PyPREP allows editing the threshold value for a channel
+to be considered 'bad-by-flat' by modifying the argument ``flat_threshold``
+in the method :meth:`~pyprep.NoisyChannels.find_bad_by_nan_flat`.
+However, the default value remains the same as in MATLAB PREP: ``1e-15`` volts
+(that is, 1e-9 microvolts).
+
 Differences in Signal Detrending
 --------------------------------
 

pyprep/find_noisy_channels.py

@@ -223,16 +223,23 @@ def find_all_bads(self, ransac=True, channel_wise=False, max_chunk_size=None):
                 channel_wise=channel_wise, max_chunk_size=max_chunk_size
             )
 
-    def find_bad_by_nan_flat(self):
+    def find_bad_by_nan_flat(self, flat_threshold=1e-15):
         """Detect channels than contain NaN values or have near-flat signals.
 
         A channel is considered flat if its standard deviation or its median
-        absolute deviation from the median (MAD) are below 1e-9 microvolts.
+        absolute deviation from the median (MAD) are below the provided flat
+        threshold (default: ``1e-15`` volts).
 
         This method is run automatically when a ``NoisyChannels`` object is
         initialized, preventing flat or NaN-containing channels from interfering
         with the detection of other types of bad channels.
 
+        Parameters
+        ----------
+        flat_threshold : float, optional
+            The lowest standard deviation or MAD value for a channel to be
+            considered bad-by-flat. Defaults to ``1e-15`` volts (corresponds to
+            10e-10 µV in MATLAB PREP).
         """
         # Get all EEG channels from original copy of data
         EEGData = self.raw_mne.get_data()
@@ -242,9 +249,8 @@ def find_bad_by_nan_flat(self):
         nan_channels = self.ch_names_original[nan_channel_mask]
 
         # Detect channels with flat or extremely weak signals
-        FLAT_THRESHOLD = 1e-15  # corresponds to 10e-10 µV in MATLAB PREP
-        flat_by_mad = _mad(EEGData, axis=1) < FLAT_THRESHOLD
-        flat_by_stdev = np.std(EEGData, axis=1) < FLAT_THRESHOLD
+        flat_by_mad = _mad(EEGData, axis=1) < flat_threshold
+        flat_by_stdev = np.std(EEGData, axis=1) < flat_threshold
         flat_channel_mask = flat_by_mad | flat_by_stdev
         flat_channels = self.ch_names_original[flat_channel_mask]