ROOSTER

ROOSTER#

class star_privateer.ROOSTER(rotclass_kwargs=None, periodsel_kwargs=None, **kwargs)#

ROOSTER object, wrapping a random forest classifiers framework designed to analyse surface rotation in stellar light curves.

__init__(rotclass_kwargs=None, periodsel_kwargs=None, **kwargs)#

Initiate a new ROOSTER instance. A RotClass and a PeriodSel classifiers are both created as attributes of the ROOSTER object. Additional parameters provided when initialising a ROOSTER instance will be passed to sklearn.ensemble.RandomForestClassifier.

Parameters:

  • rotclass_kwargs (dict) – Keyword arguments to pass to the RotClass random forest classifier. Optional, default None.

  • periodsel_kwargs (dict) – Keyword arguments to pass to the PeriodSel random forest classifier. Optional, default None.

  • **kwargs – Keyword arguments common to both random forest classifiers.

analyseSet(features, p_candidates, e_p_err=None, E_p_err=None, feature_names=None, target_id=None)#

Analyse provided targets using ROOSTER.

Parameters:

  • features (ndarray) – Feature on which to perform the classification. Must be of shape (n, n_features).

  • p_candidates (ndarray) – Candidate periods to be recovered by PeriodSel. Must be of shape (n, n_class) where n_class is the number of methods used to provided rotation period candidates for each target.

  • e_p_err (ndarray) – Lower uncertainties on periods from p_candidates. Selected period uncertainties will be provided as output if e_p_err and E_p_err are provided. Optional, default None.

  • E_p_err (ndarray) – Upper uncertainties on periods from p_candidates. Selected period uncertainties will be provided as output if e_p_err and E_p_err are provided. Optional, default None.

  • feature_names (ndarray) – Feature names. Must be of shape (n_features). In case provided feature names are not consistent with the ones used to train the classifiers, an exception will be raised. Optional, default None.

  • target_id (ndarray) – If provided, will be stored in memory as the last set of identifiers analysed by the classifiers. Optional, default None.

Returns:

Tuple of arrays with, in this order, the rotation score attributed by RotClass, the rotation period selected by PeriodSel, and, if e_p_err and E_p_err were provided as input, the corresponding lower and upper uncertainties on periods.

Return type:

tuple of arrays

computePeriodSelTrueAccuracy(target_id, predicted_periods, tolerance=0.1, catalog='santos-19-21')#

Compute PeriodSel true Accuracy for a given sample of target by comparing the reference period value to the value chosen by ROOSTER, with a tolerance interval.

Parameters:

  • target_id (ndarray) – Identifiers of the n targets for which parameters are provided. Non-unique identifiers are allowed.

  • predicted_periods (ndarray) – Periods predicted by PeriodSel.

  • tolerance (float) – Tolerance to consider when comparing predicted_periods to the reference periods

  • catalog (str) – Catalog to consider for the reference rotation period value of each target. Optional, default santos-19-21.

Returns:

The PeriodSel classifier true accuracy.

Return type:

float

getFeatureNames()#

Get name of feature that ROOSTER requires for classification.

getLastAnalysisInfo()#

Get list of identifiers and corresponding classes obtained with the last analysis run.

Returns:

Arrays with target identifiers (might be None if they were not provided), corresponding rotation score, and index of selected period (with respect to the p_candidates array that was provided).

Return type:

tuple of arrays

getNumberEltTest()#

Return a tuple of integer, corresponding to the number of elements used to train each ROOSTER classifier.

getNumberEltTrain()#

Return a tuple of integer, corresponding to the number of elements used to train each ROOSTER classifier.

getScore()#

Returns ROOSTER classifying scores. Scores are returned in the following order: RotClassTestScore, PeriodSelTestScore. The ROOSTER instance must have been trained and tested before.

getTestPeriodSelInfo()#

Get list of identifiers and corresponding classes obtained when testing PeriodSel.

Returns:

Arrays with target identifiers, corresponding reference classes, and predicted classes.

Return type:

tuple of arrays

getTestRotClassInfo()#

Get list of identifiers and corresponding classes obtained when testing RotClass.

Returns:

Arrays with target identifiers, corresponding reference classes, and predicted classes.

Return type:

tuple of arrays

getTrainingPeriodSelInfo()#

Get list of identifiers and corresponding classes used to train PeriodSel.

Returns:

Arrays with target identifiers and corresponding reference classes.

Return type:

tuple of arrays

getTrainingRotClassInfo()#

Get list of identifiers and corresponding classes used to train RotClass.

Returns:

Arrays with target identifiers and corresponding reference classes.

Return type:

tuple of arrays

save(filename)#

Save the ROOSTER instance as filename.

selectParam(candidates)#

Select a parameter corresponding to the rotation periods selected previously by PeriodSel. The analyseSet function must be run before using this function.

Parameters:

candidates (ndarray) – parameters to consider to perform the selection. The array must have the same shape as the p_candidates array that was provided to analyseSet.

test(target_id, p_candidates, features, catalog='santos-19-21', verbose=False, feature_names=None, e_p_err=None, E_p_err=None, tolerance=0.1)#

Test ROOSTER classifiers with the provided test set.

Parameters:

  • target_id (ndarray) – Identifiers of the n targets for which parameters are provided. Non-unique identifiers are allowed.

  • p_candidates (ndarray) – Candidate periods to be recovered by PeriodSel. Must be of shape (n, n_class) where n_class is the number of methods used to provided rotation period candidates for each target.

  • features (ndarray) – Feature on which to perform the classification. Must be of shape (n, n_features).

  • feature_names (ndarray) – Feature names. Must be of shape (n_features). Optional, default None.

  • e_p_err (ndarray) – Lower uncertainties on periods from p_candidates. Selected period uncertainties will be provided as output if e_p_err and E_p_err are provided. Optional, default None.

  • E_p_err (ndarray) – Upper uncertainties on periods from p_candidates. Selected period uncertainties will be provided as output if e_p_err and E_p_err are provided. Optional, default None.

  • catalog (str) – Catalog to consider for the reference rotation period value of each target. Optional, default santos-19-21.

  • verbose (bool) – Output verbosity. Optional, default False.

  • tolerance (float) – Tolerance to consider when checking that at least one period in p_candidates is compatible with the target reference period (therefore allowing to use the target in the test set.

Returns:

Tuple of array with, in this order, target identifiers tested for RotClass, inferred class (rot or norot), target identifiers tested for PeriodSel, selected periods, and, if e_p_err and E_p_err were provided as input, corresponding lower and upper uncertainties on periods.

Return type:

tuple of array

train(target_id, p_candidates, features, feature_names=None, catalog='santos-19-21', verbose=False, tolerance=0.1)#

Train ROOSTER classifiers with the provided training set.

Parameters:

  • target_id (ndarray) – Identifiers of the n targets for which parameters are provided. Non-unique identifiers are allowed.

  • p_candidates (ndarray) – Candidate periods to be recovered by PeriodSel. Must be of shape (n, n_class) where n_class is the number of methods used to provided rotation period candidates for each target.

  • features (ndarray) – Feature on which to perform the training. Must be of shape (n, n_features).

  • feature_names (ndarray) – Feature names. Must be of shape (n_features). Optional, default None.

  • catalog (str) – Catalog to consider for the reference rotation period value of each target. Optional, default santos-19-21.

  • verbose (bool) – Output verbosity. Optional, default False.

  • tolerance (float) – Tolerance to consider when checking that at least one period in p_candidates is compatible with the target reference period (therefore allowing to use the target in the training set.

star_privateer.create_rooster_feature_inputs(df, return_err=False, candidate_names=None, candidate_lower_errors=None, candidate_upper_errors=None)#

Take a DataFrame created by build_catalog_features and return ready-to-use input array for ROOSTER training and classification.

Parameters:

  • df (pandas.DataFrame) – The dataframe created by the build_catalog_features function, containing the features that will be used to train and test ROOSTER classifiers.

  • return_err (bool) – If set to True, the uncertainties on the candidate periods will be returned by the function. Optional, default False.

  • candidate_names (list) – Name of the candidate periods to select among the features. If not provided, the default will be ['prot_ps', 'prot_acf', 'prot_cs'] Optional, default None.

  • candidate_lower_errors (list) – Name of the lower uncertainty on the candidate periods to select among the features. If not provided, the default will be ['e_prot_ps', 'e_prot_acf', 'e_prot_cs'] Optional, default None.

  • candidate_upper_errors (list) – Name of the upper uncertainty on the candidate periods to select among the features. If not provided, the default will be ['E_prot_ps', 'E_prot_acf', 'E_prot_cs'] Optional, default None.

Returns:

Tuple of arrays, including, in this order, the target identifiers, the candidate rotation periods, the lower and upper uncertainties on rotation periods (only if return_err is set to True), the training features arrays and the corresponding feature names.

Return type:

tuple of arrays

star_privateer.load_rooster_instance(instance='rooster_default', filename=None, on_the_fly=True, verbose=False, seed=None)#

Load by default one of the pre-trained ROOSTER instances provided by the PLATO MSAP4 demonstrator. If filename is provided, load the ROOSTER instance saved under this name.

Parameters:

  • instance (str) – Name of the ROOSTER instance to load from the module. Optional, default 'rooster_default'.

  • filename (str or Path instance) – If provided, the ROOSTER instance saved under this name will be loaded instead of the instance element. Optional, default None.

  • on_the_fly (bool) – If set to True, no ROOSTER object will be loaded and a new ROOSTER instance will be trained on the fly using a default dataset. Optional, default True.

  • verbose (bool) – Output verbosity.

  • seed (int) – Random seed to use in case on_the_fly is set to True. Optional, default None.

Return type:

ROOSTER object.