Prototype: Adding support for reading CBV files

Over in #672, work is well underway to add a CBVCorrector which would use Kepler/TESS Cotrending Basis Vector data to remove systematics from light curves.

A recent change in Lightkurve v2.x is the use of the astropy.timeseries.TimeSeries class as a container to hold light curve data. For consistency, it would be good to also use TimeSeries objects to store Cotrending Basis Vectors.

I am opening this issue to share a rough prototype of what this implementation could look like.

Prototype

from astropy.io import fits
from astropy.time import Time
from astropy.table import Table
from astropy.timeseries import TimeSeries

from lightkurve.correctors import DesignMatrix


class CotrendingBasisVectors(TimeSeries):
    """Container class for Kepler/TESS Cotrending Basis Vectors (CBVs).
    
    This is a special case of `TimeSeries` in which columns named `VECTOR_X`
    are used to denote cotrending basis vectors.  X is a positive integer
    starting from 1, consistent with the official Kepler/TESS data products.
    """
    def to_designmatrix(self, vectors=None, name="cbv"):
        """Returns a `DesignMatrix` containing the CBVs."""
        if vectors is None:
            vectors = list(range(1, cbv.meta['TFIELDS']-2))
        return DesignMatrix(self[[f"VECTOR_{idx}" for idx in vectors]].as_array(),
                            name=name)
        
    def plot(self):
        """TODO: A nice plotting function for CBVS."""
        pass
        

def read_cbv_file(filename, ext="CBV.single-scale.1.1"):
    """FITS file reader for official `CotrendingBasisVectors` files."""
    hdulist = fits.open(filename)

    # Read the columns and meta data
    tbl = Table.read(hdulist[ext], format="fits")
    tbl.meta.update(hdulist[0].header)
    tbl.meta.update(hdulist[ext].header)

    # TimeSeries-based objects require a dedicated time column
    t = Time(tbl['TIME'].data, format='btjd')
    tbl.remove_column('TIME')
    return CotrendingBasisVectors(time=t, data=tbl)

Example use:

# Reading a CBV file
url = "https://archive.stsci.edu/missions/tess/ffi/s0017/2019/279/1-1/tess2019279210107-s0017-1-1-0161-s_cbv.fits"
cbv = read_cbv_file(url)

# Accessing meta data
print(cbv.meta['TELESCOP'])
print(cbv.meta['CAMERA'])

# Accessing a single vector
cbv['VECTOR_1'].data

# Convert the CBVs into a `DesignMatrix` object
dm = cbv.to_designmatrix()

[barentsen]

Yep, you can now do download(flux_column='sap_flux') to make this easier!

[barentsen]

Closing this issue as it has been superseded by #826!