Skip to content

Commit a0f2bdc

Browse files
peterdsharpepeterdsharpe
committed
Standardize docstrings to numpydoc in tools/statistics
1 parent d924866 commit a0f2bdc

1 file changed

Lines changed: 76 additions & 55 deletions

File tree

‎aerosandbox/tools/statistics/time_series_uncertainty_quantification.py‎

Lines changed: 76 additions & 55 deletions
Original file line numberDiff line numberDiff line change
@@ -15,32 +15,39 @@ def estimate_noise_standard_deviation(
1515
estimator_order: int | None = None,
1616
) -> float:
1717
"""
18-
Estimates the standard deviation of the random noise in a time-series dataset.
18+
Estimate the standard deviation of the random noise in a time-series dataset.
1919
2020
Relies on several assumptions:
2121
2222
- The noise is normally-distributed and independent between samples (i.e. white noise).
2323
24-
- The noise is stationary and homoscedastic (i.e., the noise standard deviation is constant).
24+
- The noise is stationary and homoscedastic (i.e., the noise standard deviation is
25+
constant).
2526
2627
- The noise is uncorrelated with the signal.
2728
28-
- The sample rate of the data is significantly higher than the highest-frequency component of the signal. (In
29-
practice, this ratio need not be more than ~5:1, if higher-order estimators are used. At a minimum, however,
30-
this ratio must be greater than 2:1, corresponding to the Nyquist frequency.)
31-
32-
The algorithm used in this function is a highly-optimized version of the math described in this repository,
33-
part of an upcoming paper: https://github.com/peterdsharpe/aircraft-polar-reconstruction-from-flight-test
34-
35-
Args:
36-
37-
data: A 1D NumPy array of time-series data.
38-
39-
estimator_order: The order of the estimator to use. Higher orders are generally more accurate, up to the
40-
point where sample error starts to dominate. If None, a reasonable estimator order will be chosen automatically.
41-
42-
Returns: An estimate of the standard deviation of the data's noise component.
43-
29+
- The sample rate of the data is significantly higher than the highest-frequency component
30+
of the signal. (In practice, this ratio need not be more than ~5:1, if higher-order
31+
estimators are used. At a minimum, however, this ratio must be greater than 2:1,
32+
corresponding to the Nyquist frequency.)
33+
34+
The algorithm used in this function is a highly-optimized version of the math described in
35+
this repository, part of an upcoming paper:
36+
https://github.com/peterdsharpe/aircraft-polar-reconstruction-from-flight-test
37+
38+
Parameters
39+
----------
40+
data : np.ndarray
41+
A 1D NumPy array of time-series data.
42+
estimator_order : int | None
43+
The order of the estimator to use. Higher orders are generally more accurate, up to
44+
the point where sample error starts to dominate. If None, a reasonable estimator order
45+
will be chosen automatically.
46+
47+
Returns
48+
-------
49+
float
50+
An estimate of the standard deviation of the data's noise component.
4451
"""
4552
if len(data) < 2:
4653
raise ValueError("Data must have at least 2 points.")
@@ -90,47 +97,61 @@ def bootstrap_fits(
9097
normalize: bool | None = None,
9198
) -> tuple[np.ndarray, np.ndarray] | list[Spline]:
9299
"""
93-
Bootstraps a time-series dataset and fits splines to each bootstrap resample.
94-
95-
Args:
96-
97-
x: The independent variable (e.g., time) of the dataset. A 1D NumPy array.
98-
99-
y: The dependent variable (e.g., altitude) of the dataset. A 1D NumPy array.
100-
101-
n_bootstraps: The number of bootstrap resamples to create.
102-
103-
fit_points: An optional variable that determines what to do with the splines after they are fit:
104-
105-
- If an integer, the splines will be evaluated at a linearly-spaced vector of points between the minimum
106-
and maximum x-values of the dataset, with the number of points equal to `fit_points`. This is the default.
107-
108-
- If an iterable of floats (e.g. a 1D NumPy array), the splines will be evaluated at those points.
109-
110-
- If None, the splines won't be evaluated, and instead the splines are returned directly.
111-
112-
spline_degree: The degree of the splines to fit.
113-
114-
normalize: Whether or not to normalize the data before fitting. If True, the data will be normalized to
115-
the range [0, 1] before fitting, and the splines will be un-normalized before being returned. If False,
116-
the data will not be normalized before fitting.
117-
118-
- If None (the default), the data will be normalized if and only if `fit_points` is not None.
119-
120-
121-
Returns: One of the following, depending on the value of `fit_points`:
122-
123-
- If `fit_points` is an integer or array, then this function returns a tuple of NumPy arrays:
100+
Bootstrap a time-series dataset and fit splines to each bootstrap resample.
101+
102+
Parameters
103+
----------
104+
x : np.ndarray
105+
The independent variable (e.g., time) of the dataset. A 1D NumPy array.
106+
y : np.ndarray
107+
The dependent variable (e.g., altitude) of the dataset. A 1D NumPy array.
108+
x_noise_stdev : None | float
109+
The standard deviation of the noise in `x`. If None, it is estimated from the data
110+
using `estimate_noise_standard_deviation()`.
111+
y_noise_stdev : None | float
112+
The standard deviation of the noise in `y`. If None, it is estimated from the data
113+
using `estimate_noise_standard_deviation()`.
114+
n_bootstraps : int
115+
The number of bootstrap resamples to create.
116+
fit_points : int | Iterable[float] | None
117+
An optional variable that determines what to do with the splines after they are fit:
118+
119+
- If an integer, the splines will be evaluated at a linearly-spaced vector of points
120+
between the minimum and maximum x-values of the dataset, with the number of points
121+
equal to `fit_points`. This is the default.
122+
123+
- If an iterable of floats (e.g. a 1D NumPy array), the splines will be evaluated at
124+
those points.
125+
126+
- If None, the splines won't be evaluated, and instead the splines are returned
127+
directly.
128+
spline_degree : int
129+
The degree of the splines to fit.
130+
normalize : bool | None
131+
Whether or not to normalize the data before fitting. If True, the data will be
132+
normalized to the range [0, 1] before fitting, and the splines will be un-normalized
133+
before being returned. If False, the data will not be normalized before fitting.
134+
135+
- If None (the default), the data will be normalized if and only if `fit_points` is
136+
not None.
137+
138+
Returns
139+
-------
140+
tuple[np.ndarray, np.ndarray] | list[Spline]
141+
One of the following, depending on the value of `fit_points`:
142+
143+
- If `fit_points` is an integer or array, then this function returns a tuple of NumPy
144+
arrays:
124145
125146
- `x_fit`: A 1D NumPy array with the x-values at which the splines were evaluated.
126147
127-
- `y_bootstrap_fits`: A 2D NumPy array of shape (n_bootstraps, len(x_fit)) with the y-values of the
128-
splines evaluated at each bootstrap resample and at each x-value.
129-
130-
- If `fit_points` is None, then this function returns a list of `n_bootstraps` splines, each of which is a
131-
`NaturalUnivariateSpline`, which is a subclass of `scipy.interpolate.UnivariateSpline` with more sensible
132-
extrapolation.
148+
- `y_bootstrap_fits`: A 2D NumPy array of shape (n_bootstraps, len(x_fit)) with
149+
the y-values of the splines evaluated at each bootstrap resample and at each
150+
x-value.
133151
152+
- If `fit_points` is None, then this function returns a list of `n_bootstraps`
153+
splines, each of which is a `NaturalUnivariateSpline`, which is a subclass of
154+
`scipy.interpolate.UnivariateSpline` with more sensible extrapolation.
134155
"""
135156
### Set defaults
136157
if normalize is None:

0 commit comments

Comments
 (0)