Modules

Documentation for the lcdc package and its submodules.

DatasetBuilder

DatasetBuilder is the main entrypoint class that holds the data and provides methods for data preprocessing and dataset creation.

`DatasetBuilder`

DatasetBuilder.__init__(directory: str, classes: List[str]=[], regexes: List[str]=[], norad_ids: List[int]=None)

Parameters

directory (str): The data directory.

classes (List[str], optional): A list of class names (default is an empty list).

regexes (List[str], optional): A list of regex patterns corresponding to the classes (default is an empty list).

norad_ids (List[int], optional): A list of NORAD IDs to filter the data (default is None).

`DatasetBuilder.preprocess`

DatasetBuilder.preprocess(ops: List[callable]=[])

Applies preprocessing operations to the dataset.

Parameters

ops (List[callable], optional): List of preprocessing operations to apply (default is an empty list).

`DatasetBuilder.build_dataset`

DatasetBuilder.build_dataset(split_ratio: float=None) -> Union[Dataset, List[Dataset]]

Builds the dataset, optionally splitting it into training and testing sets.

Parameters

split_ratio (float, optional): The ratio for splitting the dataset (default is None).

Returns

datasets (Union[Dataset, List[Dataset]]): The built dataset or a pair of train and test datasets if split_ratio is provided.

`DatasetBuilder.to_file`

DatasetBuilder.to_file(path: str)

Saves the dataset to a Parquet file.

Parameters

path (str): The path to save the Parquet file.

`DatasetBuilder.from_file`

DatasetBuilder.from_file(path: str) -> DatasetBuilder

Loads a DatasetBuilder from a .parquet file.

Parameters

path (str): The path to the Parquet file.

Returns

instance (DatasetBuilder): The DatasetBuilder with the loaded dataset.

`stats`

stats is a module that provides functions for computing statistics on the light curves. The computed statistics are stored in the records as a new field.

`Amplitude`

Amplitude()

Computes the amplitude as difference between maximal and minimal value of standartized magnitude. Returns results are stored in record's "Amplitude" field.

`MediumTime`

MediumTime()

Computes the medium time of a given record. Returns results are stored in record's "MediumTime" field.

`MediumPhase`

MediumPhase()

Computes the medium phase angle of a given record. Returns results are stored in record's "MediumPhase" field.

`FourierSeries`

FourierSeries(order: int, fs: bool=True, covariance: bool=True, amplitude: bool=True)

Parameters

order (int): The order of the Fourier series.

fs (bool, optional): Whether to compute and store Fourier coefficients (default is True).

covariance (bool, optional): Whether to compute and store Fourier covariance (default is True).

amplitude (bool, optional): Whether to compute and store Fourier amplitude (default is True).

Returns results are stored in record's "FourierCoefs" "FourierAmplitude" and "FourierCovariance" fields. The "FourierCovariance" matrix is stored in flatten version as 1D array of size [order+1 x order+1].

`ContinousWaveletTransform`

ContinousWaveletTransform(wavelet: str, length: int, scales: int)

Computes the Continuous Wavelet Transform (CWT) of a given record using the PyWavelet package.

Parameters

wavelet (str): The type of wavelet to use for the CWT.

length (int): The length of the signal to transform.

scales (int): The number of scales to use for the CWT.

Returns flatten results of size [length x scales] stored in record's "CWT" field.

`preprocessing`

`CustomProcessor`

CustomProcessor(fun: callable)

CustomProcessor class is a wrapper for custom functions that are not part of the predefined preprocessing steps. Ensure the correct output format of the function.

Parameters

fun (function): The custom function to be applied to the record.

Filters

Filters filter the records based on the criteria implemented in its condition(record) method.

`FilterFolded`

FilterFolded(k:int=100, threshold:float=0.5)

Filters records if its folded light curve has a certain threshold of non-zero values.

Parameters

k (int, optional): The size of the folded light curve (default is 100).

threshold (float, optional): The minimal ratio of non-zero measurements in the folded light curve (default is 0.5).

`FilterMinLength`

FilterMinLength(length: int, step: float = None)

Filters records if the light curve length is at least length.

Parameters

length (int): Minimal length of the light curve.

step (float, optional): Time step used for length computation is None the number of measurements is used as the length (default is None).

`FilterByPeriodicity`

FilterByPeriodicity(types: List[Variability])

Filters records based on the variability type.

Parameters

types (List[Variability]): List of lcdc.vars.Variability types to filter.

`FilterByStartDate`

FilterByStartDate(year, month, day, hour=0, minute=0, second=0)

Filters out records created before the specified start date.

Parameters

year (int): The year of the start date.

month (int): The month of the start date.

day (int): The day of the start date.

hour (int, optional): The hour of the start date (default is 0).

minute (int, optional): The minute of the start date (default is 0).

second (int|float, optional): The second of the start date (default is 0).

`FilterByEndDate`

FilterByEndDate(year, month, day, hour=0, minute=0, second=0)

Filters out records created after the specified end date.

Parameters

year (int): The year of the end date.

month (int): The month of the end date.

day (int): The day of the end date.

hour (int, optional): The hour of the end date (default is 0).

minute (int, optional): The minute of the end date (default is 0).

second (int|float, optional): The second of the end date (default is 0).

`FilterByNorad`

FilterByNorad(norad_list: List[int])

Filters records based on the NORAD ID.

Parameters

norad_list (List[int]): List of allowed NORAD IDs.

`CustomFilter`

CustomFilter(fun: callable)

CustomFilter class is a wrapper for custom functions that are not part of the predefined collection.

Parameters

fun (function): The custom function to be applied to the record.

Splitting

Splitting operations are used to split one light curve into multiple records based on some methodology.

`SplitByGaps`

SplitByGaps(max_length: int=None)

SplitByGaps splits the light curve into parts if the time difference between two consecutive measurements is greater than the apparent rotational period.

For non-periodic light curves, the split wont be performed.

Parameters

max_length (int, optional): The maximum length of a part in seconds. Defaults to None. If its defined, multiple parts can be merged togethe if their sum of lengths is less than max_length.

`SplitByRotationalPeriod`

SplitByRotationalPeriod(multiple: float)

SplitByRotationalPeriod splits the light curve by the rotational period. For non-periodic light curves, the split wont be performed.

Parameters

multiple (int, optional): The light curve is split by the multitiple of period.

`SplitBySize`

SplitBySize(max_length: float, uniform: bool=False)

SplitBySize splits the light curve into parts of a fixed size.

Parameters

max_length (int): The maximum length of a part in seconds. uniform (bool, optional): If True, the parts will have the same length <= max_length. Defaults to False.

Transformations

Transformations modify the original samples in some way.

`Fold`

Fold()

Fold class is a transformation folds the light curve by its apparent rotational period. Does not apply for non-variable or aperiodic light curves.

Influenced fields: time, mag, phase, distance, filter

`ToGrid`

ToGrid(sampling_frequency: float, size: int) ToGrid class is a transformation that resamples the light curve by sampling_frequency. The result is padded / truncated to a fixed size.

Influenced fields: time, mag, phase, distance, filter

Parameters

sampling_frequency (float): The resampling frequency [Hz].

size (int): The fixed size of the resampled light curve.

`DropColumns`

DropColumns(columns: List[str])

DropColumns removes field specified in the columns parameter.

Parameters

columns (List[str]): List of columns to drop.

`ToApparentMagnitude`

ToApparentMagnitude(inplace: bool)

ToApparentMagnitude class converts standardized magnitude (to distance 1000km and 90 deg phase angle) into apparent magnitude.

Parameters

inplace (bool): If True, the original magnitude field is replaced with the corrected one. Otherwise, the corrected magnitude is stored in a new field 'apparent_mag'.

Source: McCue GA, Williams JG, Morford JM. Optical characteristics of artificial satellites. Planetary and Space Science. 1971;19(8):851-68. Available from: https://www.sciencedirect.com/science/article/pii/0032063371901371.

`vars`

Contains convenience Enum classes and other constants.

`Variability`

Variability is a String Enum class for the variability types.

Name Value

PERIODIC 'periodic'

APERIODIC 'aperiodic'

NONVARIABLE 'non-variable'

`TableCols`

TableCols is a String Enum class for the table basic table columns.

Name Value Description

ID 'id' track id

NORAD_ID 'norad_id' object norad id

TIMESTAMP 'timestamp' timestamp of the measurement

PERIOD 'period' apparent rotational period

TIME 'time' list of time measurements

MAG 'mag' list of standartized magnitude measurements

PHASE 'phase' list of phase angle measurements

DISTANCE 'distance' list of distance measurements

FILTER 'filter' list of filter measurements

VARIABILITY 'variability' object variability type

NAME 'name' object name

LABEL 'label' class label

RANGE 'range' index range of original measurements

`Filter`

Filter is a Int Enum class for the filter types.

Name Value

UNKNOWN 0

CLEAR 1

POL 2

V 4

R 8

B 16

`DATA_COLS`

DATA_COLS is a list of list columns namely: "time", "mag", "phase", "distance", "filter".

`utils`

Module utils contains utility and vizualization functions.

`plot_track`

plot_track(record: Dict[str, Any]) -> [matplotlib.figure.Figure, matplotlib.axes.Axes]

Plots the light curve of a given record if data is present. Present fields:

"mag" - plots magnitude vs. time

"FourierCoefs" - plots reconstructed magnitude vs. time and residuals

"phase" - plots phase vs. time

"mag" and "phase" - plots magnitude vs. phase

"distance" - plots distance vs. time

`datetime_to_sec`

datetime_to_sec(datetime: string) -> float

Converts datetime in format "%Y-%m-%d %H:%M:%S" to seconds since epoch.

`sec_to_datetime`

sec_to_datetime(seconds: float) -> string

Converts seconds since epoch to datetime in format "%Y-%m-%d %H:%M:%S".

`get_fourier_series`

get_fourier_series(order: int, period: float = 1) -> Tuple[np.ndarray, np.ndarray, np.ndarray]

Creates a Fourier series function with given order and period.

Parameters

order (int): The order of the Fourier series.

period (float, optional): The period of the Fourier series (default is 1).

Returns

func: Function func(x, coefs)

`fourier_series_fit`

fourier_series_fit(order: int, record: Dict[str, Any], period: float = 1) -> Tuple[np.ndarray, np.ndarray]

Fits a Fourier series to the given record.

Parameters

order (int): The order of the Fourier series.

record (Dict[str, Any]): The record to fit the Fourier series to.

period (float, optional): The period of the Fourier series (default is 1).

Returns - coefs (Array[order+1 x 1]): The Fourier coefficients. - covariance_matrix (Array[order+1 x order+1]): The covariance matrix of coeficients.

`correct_standard_magnitude`

correct_standard_magnitude(mag: float|array[float], distance: float|array[float], phase: float|array[float]]) -> float|array[float]

correct_standard_magnitude corrects the standardized magnitude to apparent magnitude.

Source: McCue GA, Williams JG, Morford JM. Optical characteristics of artificial satellites. Planetary and Space Science. 1971;19(8):851-68. Available from: https://www.sciencedirect.com/science/article/pii/0032063371901371.

Name	Value
`PERIODIC`	'periodic'
`APERIODIC`	'aperiodic'
`NONVARIABLE`	'non-variable'

Name	Value	Description
`ID`	'id'	track id
`NORAD_ID`	'norad_id'	object norad id
`TIMESTAMP`	'timestamp'	timestamp of the measurement
`PERIOD`	'period'	apparent rotational period
`TIME`	'time'	list of time measurements
`MAG`	'mag'	list of standartized magnitude measurements
`PHASE`	'phase'	list of phase angle measurements
`DISTANCE`	'distance'	list of distance measurements
`FILTER`	'filter'	list of filter measurements
`VARIABILITY`	'variability'	object variability type
`NAME`	'name'	object name
`LABEL`	'label'	class label
`RANGE`	'range'	index range of original measurements