# Usage examples¶

As follows are usage example for all detrending methods offered by wotan. In all examples, the following synthetic data are used:

```
import numpy as np
from wotan import flatten
points = 1000
time = np.linspace(0, 30, points)
flux = 1 + ((np.sin(time) + time / 10 + time**1.5 / 100) / 1000)
noise = np.random.normal(0, 0.0001, points)
flux += noise
for i in range(points):
if i % 75 == 0:
flux[i:i+5] -= 0.0004 # Add some transits
flux[i+50:i+52] += 0.0002 # and flares
flux[300:400] = np.nan
```

## Robust estimators with tuning constant¶

Some robust estimators can be tuned: `biweight`

, `andrewsinewave`

, `welsch`

, `huber`

, `huber_psi`

, `hampel`

, `hampelfilt`

, `tau`

. The `hodges`

can not be tuned.

Example usage:

```
flatten_lc, trend_lc = flatten(
time, # Array of time values
flux, # Array of flux values
method='biweight',
window_length=0.5, # The length of the filter window in units of ``time``
edge_cutoff=0.5, # length (in units of time) to be cut off each edge.
break_tolerance=0.5, # Split into segments at breaks longer than that
return_trend=True, # Return trend and flattened light curve
cval=5.0 # Tuning parameter for the robust estimators
)
```

Which we can plot as follows:

```
import matplotlib.pyplot as plt
plt.scatter(time, flux, s=1, color='black')
plt.plot(time, trend_lc, color='red', linewidth=2)
plt.show()
plt.close()
plt.scatter(time, flatten_lc, s=1, color='black')
plt.show()
```

Note

Tuning constants `cval`

are defined as multiples in units of median absolute deviation from the central location. Defaults are usually chosen to achieve high efficiency for Gaussian distributions. For example, for the `biweight`

a `cval`

of 6 includes data up to 4 standard deviations (6 median absolute deviations) from the central location and has an efficiency of 98%. Another typical value for the `biweight`

is 4.685 with 95% efficiency. Larger values for make the estimate more efficient but less robust. The default for the `biweight`

in wotan is 5, as it has shown the best results in the transit injection retrieval experiment. The other defaults are from the literature.

`biweight`

5`andrewsinewave`

1.339`welsch`

2.11`huber`

1.5`huber_psi`

1.28`hampel`

(1.7, 3.4, 8.5)`hampelfilt`

3`ramsay`

0.3`tau`

: 4.5

The `hampel`

has a 3-part descending function, known also as (a,b,c). Its tuning constant `cval`

must be given as a tuple of 3 values. Typical values are (1.7, 3.4, 8.5) called “17A”; and (2.5, 4.5, 9.5) called “25A”. With values given as multiples of the median absolute deviation, the 25A can be stated equivalently: a’ = 1.686, b’ = 3.035 c’ = 6.408 as multiples of the standard deviation.

## Trimmed methods¶

There are 3 methods which first focus on outlier treatment, followed by taking the mean in a second stage: `trim_mean`

, `winsorize`

and `hampelfilt`

.

- The
`hampelfilt`

was already discussed in the previous section because its threshold is defined as`cval`

times the median absolute deviation, beyond which it replaces values with the median. - The
`trim_mean`

deletes the fraction`proportiontocut`

from both sides of the distribution. - The
`winsorize`

replaces the fraction`proportiontocut`

from both sides of the distribution with the remaining values at the edges.

Example usage:

```
flatten_lc, trend_lc = flatten(
time, # Array of time values
flux, # Array of flux values
method='trim_mean',
window_length=0.5, # The length of the filter window in units of ``time``
edge_cutoff=0.5, # length (in units of time) to be cut off each edge.
break_tolerance=0.5, # Split into segments at breaks longer than that
return_trend=True, # Return trend and flattened light curve
proportiontocut=0.1 # Cut 10% off both ends
)
```

## median, mean¶

These methods ignore the parameters `proportiontocut`

and `cval`

Example usage:

```
flatten_lc, trend_lc = flatten(
time, # Array of time values
flux, # Array of flux values
method='median',
window_length=0.5, # The length of the filter window in units of ``time``
edge_cutoff=0.5, # length (in units of time) to be cut off each edge.
break_tolerance=0.5, # Split into segments at breaks longer than that
return_trend=True, # Return trend and flattened light curve
)
```

## medfilt¶

This method is cadence-based. Included to compare to the time-windowed `median`

. The parameter `window_length`

is now in units of cadence (i.e., array data points). It ignores the parameters `edge_cutoff`

and `break_tolerance`

.

Example usage:

```
flatten_lc, trend_lc = flatten(
time, # Array of time values
flux, # Array of flux values
method='medfilt',
window_length=31 , # The length of the filter window in cadences
return_trend=True, # Return trend and flattened light curve
)
```

## Spline: robust rspline¶

Spline with iterative sigma-clipping. It does not provide `edge_cutoff`

, but benefits greatly from using a sensible `break_tolerance`

. Example usage:

```
flatten_lc, trend_lc = flatten(
time, # Array of time values
flux, # Array of flux values
method='rspline',
window_length=0.5, # The knot distance in units of ``time``
break_tolerance=0.5, # Split into segments at breaks longer than that
return_trend=True, # Return trend and flattened light curve
)
```

## Spline: robust hspline¶

Spline with robust Huber-estimator (linear and quadratic loss). It does not provide `edge_cutoff`

, but benefits greatly from using a sensible `break_tolerance`

. Example usage:

```
flatten_lc, trend_lc = flatten(
time, # Array of time values
flux, # Array of flux values
method='hspline',
window_length=0.5, # The knot distance in units of ``time``
break_tolerance=0.5, # Split into segments at breaks longer than that
return_trend=True, # Return trend and flattened light curve
)
```

## Spline: robust penalized pspline¶

Spline with iterative sigma-clipping. Auto-determination of `window_length`

. It does not provide `edge_cutoff`

, but benefits greatly from using a sensible `break_tolerance`

. Example usage:

```
flatten_lc, trend_lc = flatten(
time, # Array of time values
flux, # Array of flux values
method='pspline',
break_tolerance=0.5, # Split into segments at breaks longer than that
return_trend=True, # Return trend and flattened light curve
)
```

## Lowess / Loess¶

Locally weighted scatterplot smoothing (Cleveland 1979). Offers segmentation (`break_tolerance`

), but no edge clipping (`edge_cutoff`

). For similar results compared to other spline-based methods or sliders, use a `window_length`

about twice as long. Example usage:

```
flatten_lc, trend_lc = flatten(
time, # Array of time values
flux, # Array of flux values
method='lowess',
window_length=1, # The length of the filter window in units of ``time``
break_tolerance=0.5, # Split into segments at breaks longer than that
return_trend=True, # Return trend and flattened light curve
)
```

## CoFiAM¶

Cosine Filtering with Autocorrelation Minimization. Does not provide `edge_cutoff`

, but benefits greatly from using a sensible `break_tolerance`

. Example usage:

```
flatten_lc, trend_lc = flatten(
time, # Array of time values
flux, # Array of flux values
method='cofiam',
window_length=0.5, # Protected window span in units of ``time``
break_tolerance=0.5, # Split into segments at breaks longer than that
return_trend=True, # Return trend and flattened light curve
)
```

## Fitting of sines and cosines¶

Fits a sum of sines and cosines, where the highest order is determined by the protected window span `window_length`

in units of `time`

. A robustification (iterative sigma-clipping of 2-sigma outliers until convergence) is available by setting the parameter `robust=True`

. Example usage:

```
flatten_lc, trend_lc = flatten(
time, # Array of time values
flux, # Array of flux values
method='cosine',
robust='True', # iterative sigma-clipping of 2-sigma outliers until convergence
window_length=0.5, # Protected window span in units of ``time``
break_tolerance=0.5, # Split into segments at breaks longer than that
return_trend=True, # Return trend and flattened light curve
)
```

## SuperSmoother¶

Friedman’s (1984) Super-Smoother, a local linear regression with adaptive bandwidth. Does not provide `edge_cutoff`

, but benefits greatly from using a sensible `break_tolerance`

. Example usage:

```
flatten_lc, trend_lc = flatten(
time, # Array of time values
flux, # Array of flux values
method='supersmoother',
window_length=0.5, # The knot distance in units of ``time``
break_tolerance=0.5, # Split into segments at breaks longer than that
return_trend=True, # Return trend and flattened light curve
cval=None # Bass enhancement (smoothness)
)
```

Note

`cval`

determines the bass enhancement (smoothness) and can be None or in the range 0 < `cval`

< 10. Smaller values make the trend more flexible to fit out small variations.

## Savitzky-Golay savgol¶

Sliding segments are fit with polynomials (Savitzky & Golay 1964). This filter is cadence-based (not time-windowed), so that `window_length`

must be an integer value. If an even integer is provided, it is made uneven (a requirement) by adding 1. The polyorder is set by `cval`

(default: 2 - the best value from our experiments). Does not provide `edge_cutoff`

, but benefits from using a sensible `break_tolerance`

.

Example usage:

```
flatten_lc, trend_lc = flatten(
time, # Array of time values
flux, # Array of flux values
method='savgol',
cval=2, # Defines polyorder
window_length=51, # The window length in cadences
break_tolerance=0.5, # Split into segments at breaks longer than that
return_trend=True, # Return trend and flattened light curve
)
```

## Gaussian Processes¶

Available kernels are :

`squared_exp`

Squared-exponential kernel, with option for iterative sigma-clipping`matern`

Matern 3/2 kernel, with option for iterative sigma-clipping`periodic`

Periodic kernel informed by a user-specified period`periodic_auto`

Periodic kernel informed by a Lomb-Scargle periodogram pre-search

GPs do not provide `edge_cutoff`

, but benefit from using a sensible `break_tolerance`

.

Example usage:

```
flatten_lc, trend_lc = flatten(
time, # Array of time values
flux, # Array of flux values
method='gp',
kernel='squared_exp', # GP kernel choice
kernel_size=10, # GP kernel length
break_tolerance=0.5, # Split into segments at breaks longer than that
return_trend=True, # Return trend and flattened light curve
)
```

Note

The sensible `kernel_size`

varies between kernels.

A robustification (iterative sigma-clipping of 2-sigma outliers until convergence) is available by setting the parameter `robust=True`

:

```
flatten_lc, trend_lc = flatten(
time, # Array of time values
flux, # Array of flux values
method='gp',
kernel='squared_exp', # GP kernel choice
kernel_size=10, # GP kernel length
break_tolerance=0.5, # Split into segments at breaks longer than that
robust=True, # Robustification using iterative sigma clipping
return_trend=True, # Return trend and flattened light curve
)
```

Here we can simply swap `kernel='squared_exp'`

for `kernel='matern'`

and play with `kernel_size`

to get a very similar result.

In the presence of strong periodicity, we can also use the periodic kernel. This version does not support robustification. If we know the period, we can do this.

```
flatten_lc2, trend_lc2 = flatten(
time, # Array of time values
flux, # Array of flux values
method='gp',
kernel='periodic', # GP kernel choice
kernel_period=2*3.14, # GP kernel period
kernel_size=10, # GP kernel length
break_tolerance=0.5, # Split into segments at breaks longer than that
return_trend=True, # Return trend and flattened light curve
)
```

Usually, however, it is better to let wotan detect the period. We can do this by setting `kernel='periodic_auto'`

. Then, a Lomb-Scargle periodogram is calculated, and the strongest peak is used as the period. In addition, a Matern kernel is added to consume the remaining non-periodic variation. This version does not support robustification. Example:

```
flatten_lc2, trend_lc2 = flatten(
time, # Array of time values
flux, # Array of flux values
method='gp',
kernel='periodic_auto', # GP kernel choice
kernel_size=10, # GP kernel length
break_tolerance=0.5, # Split into segments at breaks longer than that
return_trend=True, # Return trend and flattened light curve
)
```