tessl/pypi-astropy
Astronomy and astrophysics core library providing comprehensive tools for astronomical computations and data handling
—
Pending
Quality
Pending
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
timeseries.mddocs/
Time Series
Time series data structures and analysis tools for astronomical time-domain observations.
Core Imports
from astropy.timeseries import TimeSeries, BinnedTimeSeries
from astropy.timeseries import LombScargle
from astropy.timeseries import aggregate_downsampleCapabilities
Time Series Data Structures
Classes for representing time series data with time-aware operations and astronomical data integration.
class TimeSeries:
"""
Base class for time series data.
Parameters:
- time: Time column (astropy.time.Time)
- data: Additional columns (dict, Table, or None)
- **kwargs: Additional column data
"""
def __init__(self, time=None, data=None, **kwargs): ...
def fold(self, period, epoch_time=None, epoch_phase=0, wrap_phase=None, normalize_phase=False):
"""
Fold time series by a given period.
Parameters:
- period: folding period (Quantity with time units)
- epoch_time: reference time for folding
- epoch_phase: phase at reference time
- wrap_phase: phase range for wrapping
- normalize_phase: whether to normalize phase to [0,1]
Returns:
TimeSeries: folded time series
"""
def bin_time(self, time_bin_size=None, time_bin_start=None, time_bin_end=None):
"""
Bin time series data.
Parameters:
- time_bin_size: size of time bins
- time_bin_start: start times for bins
- time_bin_end: end times for bins
Returns:
BinnedTimeSeries: binned time series
"""
@classmethod
def read(cls, filename, format=None, **kwargs):
"""Read time series from file."""
def write(self, filename, format=None, **kwargs):
"""Write time series to file."""
@property
def time(self):
"""Time column."""
class BinnedTimeSeries(TimeSeries):
"""
Time series with binned data.
Parameters:
- time_bin_start: start times for bins
- time_bin_end: end times for bins (optional if time_bin_size given)
- time_bin_size: size of time bins (optional)
- data: additional column data
"""
def __init__(self, time_bin_start=None, time_bin_end=None, time_bin_size=None, data=None, **kwargs): ...
@property
def time_bin_start(self):
"""Start times of bins."""
@property
def time_bin_end(self):
"""End times of bins."""
@property
def time_bin_center(self):
"""Center times of bins."""
@property
def time_bin_size(self):
"""Sizes of time bins."""Periodogram Analysis
Tools for period detection and frequency analysis in time series data.
class LombScargle:
"""
Lomb-Scargle periodogram for unevenly sampled data.
Parameters:
- t: observation times
- y: observed values
- dy: uncertainties in y (optional)
- fit_mean: whether to fit mean offset
- center_data: whether to center data around mean
- nterms: number of Fourier terms for multi-term periodogram
"""
def __init__(self, t, y, dy=None, fit_mean=True, center_data=True, nterms=1): ...
def power(self, frequency, normalization='standard', method='auto', method_kwds=None):
"""
Compute Lomb-Scargle power at given frequencies.
Parameters:
- frequency: frequencies to compute power
- normalization: normalization method ('standard', 'model', 'log', 'psd')
- method: computational method ('auto', 'slow', 'fast', 'scipy', 'chi2')
- method_kwds: additional method arguments
Returns:
array: power at each frequency
"""
def autopower(self, samples_per_peak=5, nyquist_factor=5, minimum_frequency=None, maximum_frequency=None, **kwargs):
"""
Compute power at automatically chosen frequencies.
Parameters:
- samples_per_peak: frequency sampling per peak width
- nyquist_factor: multiple of average Nyquist frequency for max frequency
- minimum_frequency: minimum frequency to consider
- maximum_frequency: maximum frequency to consider
- **kwargs: additional arguments for power()
Returns:
tuple: (frequency, power) arrays
"""
def false_alarm_probability(self, power, method='baluev'):
"""
Compute false alarm probability for given power.
Parameters:
- power: power values
- method: method for computation ('baluev', 'bootstrap')
Returns:
array: false alarm probabilities
"""
def false_alarm_level(self, false_alarm_probability, method='baluev'):
"""
Compute power level for given false alarm probability.
Parameters:
- false_alarm_probability: target false alarm probability
- method: method for computation
Returns:
float: power level
"""
def model(self, t, frequency):
"""
Compute best-fit model at given frequency.
Parameters:
- t: times for model evaluation
- frequency: frequency for model
Returns:
array: model values
"""
def design_matrix(self, frequency, t=None):
"""
Compute design matrix for given frequency.
Parameters:
- frequency: frequency value
- t: times (default uses fitted times)
Returns:
array: design matrix
"""Downsampling and Aggregation
Functions for reducing time resolution and aggregating time series data.
def aggregate_downsample(time_series, *, time_bin_size=None, time_bin_start=None, n_bins=None, aggregate_func=None):
"""
Downsample time series by aggregating into time bins.
Parameters:
- time_series: input TimeSeries
- time_bin_size: size of time bins
- time_bin_start: start time for first bin
- n_bins: number of bins to create
- aggregate_func: function to aggregate data in each bin
Returns:
BinnedTimeSeries: downsampled time series
"""
def boxcar_downsample(time_series, *, time_bin_size=None, time_bin_start=None, n_bins=None):
"""
Downsample using boxcar (moving average) method.
Parameters:
- time_series: input TimeSeries
- time_bin_size: size of time bins
- time_bin_start: start time for first bin
- n_bins: number of bins
Returns:
BinnedTimeSeries: downsampled time series
"""I/O Operations
Specialized I/O functions for common astronomical time series formats.
def kepler_fits_reader(filename):
"""
Reader for Kepler FITS time series files.
Parameters:
- filename: path to Kepler FITS file
Returns:
TimeSeries: loaded time series
"""
def tess_fits_reader(filename):
"""
Reader for TESS FITS time series files.
Parameters:
- filename: path to TESS FITS file
Returns:
TimeSeries: loaded time series
"""Usage Examples
Basic Time Series Operations
import numpy as np
from astropy.time import Time
from astropy.timeseries import TimeSeries
import astropy.units as u
# Create time array
times = Time('2023-01-01') + np.arange(100) * u.day
# Create time series with mock data
flux = 1 + 0.1 * np.sin(2 * np.pi * np.arange(100) / 10) + 0.05 * np.random.random(100)
ts = TimeSeries(time=times, flux=flux)
print(f"Time series length: {len(ts)}")
print(f"Time range: {ts.time[0]} to {ts.time[-1]}")Period Detection with Lomb-Scargle
from astropy.timeseries import LombScargle
# Simulate periodic signal with noise
t = np.linspace(0, 100, 1000)
y = np.sin(2 * np.pi * t / 10) + 0.1 * np.random.normal(size=1000)
# Create Lomb-Scargle periodogram
ls = LombScargle(t, y)
# Find power at automatically determined frequencies
frequency, power = ls.autopower()
# Find frequency with maximum power
best_freq = frequency[np.argmax(power)]
best_period = 1 / best_freq
print(f"Detected period: {best_period:.2f}")
# Compute false alarm probability
fap = ls.false_alarm_probability(power.max())
print(f"False alarm probability: {fap:.2e}")Folding Time Series
# Fold time series by detected period
period = 10.0 * u.day
folded_ts = ts.fold(period=period)
print(f"Folded time series length: {len(folded_ts)}")
print(f"Phase range: {folded_ts['time'].min()} to {folded_ts['time'].max()}")Binning Time Series
# Bin time series into daily bins
binned_ts = ts.bin_time(time_bin_size=1*u.day)
print(f"Original length: {len(ts)}")
print(f"Binned length: {len(binned_ts)}")Downsampling
from astropy.timeseries import aggregate_downsample
# Downsample using mean aggregation
downsampled = aggregate_downsample(ts, time_bin_size=5*u.day,
aggregate_func=np.mean)
print(f"Downsampled to {len(downsampled)} points")Types
# Time series types
TimeSeries = astropy.timeseries.TimeSeries
BinnedTimeSeries = astropy.timeseries.BinnedTimeSeries
# Periodogram types
LombScargle = astropy.timeseries.LombScargle