chronostar package#

Subpackages#

Submodules#

chronostar.base module#

class chronostar.base.BaseComponent(params=None)#

Bases: object

Abstract class for a (assumed-to-be Gaussian) component to be used in a mixture model

Capable of fitting itself to a set of samples and responsibilities (membership probabilities)

Parameters:

params (ndarray of shape(n_params), optional) – The model parameters, as a 1 dimensional arra

classmethod configure(**kwargs)#

Set any configurable class attributes

Return type:

None

abstract estimate_log_prob(X)#

Calculate the log probability of each sample in X given this components current estimated parameters

Parameters:

X (ndarray of shape (n_samples, n_features)) – Input data

Returns:

Log probabilities

Return type:

ndarray of shape (n_samples)

abstract get_parameters()#

Get parameters

Returns:

a single 1D array of the component parameters

Return type:

ndarray of shape (n_params)

abstract maximize(X, resp)#

Maximize the model parameters on a set of data and responsibilities

Parameters:

  • X (ndarray of shape (n_samples, n_features)) – Input data

  • resp (ndarray of shape (n_samples, n_components)) – Responsibilities (or membership probabilities) of each sample to each component

Return type:

None

abstract property n_params: int#

The number of parameters required to describe this component’s model

Necessary for calculating information criteria that depend on number of parameters, e.g. BIC or AIC

Returns:

How many parameters describe this model

Return type:

int

abstract set_parameters(params)#

Set parameters

Parameters:

params (ndarray of shape (n_params)) – a single 1D array of the component parameters

Return type:

None

abstract split()#

Split this component into two by some means.

Popular approach is to split along the primary axis

Returns:

Two components with identical parameters except half as wide and offset from mean

Return type:

tuple[BaseComponent, BaseComponent]

class chronostar.base.BaseICPool(component_class, start_init_comps=None)#

Bases: object

A pool of sets of initial conditions, stored as a queue

Parameters:

component_class (Type[BaseComponent]) – A class derived from BaseComponent

abstract property best_mixture: BaseMixture#

Get the best scoring mixture

Returns:

The best scoring mixture

Return type:

BaseMixture

Note

Perhaps an extension is to keep track of the top N best mixtures

classmethod configure(**kwargs)#

Set any configurable class attributes

Return type:

None

abstract get_next()#

Pop the next initial conditions of internal queue and return it with a unique identifier

Returns:

An initial condition: a tuple of components, paired with a unique, informative id

Return type:

InitialCondition

abstract has_next()#

Determine if internal queue is non-empty, after attempting to repopulate as needed.

Returns:

Whether the queue is non-empty

Return type:

bool

abstract register_result(unique_id, mixture, score)#

Register a finished mixture fit with its score

Parameters:

  • unique_id (str) – Unique identifier that was provided along with initial conditions

  • mixture (BaseMixture) – A mixture model that has been fit

  • score (float) – The score of the mixture model

Return type:

None

class chronostar.base.BaseMixture(init_weights, init_comps)#

Bases: object

A Mixture model (e.g. Gaussian Mixture Model) consisting of components

Parameters:

  • init_weights (ndarray of shape(n_components) or (n_samples, n_components)) – The initial weight of components, ideally normalized such that sums to 1. If init_weights is 2D the it is interpreted as initial membership probabilities

  • init_comps (list[BaseComponent]) – A list of component objects, which may optionally already have pre-set parameters.

abstract bic(X)#

Calculate the Bayesian Information Critereon (BIC)

Parameters:

X (NDArray[float64] of shape (n_samples, n_features)) – Input data

Returns:

The BIC

Return type:

float

classmethod configure(**kwargs)#

Set any configurable class attributes

Return type:

None

estimate_membership_prob(X)#

Estimate the membership probability of each star to each component

Parameters:

X (NDArray[float64] of shape (n_samples, n_features)) – Input data

Returns:

The membership probability of each star to each component. Each row should sum to 1, each column should average to the corresponding component’s weight

Return type:

NDArray[float64] of shape (n_samples, n_components)

abstract estimate_weighted_log_prob(X)#

Estimate the weighted log-probabilities, log P(X | Z) + log weights.

Parameters:

X (array-like of shape (n_samples, n_features)) –

Returns:

weighted_log_prob

Return type:

array, shape (n_samples, n_component)

abstract fit(X)#

Fit the mixture model to the data

Parameters:

X (NDArray[float64] of shape (n_samples, n_features)) – Input data

Return type:

None

abstract get_components()#

Return the components of the mixture model

Returns:

A tuple of the components

Return type:

tuple[BaseComponent, …]

abstract get_parameters()#

Get the parameters of the mixture model

Returns:

The weights of the components and a tuple of the components

Return type:

tuple[NDArray[float64], tuple[BaseComponent, …]]

abstract set_parameters(params)#

Set the parameters of the mixture model

Parameters:

params (tuple[NDArray[float64], tuple[BaseComponent, ...]]) – The weights of the components and a tuple of the components

Return type:

None

class chronostar.base.InitialCondition(label: str, components: tuple[BaseComponent, ...])#

Bases: NamedTuple

Simple named tuple for pairing an informative label with a list of initial components

Parameters:

  • label (str or int) – unique identifer combined with extra information

  • components (list[BaseComponent]) – A list of components that can initialise a mixture fit

components: tuple[chronostar.base.BaseComponent, ...]#

Alias for field number 1

label: str#

Alias for field number 0

class chronostar.base.ScoredMixture(mixture: BaseMixture, score: float, label: str)#

Bases: NamedTuple

Simple named tuple for pairing mixtures with their scores

Parameters:

  • mixture (BaseMixture) – A mixture model whose fit method has been called

  • score (float) – The score of the mixture model

label: str#

Alias for field number 2

mixture: BaseMixture#

Alias for field number 0

score: float#

Alias for field number 1

chronostar.datatools module#

chronostar.datatools.construct_covs_from_data(X, dim=6)#

Reconstruct covariance matrices from data rows

Parameters:

  • X (NDArray[float64] of shape (n_samples, n_features)) – Input data

  • dim (int, default 6) – The dimensions of the means and covariance matrices

Notes

Structure of data is assumed to be (in the case of dim=6): .. code:

X, Y, Z, U, V, W, DX, DY, DZ, DU, DV, DW,
XY_cov, XZ_cov, XU_cov, XV_cov, XW_cov,
        YZ_cov, YU_cov, YV_cov, ...
etc.
Return type:

tuple[ndarray[Any, dtype[float64]], ndarray[Any, dtype[float64]]]

chronostar.datatools.extract_array_from_table(table, msk=None)#

Take data from a table and convert into numpy array

Parameters:

  • table (Table) – An astropy table with measurement column names ra, dec, parallax, pmra, pmdec, and radial_velocity, as well as ra_error, dec_error etc, and optionally any subset of pair-wise correlations, ra_dec_corr, ra_parallax_corr etc., but in the order of measurement column names as given above

  • msk (Optional[NDArray], optional) – A mask (boolean or index) for the table rows to be used, by default None

Returns:

A float array of shape (nstars, 27) where the first 6 columns are measurements ra, dec, parallax, pmra, pmdec, radial_velocity, the next 6 columns are the errors, and the next 15 are the pairwise covariances in the ordering: ra_dec, ra_parallax, ra_pmra, ra_pmdec, ra_radial_velocity, dec_parallax, etc.

Return type:

NDArray[float64]

chronostar.datatools.replace_cov_with_sampling(data, covs=None, n_draws=100, dim=6)#

Replace uncertainty covariances with a random sampling of the implied distribution

Parameters:

  • data (NDArray[float64] of shape (n_samples, n_features)) – Input data. If covs is None, then data should have dim + “dimth triangle number” columns, with the final dimth triangle number columns encoding covariance matrices

  • covs (Optional[NDArray[float64]] of shape (n_samples, 6, 6), optional) – An array of covariance matrices, by default None

  • n_draws (int, optional) – the number of random draws to take from each star’s distribution, by default 100

  • dim (int, optional) – dimensions, by default 6

Returns:

A pseudo data set, where each initial sample is replaced by a swarm of samples

Return type:

NDArray[float64] of shape (n_samples * n_draws, dim)

chronostar.driver module#

class chronostar.driver.Driver(config_file, mixture_class=<class 'chronostar.mixture.componentmixture.ComponentMixture'>, icpool_class=<class 'chronostar.icpool.simpleicpool.SimpleICPool'>, component_class=<class 'chronostar.component.spherespacetimecomponent.SphereSpaceTimeComponent'>)#

Bases: object

Top level class of Chronostar which drives the entire fitting process

Parameters:

  • config_file (Union[str, Path]) – A yaml configuration file with sections mixture, icpool, introducer and component.

  • mixture_class (Type[BaseMixture], default ComponentMixture) – A class derived from BaseMixture

  • icpool_class (Type[BaseICPool], default SimpleICPool) – A class derived from BaseICPool

  • component_class (Type[BaseComponent], default SphereSpaceTimeComponent) – A class derived from BaseComponent

intermediate_dumps#

Whether to write to file the results of mixture model fits, configurable

Type:

bool, default True

savedir#

Path to the directory of where to store results, configurable

Type:

str, default ‘./result’

configure(**kwargs)#

Set any configurable class attributes

Return type:

None

dump_all_config_params(fp)#

Get all configurable parameters and write them to file

This method attempts to identify all class level parameters that could be configurable and writes them all to file.

Parameters:

fp (TextIOWrapper) – File pointer to output file

Return type:

None

dump_mixture_result(dump_dir, label, mixture, data)#

Store the result of a mixture to file

Parameters:

  • label (str) – The unique label of the initial condition of the mixture

  • mixture (BaseMixture) – The (fitted) mixture model

  • data (NDArray of shape (n_samples, n_features)) – The input data

Return type:

None

read_config_file(config_file)#

Read the contents of the config file into a dictionary

Parameters:

config_file (Union[str, Path]) – A yaml configuration file with sections mixture, icpool, introducer and component.

Returns:

A dictionary of all configuration parameters

Return type:

dict[str, Any]

Raises:

  • yaml.YAMLError – A yaml exception, in the event the file can’t be read

  • UserWarning – If the file has an unrecognised key at top-most level

run(data, start_init_comps=None, init_resp=None)#

Run a fit on the input data

Parameters:

  • data (NDArray[float64] of shape (n_samples, n_features)) – The input data

  • start_init_comps (InitialCondition, optional) – Parameters defining a mixture model, which serves as a starting point for the entire run.

  • init_resp (NDArray[float64] of shape (n_samples, n_comps), optional) – Starting point for component memberships

Returns:

A mixture object containing the best fitting parameters, retrievable by mixture.get_parameters()

Return type:

BaseMixture

chronostar.synthdata module#

synthdata.py Used for testing only.

A class plus a couple of functions helpful for generating synthetic data sets.

synthesiser Used to generate realistic data for one (or many) synthetic association(s) with multiple starburst events along with a background as desired. From a parametrised gaussian distribution, generate the starting XYZUVW values for a given number of stars TODO: accommodate multiple groups

chronostar.synthdata.generate_association(mean_now, covariance_birth, age, nstars=100, rng=None)#

Generate stars based on an association’s position, birth cov and age

Note that the parameters are current position, but birth covariance. This is because when generating a synthetic association, we typically don’t care where it was born, but rather where it is now, so that we can allign it up with other synthetic associations.

Parameters:

  • mean_now (array of shape(6)) – Current day location of association in cartesian space

  • covariance_birth (array of shape(6, 6)) – Covariance of association at birth in cartesian space

  • age (float) – Desired age of association

  • nstars (int, optional) – number of stars, by default 100

  • rng (np.random.default_rng, optional) – numpy’s random number generator, by default None

Returns:

6D Cartesian data of stars

Return type:

array of shape (nstars, 6)

chronostar.traceorbit module#

Module for tracing orbits using the epicyclic approximation

chronostar.traceorbit.epicyclic_approx(data, times=None, sA=0.89, sB=1.15, sR=1.21)#

MZ (2020 - 01 - 17)

Epicyclic approximation following the Makarov et al. 2004 paper in the curvilinear coordinate system: The radial component xi is pointing towards the Galactic center at all times and equals 0 at R0. The circular component eta circles around the Galaxy; eta = phi*R. The vertical component is defined as a displacement from the Galactic plane.

This approximation works close to the LSR.

Parameters:

data ([pc, pc*, pc, km/s, km/s, km/s]) –

xi, eta, zeta, xidot, etadot, zetadot

# *parsecs in the eta component are scales parsecs…

chronostar.traceorbit.trace_epicyclic_orbit(xyzuvw_start, time=None, sA=0.89, sB=1.15, sR=1.21, ro=8.0, vo=220.0)#

MZ (2020 - 01 - 17)

Given a star’s XYZUVW relative to the LSR (at any time), project its orbit forward (or backward) to each of the time listed in time using epicyclic approximation. This only works close to the LSR.

Positive time –> traceforward Negative time –> traceback

Parameters:

  • xyzuvw_start (float array of shape (6)) – Starting point of orbit: x, y, z, u, v, w with pc units for position and km/s units for velocity

  • time ((float) or ([ntime] float array)) – One (or many) times by which to calculate the orbit

Returns:

xyzuvw_tf – [pc, pc, pc, km/s, km/s, km/s] - the traced orbit with positions and velocities

Return type:

[ntime, 6] array

Module contents#