# -*- coding: utf-8 -*-
import numpy as np
from ..misc.report import get_kwargs
from .rsp_clean import rsp_clean
from .rsp_peaks import rsp_peaks
from .rsp_rvt import rsp_rvt
[docs]
def rsp_methods(
sampling_rate=1000,
method="khodadad",
method_cleaning="default",
method_peaks="default",
method_rvt="power",
**kwargs,
):
"""**RSP Preprocessing Methods**
This function analyzes and specifies the methods used in the preprocessing, and create a
textual description of the methods used. It is used by :func:`rsp_process()` to dispatch the
correct methods to each subroutine of the pipeline and :func:`rsp_report()` to create a
preprocessing report.
Parameters
----------
sampling_rate : int
The sampling frequency of the raw RSP signal (in Hz, i.e., samples/second).
method : str
The method used for cleaning and peak finding if ``"method_cleaning"``
and ``"method_peaks"`` are set to ``"default"``. Can be one of ``"Khodadad"``, ``"BioSPPy"``.
Defaults to ``"Khodadad"``.
method_cleaning: str
The method used to clean the raw RSP signal. If ``"default"``,
will be set to the value of ``"method"``. Defaults to ``"default"``.
For more information, see the ``"method"`` argument
of :func:`.rsp_clean`.
method_peaks: str
The method used to find peaks. If ``"default"``,
will be set to the value of ``"method"``. Defaults to ``"default"``.
For more information, see the ``"method"`` argument
of :func:`.rsp_peaks`.
method_rvt: str
The method used to compute respiratory volume per time. Defaults to ``"harrison"``.
For more information, see the ``"method"`` argument
of :func:`.rsp_rvt`.
**kwargs
Other arguments to be passed to :func:`.rsp_clean`,
:func:`.rsp_peaks`, and :func:`.rsp_rvt`.
Returns
-------
report_info : dict
A dictionary containing the keyword arguments passed to the cleaning
and peak finding functions, text describing the methods, and the corresponding
references.
See Also
--------
rsp_process, rsp_clean, rsp_findpeaks
Examples
--------
.. ipython:: python
import neurokit2 as nk
methods = nk.rsp_methods(sampling_rate=100, method="Khodadad", method_cleaning="hampel")
print(methods["text_cleaning"])
print(methods["references"][0])
"""
# Sanitize inputs
method_cleaning = (
str(method).lower() if method_cleaning == "default" else str(method_cleaning).lower()
)
method_peaks = str(method).lower() if method_peaks == "default" else str(method_peaks).lower()
method_rvt = str(method_rvt).lower()
# Create dictionary with all inputs
report_info = {
"sampling_rate": sampling_rate,
"method": method,
"method_cleaning": method_cleaning,
"method_peaks": method_peaks,
"method_rvt": method_rvt,
**kwargs,
}
# Get arguments to be passed to cleaning and peak finding functions
kwargs_cleaning, report_info = get_kwargs(report_info, rsp_clean)
kwargs_peaks, report_info = get_kwargs(report_info, rsp_peaks)
kwargs_rvt, report_info = get_kwargs(report_info, rsp_rvt)
# Save keyword arguments in dictionary
report_info["kwargs_cleaning"] = kwargs_cleaning
report_info["kwargs_peaks"] = kwargs_peaks
report_info["kwargs_rvt"] = kwargs_rvt
# Initialize refs list with NeuroKit2 reference
refs = ["""Makowski, D., Pham, T., Lau, Z. J., Brammer, J. C., Lespinasse, F., Pham, H.,
Schölzel, C., & Chen, S. A. (2021). NeuroKit2: A Python toolbox for neurophysiological signal processing.
Behavior Research Methods, 53(4), 1689–1696. https://doi.org/10.3758/s13428-020-01516-y
"""]
# 1. Cleaning
# ------------
report_info["text_cleaning"] = f"The raw signal, sampled at {sampling_rate} Hz,"
if method_cleaning in ["khodadad", "khodadad2018"]:
report_info["text_cleaning"] += (
" was preprocessed using a second order 0.05-3 Hz bandpass Butterworth filter."
)
elif method_cleaning in ["hampel", "power", "power2020"]:
report_info["text_cleaning"] += (
" was preprocessed using a median-based Hampel filter by replacing values which"
+ f' are {report_info.get("threshold", 3)} median absolute deviation away from the rolling median;'
+ "following Power et al. 2020."
)
refs.append(
"""Power, J., Lynch, C., Dubin, M., Silver, B., Martin, A., Jones, R.,(2020)
Characteristics of respiratory measures in young adults scanned at rest,
including systematic changes and “missed” deep breaths.
NeuroImage, Volume 204, 116234"""
)
elif method_cleaning in ["biosppy"]:
report_info["text_cleaning"] += (
" was preprocessed using a second order 0.1-0.35 Hz bandpass "
+ "Butterworth filter followed by a constant detrending."
)
elif method_cleaning in ["none"]:
report_info[
"text_cleaning"
] += " was directly used for peak detection without preprocessing."
else:
# just in case more methods are added
report_info["text_cleaning"] += f" was cleaned following the {method} method."
# 2. Peaks
# ----------
if method_peaks in ["khodadad", "khodadad2018"]:
report_info[
"text_peaks"
] = "The peak detection was carried out using the method described in Khoadadad et al. (2018)."
refs.append(
"""Khodadad, D., Nordebo, S., Müller, B., Waldmann, A., Yerworth, R., Becher, T., ... & Bayford, R. (2018).
Optimized breath detection algorithm in electrical impedance tomography.
Physiological measurement, 39(9), 094001."""
)
elif method_peaks in ["biosppy"]:
report_info[
"text_peaks"
] = "The peak detection was carried out using the method provided by the Python library BioSPpy (/signals/resp.py)."
elif method_peaks in ["scipy"]:
report_info[
"text_peaks"
] = "The peak detection was carried out using the method provided by the Python library SciPy (signal.find_peaks)."
elif method_peaks in ["none"]:
report_info["text_peaks"] = "There was no peak detection carried out."
else:
report_info[
"text_peaks"
] = f"The peak detection was carried out using the method {method_peaks}."
# 3. RVT
# ----------
if method_rvt in ["harrison", "harrison2021"]:
report_info[
"text_rvt"
] = "The respiratory volume per time computation was carried out using the method described in Harrison et al. (2021)."
refs.append(
"""Harrison, S. J., Bianchi, S., Heinzle, J., Stephan, K. E., Iglesias, S., & Kasper, L. (2021).
A Hilbert-based method for processing respiratory timeseries.
Neuroimage, 230, 117787."""
)
elif method_rvt in ["birn", "birn2006"]:
report_info[
"text_rvt"
] = "The respiratory volume per time computation was carried out using the method described in Birn et al. (2006)."
refs.append(
"""Birn, R. M., Diamond, J. B., Smith, M. A., & Bandettini, P. A. (2006).
Separating respiratory-variation-related fluctuations from neuronal-activity-related fluctuations in
fMRI. Neuroimage, 31(4), 1536-1548."""
)
elif method_rvt in ["power", "power2020"]:
report_info[
"text_rvt"
] = "The respiratory volume per time computation was carried out using the method described in Power at al. (2020)."
refs.append(
"""Power, J. D., Lynch, C. J., Dubin, M. J., Silver, B. M., Martin, A., & Jones, R. M. (2020).
Characteristics of respiratory measures in young adults scanned at rest, including systematic
changes and "missed" deep breaths. Neuroimage, 204, 116234."""
)
elif method_rvt in ["none"]:
report_info["text_rvt"] = "Respiratory volume per time was not computed."
else:
report_info[
"text_rvt"
] = f"The respiratory volume per time computation was carried out using the method described in {method_rvt}."
report_info["references"] = list(np.unique(refs))
return report_info
