In #8591, I moved the periodogram classes from astropy.stats to astropy.timeseries. In this PR, I want to make sure that users can seamlessly use the periodogram classes given a time series object.

This PR actually does two main things:

• It adapts the BLS and Lomb-Scargle algorithms so that they can optionally work with absolute rather than relative times. This means that parameters such as transit_time return absolute Time objects, and methods such as e.g. model can be given absolute times to evaluate the models on. I have fully preserved back-compatibility with just using relative times (with or without units). I have added an extensive test for both periodogram algorithms to make sure that they behave correctly when given absolute times.

• It then adds a periodogram method on the TimeSeries class, which is a convenience to initialize either BoxLeastSquares or LombScargle with the correct arguments. Then instead of doing:

from astropy.stats import BoxLeastSquares
keep = ~np.isnan(ts['sap_flux'])
periodogram = BoxLeastSquares(ts.time.jd[keep] * u.day, ts['sap_flux'][keep])
periodogram.autopower(0.2 * u.day)

users can just do:

periodogram = ts.periodogram(algorithm='bls', algorithm='sap_flux')
results = periodogram.autopower(0.2 * u.day)

I considered an alternative approach which would be to make it so that e.g. BoxLeastSquares can be initialized with a time series, but I decided not to implement this for the following reasons:

• It doesn't solve the issue that one has to still specify the column names to use for the flux, and there isn't much benefit to writing:

BoxLeastSquares(ts, y='flux', dy='flux_error')

compared with:

BoxLeastSquares(ts.time, y=ts['flux'], dy=ts['flux_error'])

• If we do this, we essentially are overloading the initializer in a way that it accepts very flexible input (strings or numbers, times, quantities, time series, etc.) and that's not ideal. We could instead have a class method but then that's more to type.

The advantage of just being able to do:

ts.periodogram(algorithm='bls', algorithm='sap_flux')

is that it avoids having to import the periodogram classes and initialize them manually, and provides a nice user-friendly API. This also transparently handles masking out e.g. NaN values before initializing the periodogram classes.

For the binned time series, I'm doing the same as for the sampled one, using the times at the center of the bins (this is mentioned in the docstring)

At the moment there is a little bit of code duplication between binned and sampled, and between BLS and Lomb-Scargle. My priority here is to make sure that things work as we want, and we can always find ways to reduce the duplication in future.

It might be worth writing a top-level docs page specifically about periodograms that then links to the two (or more in future) algorithms we have. Again, in the interest of getting this in to the feature freeze, I'm happy to try and improve the docs in the RC phase, since it would just be docs.

@dfm @mirca @joeldhartman @jakevdp - as the authors for the periodogram classes, I just wanted to give you a heads-up about the changes related to accepting absolute times.