# User requirements for a timeseries data container in `sunpy`

| Requirement | Notes |
| ----------- | ----- |
| Store data that is a function of time | This means the time column should be treated as the index or coordinates to the data, and be stored as a time-like type. |
| Handle different time scales | Data can have times defined in a variety of different time scales (e.g. UTC, TAI) |
| Store multi-dimensional data | Although time is a common index to timeseries data, it isn't always the only one. As an exapmle, velocity distribution functions measured in the solar wind are 4D datasets, with data as a function of time and three dimensions in velocity space. |
| Handle time scales with leapseconds | Some timescales can contain timestamps that occur within a leapsecond. |
| Store and use physical units with the data and any non-time indices | |
| Store data in a format that can be used with scientific Python libraries | |
| Support for storing out-of memory datasets | |
| Store metadata alongside actual data | |
| Have a way to store an observer coordinate alongside the time index | |
| Have an easy way to do common data manipulation tasks | e.g. interpolating, resampling, rebinning |
| Have a way to combine multiple timeseries objects, and keep track of metadata | |
| Ability to convert to other common time series objects (e.g. `pandas.DataFrame`) | |
| Functionality for loading and saving out to common file formats | |

# What do PyHC projects use for their timeseries data?

| Package | Container |
| ------- | --------- |
| `sunpy` | Custom `TimeSeries` object, backed by `pandas.DataFrame` |
| HAPI Client | `numpy.ndarray` |
| `pySPEDAS` | Not sure, can users actually get at the data itself? |
| `spacepy` | Unclear if there is any specific timeseries container object? |
| `aidapy` | `xarray.DataArray`|
| `cdflib` | `numpy.ndarray`, support to convert to `xarray.DataArray` or `astropy` `TimeSeries` |
| `NDCube` | `NDCube` |
| `pytplot` | `xarray.DataArray` |
| `solo-epd-loader` | `pandas.DataFrame` |
| `speasy` | Custom `DataContainer` object, backed by `numpy.ndarray` |

# Options for a timeseries data container

- `astropy.timeseries.TimeSeries`
- `pandas.DataFrame`
- `xarray.DataArray` (or `xarray.DataSet`)
- `numpy.ndarray`
- `ndcube`