[ENH] Min-to-min and max-to-max phase shifting

[ryanhammonds]

This expands phase shifting to allow for minima-to-minima and maxima-to-maxima sims. It also add phase shifting to sim_bursty_oscillation, which wasn't possible before. The phase kwarg was added to sim_cycle so phase shifting could be done before tiling.

The motivation for this was working with sims + bycycle and the lack of a convenient way to sim cycles from trough-to-trough or peak-to-peak. When simulating from zerox-to-zerox, but bycycle defined cycles otherwise, cyclepoints could get messy. Maybe bycycle could be updated to define cycles from zerox-to-zerox, but that will likely have other side-effects to work out.

The phase argument still accepts a float from [0, 1], but it also accepts min or max strings to automatically determine the phase shift required to sim from trough-to-trough or peak-to-peak. I'm not sure a mixed param type is the best design so I'm open to suggestions.

Simple example:

import numpy as np

from neurodsp.sim.cycles import sim_cycle
from neurodsp.plts import plot_time_series

n_seconds = 5
fs = 1000

sig_max = sim_cycle(n_seconds, fs, 'asine', phase='max', rdsym=0.75)
sig_min = sim_cycle(n_seconds, fs, 'asine', phase='min', rdsym=0.75)

times = np.arange(0, len(sig_max)/fs, 1/fs)

plot_time_series(times, [sig_min, sig_max], labels=['min', 'max'])

Bycycle cyclepoints example:

import numpy as np

from neurodsp.sim import sim_combined
from neurodsp.plts import plot_time_series

from bycycle.features import compute_cyclepoints
from bycycle.plts import plot_cyclepoints_df


np.random.seed(0)

n_seconds = 5
fs = 1000

components = {'sim_bursty_oscillation': {'freq': 10, 'cycle': 'asine',
                                         'rdsym': 0.25, 'phase': 'min'},
              'sim_powerlaw':{'exponent': -2}}

sig = sim_combined(n_seconds, fs, components)

times = np.arange(0, len(sig)/fs, 1/fs)

df_samples = compute_cyclepoints(sig, fs, (1, 50))
plot_cyclepoints_df(df_samples, sig, fs)

[TomDonoghue]

This looks like a really nice extension, thanks @ryanhammonds!

I think all the extended functionality makes sense / looks good here! I don't love the mixed input type of the phase arg, but I can't really think of any other clear / obvious way to do it, so I reckon this should be fine. I've made some comments, mostly on documentation stuff, if you want to check through and push any updates (if you agree with them).

[TomDonoghue]

Thanks @ryanhammonds for the update! I direct pushed some small spelling / description tweaks.

This looks good to me - merging in!