Repository: mne-tools/mne-python

Issue:
Rename temporal_derivative_distribution_repair to tddr
Can we rename `temporal_derivative_distribution_repair` to just `tddr`? I really think that the function name is too long (39 characters) - it makes it impossible to stay within the 79 character limit without using ugly `\` line breaks, e.g.:

```python
from mne.preprocessing.nirs import temporal_derivative_distribution_repair as tddr  # 82 characters
```

I think renaming to `tddr` is not problematic because the function is in the `nirs` subpackage, and TDDR is a commonly known abbreviation in the NIRS community (googling for "nirs tddr" immediately brings up several results with the correct method).

This issue came up in https://github.com/cbrnr/mnelab/pull/145 that @rob-luke is working on. He'd probably be fine with renaming because that's what he initially proposed.

And while we're at it, I'd like to rename `beer_lambert_law` to `beer_lambert` as well (we'd save 4 chars without losing any meaning).


Discussion:
As a newbie to the python/MNE way I defer to your collective judgement. Im happy to implement whatever the group decides here. 

Here is the prior comment regarding this issue: https://github.com/mne-tools/mne-python/pull/7556#discussion_r402854260
I pass here. Honestly I think we should use editors that autocomplete so
typing
long function names is not an issue. I am more worried about make the code
self explanatory. I am not a NIRS expert nor are new comers in the field and
abbreviations and jargon are always an issue. Yes when you know it's obvious
and google certainly has the answer. We use ICA and not
independent_component_analysis
so I guess my argument has some limits but I prefer to be too
verbose/explicit than
implicit.

Ok Im going to remove myself from the fence and vote for the longer more explicit naming.
I vote for the shorter name.
In general I agree with @agramfort, but this name is taking it too far. Plus it's like ICA, NIRS people should have heard of TDDR.
>  it's like ICA, NIRS people should have heard of TDDR.

Yes this seems to be true. I would, therefore, also appreciate the shorter name in this particular case, even though I'm normally a big fan of very explicit variable and function names.

Resolving patch:
diff --git a/examples/preprocessing/plot_fnirs_artifact_removal.py b/examples/preprocessing/plot_fnirs_artifact_removal.py
--- a/examples/preprocessing/plot_fnirs_artifact_removal.py
+++ b/examples/preprocessing/plot_fnirs_artifact_removal.py
@@ -16,8 +16,8 @@
 import os
 import mne
 
-from mne.preprocessing.nirs import (
-    optical_density, temporal_derivative_distribution_repair)
+from mne.preprocessing.nirs import (optical_density,
+                                    temporal_derivative_distribution_repair)
 
 ###############################################################################
 # Import data
diff --git a/mne/preprocessing/nirs/__init__.py b/mne/preprocessing/nirs/__init__.py
--- a/mne/preprocessing/nirs/__init__.py
+++ b/mne/preprocessing/nirs/__init__.py
@@ -6,9 +6,10 @@
 #
 # License: BSD (3-clause)
 
-from .nirs import short_channels, source_detector_distances, _check_channels_ordered,\
-    _channel_frequencies, _fnirs_check_bads, _fnirs_spread_bads
+from .nirs import (short_channels, source_detector_distances,
+                   _check_channels_ordered, _channel_frequencies,
+                   _fnirs_check_bads, _fnirs_spread_bads)
 from ._optical_density import optical_density
 from ._beer_lambert_law import beer_lambert_law
 from ._scalp_coupling_index import scalp_coupling_index
-from ._temporal_derivative_distribution_repair import temporal_derivative_distribution_repair
+from ._tddr import temporal_derivative_distribution_repair, tddr
diff --git a/mne/preprocessing/nirs/_temporal_derivative_distribution_repair.py b/mne/preprocessing/nirs/_tddr.py
similarity index 89%
rename from mne/preprocessing/nirs/_temporal_derivative_distribution_repair.py
rename to mne/preprocessing/nirs/_tddr.py
--- a/mne/preprocessing/nirs/_temporal_derivative_distribution_repair.py
+++ b/mne/preprocessing/nirs/_tddr.py
@@ -13,9 +13,9 @@
 
 
 def temporal_derivative_distribution_repair(raw):
-    r"""Apply temporal derivative distribution repair to data.
+    """Apply temporal derivative distribution repair to data.
 
-    Applies temporal derivative distribution repair (TDDR) to data.
+    Applies temporal derivative distribution repair (TDDR) to data
     :footcite:`FishburnEtAl2019`. This approach removes baseline shift
     and spike artifacts without the need for any user-supplied parameters.
 
@@ -30,6 +30,11 @@ def temporal_derivative_distribution_repair(raw):
     raw : instance of Raw
          Data with TDDR applied.
 
+    Notes
+    -----
+    There is a shorter alias ``mne.preprocessing.nirs.tddr`` that can be used
+    instead of this function (e.g. if line length is an issue).
+
     References
     ----------
     .. footbibliography::
@@ -47,9 +52,13 @@ def temporal_derivative_distribution_repair(raw):
     return raw
 
 
+# provide a short alias
+tddr = temporal_derivative_distribution_repair
+
+
 # Taken from https://github.com/frankfishburn/TDDR/ (MIT license).
 # With permission https://github.com/frankfishburn/TDDR/issues/1.
-# The only modification is the name,  scipy signal import and flake fixes.
+# The only modification is the name, scipy signal import and flake fixes.
 def _TDDR(signal, sample_rate):
     # This function is the reference implementation for the TDDR algorithm for
     #   motion correction of fNIRS data, as described in:
@@ -63,13 +72,13 @@ def _TDDR(signal, sample_rate):
     #   signals_corrected = TDDR( signals , sample_rate );
     #
     # Inputs:
-    #   signals: A [sample x channel] matrix of uncorrected
-    #            optical density data
+    #   signals: A [sample x channel] matrix of uncorrected optical density
+    #            data
     #   sample_rate: A scalar reflecting the rate of acquisition in Hz
     #
     # Outputs:
-    #   signals_corrected: A [sample x channel] matrix of corrected
-    #   optical density data
+    #   signals_corrected: A [sample x channel] matrix of corrected optical
+    #   density data
     from scipy.signal import butter, filtfilt
     signal = np.array(signal)
     if len(signal.shape) != 1:


Test patch:
diff --git a/mne/preprocessing/tests/test_temporal_derivative_distribution_repair.py b/mne/preprocessing/tests/test_temporal_derivative_distribution_repair.py
--- a/mne/preprocessing/tests/test_temporal_derivative_distribution_repair.py
+++ b/mne/preprocessing/tests/test_temporal_derivative_distribution_repair.py
@@ -9,8 +9,7 @@
 
 from mne.datasets.testing import data_path
 from mne.io import read_raw_nirx
-from mne.preprocessing.nirs import optical_density, \
-    temporal_derivative_distribution_repair
+from mne.preprocessing.nirs import optical_density, tddr
 from mne.datasets import testing
 
 
@@ -31,5 +30,5 @@ def test_temporal_derivative_distribution_repair(fname, tmpdir):
     raw._data[0, 0:30] = raw._data[0, 0:30] - (shift_amp)
     assert np.max(np.diff(raw._data[0])) > shift_amp
     # Ensure that applying the algorithm reduces the step change
-    raw = temporal_derivative_distribution_repair(raw)
+    raw = tddr(raw)
     assert np.max(np.diff(raw._data[0])) < shift_amp
diff --git a/mne/tests/test_docstring_parameters.py b/mne/tests/test_docstring_parameters.py
--- a/mne/tests/test_docstring_parameters.py
+++ b/mne/tests/test_docstring_parameters.py
@@ -249,6 +249,7 @@ def test_tabs():
 rescale
 setup_proj
 source_estimate_quantification
+tddr
 whiten_evoked
 write_fiducials
 write_info