# Source code for neurokit2.rsp.rsp_rav

```
# -*- coding: utf-8 -*-
import numpy as np
import pandas as pd
from .rsp_fixpeaks import _rsp_fixpeaks_retrieve
[docs]
def rsp_rav(
amplitude,
peaks,
troughs=None,
):
"""**Respiratory Amplitude Variability (RAV)**
Computes indices of amplitude variability, such as the mean and SD of the amplitude, and the
RMSSD of the successive differences.
.. note::
This is an exploratory feature. If you manage to find studies and literature on RAV, please
let us know by opening an issue on GitHub. Adding more indices (similar to HRV) would be
trivial, but having some evidence as for its usefulness would be prerequisite.
Parameters
----------
amplitude : Union[list, np.array, pd.Series]
The amplitude signal as returned by :func:`.rsp_amplitude`.
peaks : list or array or DataFrame or Series or dict
The samples at which the inhalation peaks occur. If a dict or a DataFrame is passed, it is
assumed that these containers were obtained with :func:`.rsp_findpeaks`.
troughs : list or array or DataFrame or Series or dict
The samples at which the inhalation troughs occur. If a dict or a DataFrame is passed, it is
assumed that these containers were obtained with :func:`.rsp_findpeaks`. This argument can
be inferred from the ``peaks`` argument if the information.
Returns
-------
pd.DataFrame
A DataFrame of containing the following columns with RAV indices.
See Also
--------
rsp_amplitude, rsp_rrv
Examples
--------
.. ipython:: python
import neurokit2 as nk
rsp = nk.rsp_simulate(duration=45, respiratory_rate=15)
cleaned = nk.rsp_clean(rsp, sampling_rate=1000)
peak_signal, info = nk.rsp_peaks(cleaned, sampling_rate=1000)
amplitude = nk.rsp_amplitude(cleaned, peaks=peak_signal)
rav = nk.rsp_rav(amplitude, peaks=peak_signal)
rav
"""
# Format input.
peaks, troughs = _rsp_fixpeaks_retrieve(peaks, troughs)
# nk.signal_plot([cleaned, amplitude], subplots=True)
# Get values for each cycle
amplitude_discrete = amplitude[peaks]
diff_amp = np.diff(amplitude_discrete)
out = {} # Initialize empty dict
# Time domain ------------------------------
# Mean based
out["Mean"] = np.nanmean(amplitude_discrete)
out["SD"] = np.nanstd(amplitude_discrete, ddof=1)
out["RMSSD"] = np.sqrt(np.mean(diff_amp**2))
# out["SDSD"] = np.nanstd(diff_amp, ddof=1)
# out["CV"] = out["SD"] / out["Mean"]
out["CVSD"] = out["RMSSD"] / out["Mean"]
# # Robust
# out["Median"] = np.nanmedian(amplitude_discrete)
# out["Mad"] = mad(amplitude_discrete)
# out["MCV"] = out["Mad"] / out["Median"]
return pd.DataFrame.from_dict(out, orient="index").T.add_prefix("RAV_")
```