feets.datasets package

Submodules

feets.datasets.base module

Base code for IO dataset retrieval.

class feets.datasets.base.LightCurve(time, magnitude=None, error=None, magnitude2=None, aligned_time=None, aligned_magnitude=None, aligned_magnitude2=None, aligned_error=None, aligned_error2=None, flux=None, flux_error=None)[source]

Bases: LightCurveBase, Mapping

Time series data representation.

This class holds the time series data for a single photometric band. This may include the time, magnitude, and associated errors.

Each of the available data vectors (time, magnitude, error) can be accessed as attributes of the class.

class feets.datasets.base.LightCurveDataset(id, name, description, bands, data, metadata=None)[source]

Bases: Mapping

An immutable container for a single light curve dataset.

This object encapsulates the time series data for one astronomical object, potentially across multiple photometric bands, along with its corresponding metadata. It behaves like a dictionary, allowing access to its main attributes (_id, name, description, etc.) via key-based lookup.

The actual time series data is stored in the data attribute as a feets.libs.bunch.Bunch of LightCurve objects, one for each band.

Attributes:
_idstr or None

A unique identifier for the light curve dataset object.

namestr

The human-readable name of the dataset from which this object originates.

descriptionstr

A detailed description of the dataset’s origin, content, or purpose.

bandstuple of str

An ordered collection of the band names for which time series data is available. These names correspond to the keys in the data attribute.

datadict-like

A dictionary-like object mapping band names (from bands) to their corresponding time series data. This is internally converted to a feets.libs.bunch.Bunch of LightCurve objects for convenient attribute-style access.

metadatadict-like or None

A dictionary-like object containing arbitrary metadata about the light curve object (e.g., celestial coordinates, redshift). It is internally converted to a feets.libs.bunch.Bunch for convenient attribute-style access.

See also

feets.libs.bunch.Bunch

Container object exposing keys as attributes.

LightCurve
bands: tuple
data: Bunch
description: str
metadata: Bunch | None
name: str
feets.datasets.base.clear_data_home(data_home=None)[source]

Delete all cached files from the feets data directory.

Parameters:
data_homestr, pathlib.Path or None, optional

The path to the feets data directory.

feets.datasets.base.fetch(url, dest, force=False)[source]

Retrieve data from url and store it into dest.

Parameters:
url: str

Link to the remote data

dest: str or pathlib.Path

Path where the file must be stored

force: bool, default=False

Overwrite if the file already exists

Returns:
cached: bool

True if the file already exists

dest: pathlib.Path

The path to the downloaded file

feets.datasets.base.get_data_home(data_home=None)[source]

Return the path of the feets data directory.

This directory is used by some large dataset loaders to avoid downloading the same data several times.

By default, this is a directory named ‘feets_data’ in the user’s home directory.

Alternatively, it can be programatically set with the data_home variable, or by the ‘feets_DATA’ environment variable. The ‘~’ prefix will be expanded to the user’s home directory.

If the directory does not already exist, it will be automatically created.

Parameters:
data_homestr, pathlib.Path or None, optional

The path to the feets data directory.

Returns:
pathlib.Path

The path to the feets data directory.

feets.datasets.macho module

Utilities for accessing MACHO light curves.

The files are gathered from the original FATS project tutorial: https://github.com/isadoranun/tsfeat

feets.datasets.macho.available_MACHO_lc()[source]

List the available MACHO light curves.

Returns:
list

The list of available MACHO light curves.

feets.datasets.macho.load_MACHO(macho_id)[source]

Retrieve a light curve from the MACHO survey.

The returned light curve contains data from 2 bands: R, B.

Parameters:
macho_idstr
The ID of the MACHO light curve to retrieve.
Returns:
LightCurveDataset

Dataset with the retrieved light curve data vectors.

See also

available_MACHO_lc

Notes

The files are gathered from the original FATS project tutorial: https://github.com/isadoranun/tsfeat

Examples

>>> ds = load_MACHO('lc_1.3444.614')
>>> ds
LightCurveDataset(
    _id='lc_1.3444.614', name='MACHO', bands=('R', 'B')
)
>>> ds.bands
('R', 'B')
>>> ds.data.B
<LightCurve time[1235], magnitude[1235], error[1235]>
>>> ds.data.B.magnitude
array([-6.081, -6.041, -6.046, ..., -6.009, -5.985, -5.997], shape=(1235,))
feets.datasets.macho.load_MACHO_example()[source]

Retrieve a light curve from the MACHO survey.

The returned light curve contains data from 2 bands: R, B.

Returns:
LightCurveDataset

Dataset with the retrieved light curve data vectors.

See also

available_MACHO_lc

Notes

The files are gathered from the original FATS project tutorial: https://github.com/isadoranun/tsfeat

Examples

>>> ds = load_MACHO_example()
>>> ds
LightCurveDataset(
    _id='lc_1.3444.614', name='MACHO', bands=('R', 'B')
)
>>> ds.bands
('R', 'B')
>>> ds.data.B
<LightCurve time[1235], magnitude[1235], error[1235]>
>>> ds.data.B.magnitude
array([-6.081, -6.041, -6.046, ..., -6.009, -5.985, -5.997], shape=(1235,))

feets.datasets.ogle3 module

Utilities for accessing the OGLE-III On-line Catalog of Variable Stars.

The main goal of this catalog is to record all variable sources located in the OGLE-III fields in the Magellanic Clouds and Galactic bulge. The data currently available include:

  • classical Cepheids in the Galactic Bulge, LMC and SMC,

  • type II Cepheids in the Galactic Bulge, LMC and SMC,

  • anomalous Cepheids in LMC and SMC,

  • RR Lyrae stars in the Galactic Bulge, LMC and SMC,

  • Long Period Variables in the Galactic Bulge, LMC and SMC,

  • Double Period Variables in LMC,

  • R CrB stars in LMC,

  • Delta Sct stars in LMC.

The catalog data include basic parameters of the stars (coordinates, periods, mean magnitudes, amplitudes, parameters of the Fourier light curve decompositions), VI multi-epoch photometry collected since 2001, and for some stars supplemented with the OGLE-II photometry obtained between 1997 and 2000, finding charts and cross-identifications with previously published catalogs.

Note to the user: If you use or refer to the data obtained from this catalog in your scientific work, please cite the appropriate papers:

  • Udalski, Szymanski, Soszynski and Poleski, 2008, Acta Astron., 58, 69 (OGLE-III photometry)

  • Soszynski et al., 2008a, Acta Astron., 58, 163 (Classical Cepheids in the LMC)

  • Soszynski et al., 2008b, Acta Astron., 58, 293 (Type II and Anomalous Cepheids in the LMC)

  • Soszynski et al., 2009a, Acta Astron., 59, 1 (RR Lyrae Stars in the LMC)

  • Soszynski et al., 2009b, Acta Astron., 59, 239 (Long Period Variables in the LMC)

  • Soszynski et al., 2009c, Acta Astron., 59, 335 (R CrB Variables in the LMC)

  • Poleski et al., 2010a, Acta Astron., 60, 1 (δ Scuti Variables in the LMC)

  • Poleski et al., 2010b, Acta Astron., 60, 179 (Double Period Variables in the LMC)

  • Soszynski et al., 2010a, Acta Astron., 60, 17 (Classical Cepheids in the SMC)

  • Soszynski et al., 2010b, Acta Astron., 60, 91 (Type II Cepheids in the SMC)

  • Soszynski et al., 2010c, Acta Astron., 60, 165 (RR Lyrae Stars in the SMC)

  • Soszynski et al., 2011a, Acta Astron., 61, 1 (RR Lyrae Stars in the Galactic Bulge)

  • Soszynski et al., 2011b, Acta Astron., 61, 217 (Long-Period Variables in the Small Magellanic Cloud)

  • Soszynski et al., 2011c, Acta Astron., 61, 285; 2013b, Acta Astron., 63, 37; (Classical and Type II Cepheids in the Galactic Bulge)

  • Soszynski et al., 2013a, Acta Astron., 63, 21 (Long-Period Variables in the Galactic Bulge)

More Info: http://ogledb.astrouw.edu.pl/~ogle/CVS/

feets.datasets.ogle3.fetch_OGLE3(ogle3_id, data_home=None, metadata=True, download_if_missing=True)[source]

Retrieve a light curve from the OGLE-3 catalog.

Parameters:
ogle3_idstr

The OGLE-III ID of the light curve as seen on the load_OGLE3_catalog dataframe.

data_homestr or pathlib.Path, optional

Cache directory for the downloaded datasets. See datasets.base.get_data_home for more info.

metadatabool, default=True

If True, the row from the load_OGLE3_catalog dataframe corresponding to the given light curve will be included in the resulting dataset as metadata.

download_if_missingbool, default=True

If True, try to download the data from the source site when it’s not locally available. If False, it will raise a FileNotFoundError instead.

Returns:
LightCurveDataset

Dataset with the retrieved light curve data vectors and metadata (if metadata is True)

Raises:
ValueError

If the provided OGLE-III ID is invalid.

FileNotFoundError

If the data is not locally available and download_if_missing is set to False.

See also

datasets.base.get_data_home

Return the path of the feets data directory.

load_OGLE3_catalog

Examples

>>> ds = fetch_OGLE3("OGLE-BLG-LPV-232377")
>>> ds
LightCurveDataset(
    _id='OGLE-BLG-LPV-232377', name='OGLE-III', bands=('I', 'V')
)
>>> ds.bands
('I', 'V')
>>> ds.data.I
<LightCurve time[100], magnitude[100], error[100]>
>>> ds.data.I.magnitude
array([13.816, 13.826, 13.818, 13.812, 13.8  , 13.827, 13.797, 13.82 ,
   13.804, 13.783, 13.823, 13.8  , 13.84 , 13.817, 13.802, 13.824,
   13.822, 13.81 , 13.844, 13.848, 13.813, 13.836, 13.83 , 13.83 ,
   13.837, 13.811, 13.814, 13.82 , 13.826, 13.822, 13.821, 13.817,
   13.813, 13.809, 13.817, 13.836, 13.804, 13.801, 13.813, 13.823,
   13.818, 13.831, 13.833, 13.814, 13.814, 13.812, 13.822, 13.814,
   13.818, 13.817, 13.8  , 13.804, 13.799, 13.809, 13.815, 13.846,
   13.796, 13.791, 13.804, 13.853, 13.839, 13.816, 13.825, 13.81 ,
   13.8  , 13.807, 13.819, 13.829, 13.844, 13.84 , 13.842, 13.818,
   13.801, 13.804, 13.814, 13.821, 13.821, 13.822, 13.82 , 13.803,
   13.813, 13.826, 13.855, 13.865, 13.854, 13.828, 13.809, 13.828,
   13.833, 13.829, 13.816, 13.82 , 13.827, 13.834, 13.811, 13.817,
   13.808, 13.834, 13.814, 13.829])
feets.datasets.ogle3.load_OGLE3_catalog()[source]

List the OGLE-III catalog of variable stars as a pandas.DataFrame.

Returns:
pandas.DataFrame

The full OGLE-III catalog of variable stars.

feets.datasets.synthetic module

Synthetic light curve dataset generators.

feets.datasets.synthetic.create_normal(mu=0.0, sigma=1.0, mu_err=0.0, sigma_err=1.0, seed=None, **kwargs)[source]

Generate a light curve dataset that follows a Gaussian distribution.

Both the magnitudes and the errors are drawn from Gaussian distributions.

Parameters:
mufloat, default=0.0

Mean of the Gaussian distribution for the magnitudes.

sigmafloat, default=1.0

Standard deviation of the Gaussian distribution for the magnitudes.

mu_errfloat, default=0.0

Mean of the Gaussian distribution for the magnitudes errors.

sigma_errfloat, default=1.0

Standard deviation of the Gaussian distribution for the magnitudes errors.

seedint or array_like, optional

Random seed used to initialize the pseudo-random number generator.

kwargsoptional

extra arguments for create_random().

Returns:
LightCurveDataset

Dataset with randomly generated light curve data vectors.

See also

create_random

Examples

>>> ds = create_normal(0, 1, 0, .0008, seed=42)
>>> ds
LightCurveDataset(_id=None, name='feets-synthetic', bands=('B', 'V'))
>>> ds.data.B
LightCurve(time[10000], magnitude[10000], error[10000])
>>> ds.data.B.time
array([  0.00000000e+00,   1.00010001e-04,   2.00020002e-04, ...,
            9.99799980e-01,   9.99899990e-01,   1.00000000e+00])
feets.datasets.synthetic.create_periodic(mu_err=0.0, sigma_err=1.0, seed=None, **kwargs)[source]

Generate a light curve dataset with periodic variability.

The magnitude values follow a sinusoidal pattern with added Gaussian noise, while the error values are drawn from a Gaussian distribution.

Parameters:
mu_errfloat, default=0.0

Mean of the Gaussian distribution for the magnitude errors.

sigma_errfloat, default=1.0

Standard deviation of the Gaussian distribution for the magnitude errors.

seedint or array_like, optional

Random seed used to initialize the pseudo-random number generator.

kwargsoptional

extra arguments for create_random().

Returns:
LightCurveDataset

Dataset with randomly generated light curve data vectors.

Examples

>>> ds = synthetic.create_periodic(bands=["Ks"])
>>> ds
LightCurveDataset(_id=None, name='feets-synthetic', bands=('Ks',))
>>> ds.data.Ks.magnitude
array([ 0.95428053,  0.73022685,  0.03005121, ..., -0.26305297,
        2.57880082,  1.03376863])
feets.datasets.synthetic.create_random(magf, magf_params, errf, errf_params, timef=<function linspace>, timef_params=None, size=10000, _id=None, name='feets-synthetic', description='Lightcurve created with random numbers', bands=('B', 'V'), metadata=None)[source]

Generate a light curve dataset with any given random generator.

Parameters:
magfcallable

Function to generate the magnitudes.

magf_paramsdict-like

Parameters to feed the magf function.

errfcallable

Function to generate the magnitudes.

errf_paramsdict-like

Parameters to feed the errf function.

timefcallable, default=numpy.linspace

Function to generate the times.

timef_paramsdict-like or None, (default={“start”: 0., “stop”: 1.})

Parameters to feed the timef callable.

sizeint, default=10000

Number of observations to generate for each light curve.

_idobject, optional

Id for the generated dataset.

namestr, default=”feets-synthetic”

Name for the generated dataset.

descriptionstr, default=”Lightcurve created with random numbers”

Description for the generated dataset.

bandstuple of strings, default=(“B”, “V”)

The bands to generate.

metadatadict-like, optional

The metadata for the generated dataset

Returns:
LightCurveDataset

Dataset with randomly generated light curve data vectors.

Examples

>>> from numpy import random
>>>  create_random(
...     magf=random.normal, magf_params={"loc": 0, "scale": 1},
...     errf=random.normal, errf_params={"loc": 0, "scale": 0.008})
LightCurveDataset(_id=None, name='feets-synthetic', bands=('B', 'V'))
feets.datasets.synthetic.create_uniform(low=0.0, high=1.0, mu_err=0.0, sigma_err=1.0, seed=None, **kwargs)[source]

Generate a light curve dataset that follows a uniform distribution.

The magnitude values follow a uniform distribution, meanwhile the error values are drawn from a Gaussian distribution.

Parameters:
lowfloat, default=0.0

Lower boundary of the magnitude interval. All values generated will be greater than or equal to low.

highfloat, default=1.0

Upper boundary of the magnitude interval. All values generated will be less than high.

mu_errfloat, default=0.0

Mean of the Gaussian distribution for the magnitude errors.

sigma_errfloat, default=1.0

Standard deviation of the Gaussian distribution for the magnitude errors.

seedint or array_like, optional

Random seed used to initialize the pseudo-random number generator.

kwargsoptional

extra arguments for create_random().

Returns:
LightCurveDataset

Dataset with randomly generated light curve data vectors.

See also

create_random

Examples

>>> ds = synthetic.create_uniform(1, 2, 0, .0008, 42)
>>> ds
LightCurveDataset(_id=None, name='feets-synthetic', bands=('B', 'V'))
>>> ds.data.B.magnitude
array([ 1.37454012,  1.95071431,  1.73199394, ...,  1.94670792,
        1.39748799,  1.2171404 ])

Module contents

Utilities to load, fetch or generate datasets for some example light curves.

class feets.datasets.LightCurve(time, magnitude=None, error=None, magnitude2=None, aligned_time=None, aligned_magnitude=None, aligned_magnitude2=None, aligned_error=None, aligned_error2=None, flux=None, flux_error=None)[source]

Bases: LightCurveBase, Mapping

Time series data representation.

This class holds the time series data for a single photometric band. This may include the time, magnitude, and associated errors.

Each of the available data vectors (time, magnitude, error) can be accessed as attributes of the class.

class feets.datasets.LightCurveDataset(id, name, description, bands, data, metadata=None)[source]

Bases: Mapping

An immutable container for a single light curve dataset.

This object encapsulates the time series data for one astronomical object, potentially across multiple photometric bands, along with its corresponding metadata. It behaves like a dictionary, allowing access to its main attributes (_id, name, description, etc.) via key-based lookup.

The actual time series data is stored in the data attribute as a feets.libs.bunch.Bunch of LightCurve objects, one for each band.

Attributes:
_idstr or None

A unique identifier for the light curve dataset object.

namestr

The human-readable name of the dataset from which this object originates.

descriptionstr

A detailed description of the dataset’s origin, content, or purpose.

bandstuple of str

An ordered collection of the band names for which time series data is available. These names correspond to the keys in the data attribute.

datadict-like

A dictionary-like object mapping band names (from bands) to their corresponding time series data. This is internally converted to a feets.libs.bunch.Bunch of LightCurve objects for convenient attribute-style access.

metadatadict-like or None

A dictionary-like object containing arbitrary metadata about the light curve object (e.g., celestial coordinates, redshift). It is internally converted to a feets.libs.bunch.Bunch for convenient attribute-style access.

See also

feets.libs.bunch.Bunch

Container object exposing keys as attributes.

LightCurve
bands: tuple
data: Bunch
description: str
metadata: Bunch | None
name: str
feets.datasets.available_MACHO_lc()[source]

List the available MACHO light curves.

Returns:
list

The list of available MACHO light curves.

feets.datasets.fetch_OGLE3(ogle3_id, data_home=None, metadata=True, download_if_missing=True)[source]

Retrieve a light curve from the OGLE-3 catalog.

Parameters:
ogle3_idstr

The OGLE-III ID of the light curve as seen on the load_OGLE3_catalog dataframe.

data_homestr or pathlib.Path, optional

Cache directory for the downloaded datasets. See datasets.base.get_data_home for more info.

metadatabool, default=True

If True, the row from the load_OGLE3_catalog dataframe corresponding to the given light curve will be included in the resulting dataset as metadata.

download_if_missingbool, default=True

If True, try to download the data from the source site when it’s not locally available. If False, it will raise a FileNotFoundError instead.

Returns:
LightCurveDataset

Dataset with the retrieved light curve data vectors and metadata (if metadata is True)

Raises:
ValueError

If the provided OGLE-III ID is invalid.

FileNotFoundError

If the data is not locally available and download_if_missing is set to False.

See also

datasets.base.get_data_home

Return the path of the feets data directory.

load_OGLE3_catalog

Examples

>>> ds = fetch_OGLE3("OGLE-BLG-LPV-232377")
>>> ds
LightCurveDataset(
    _id='OGLE-BLG-LPV-232377', name='OGLE-III', bands=('I', 'V')
)
>>> ds.bands
('I', 'V')
>>> ds.data.I
<LightCurve time[100], magnitude[100], error[100]>
>>> ds.data.I.magnitude
array([13.816, 13.826, 13.818, 13.812, 13.8  , 13.827, 13.797, 13.82 ,
   13.804, 13.783, 13.823, 13.8  , 13.84 , 13.817, 13.802, 13.824,
   13.822, 13.81 , 13.844, 13.848, 13.813, 13.836, 13.83 , 13.83 ,
   13.837, 13.811, 13.814, 13.82 , 13.826, 13.822, 13.821, 13.817,
   13.813, 13.809, 13.817, 13.836, 13.804, 13.801, 13.813, 13.823,
   13.818, 13.831, 13.833, 13.814, 13.814, 13.812, 13.822, 13.814,
   13.818, 13.817, 13.8  , 13.804, 13.799, 13.809, 13.815, 13.846,
   13.796, 13.791, 13.804, 13.853, 13.839, 13.816, 13.825, 13.81 ,
   13.8  , 13.807, 13.819, 13.829, 13.844, 13.84 , 13.842, 13.818,
   13.801, 13.804, 13.814, 13.821, 13.821, 13.822, 13.82 , 13.803,
   13.813, 13.826, 13.855, 13.865, 13.854, 13.828, 13.809, 13.828,
   13.833, 13.829, 13.816, 13.82 , 13.827, 13.834, 13.811, 13.817,
   13.808, 13.834, 13.814, 13.829])
feets.datasets.load_MACHO(macho_id)[source]

Retrieve a light curve from the MACHO survey.

The returned light curve contains data from 2 bands: R, B.

Parameters:
macho_idstr
The ID of the MACHO light curve to retrieve.
Returns:
LightCurveDataset

Dataset with the retrieved light curve data vectors.

See also

available_MACHO_lc

Notes

The files are gathered from the original FATS project tutorial: https://github.com/isadoranun/tsfeat

Examples

>>> ds = load_MACHO('lc_1.3444.614')
>>> ds
LightCurveDataset(
    _id='lc_1.3444.614', name='MACHO', bands=('R', 'B')
)
>>> ds.bands
('R', 'B')
>>> ds.data.B
<LightCurve time[1235], magnitude[1235], error[1235]>
>>> ds.data.B.magnitude
array([-6.081, -6.041, -6.046, ..., -6.009, -5.985, -5.997], shape=(1235,))
feets.datasets.load_MACHO_example()[source]

Retrieve a light curve from the MACHO survey.

The returned light curve contains data from 2 bands: R, B.

Returns:
LightCurveDataset

Dataset with the retrieved light curve data vectors.

See also

available_MACHO_lc

Notes

The files are gathered from the original FATS project tutorial: https://github.com/isadoranun/tsfeat

Examples

>>> ds = load_MACHO_example()
>>> ds
LightCurveDataset(
    _id='lc_1.3444.614', name='MACHO', bands=('R', 'B')
)
>>> ds.bands
('R', 'B')
>>> ds.data.B
<LightCurve time[1235], magnitude[1235], error[1235]>
>>> ds.data.B.magnitude
array([-6.081, -6.041, -6.046, ..., -6.009, -5.985, -5.997], shape=(1235,))
feets.datasets.load_OGLE3_catalog()[source]

List the OGLE-III catalog of variable stars as a pandas.DataFrame.

Returns:
pandas.DataFrame

The full OGLE-III catalog of variable stars.