API

posterior

Utilities for creating the posterior and inference data objects for interfacing with popclass’ classification function.

class popclass.posterior.InferenceData(posterior, prior_density)

popclass version of an object containing the inference data for classification, including posterior samples and prior density.

Similar to popclass.Posterior, but is intended to include prior information to be passed to the classifier.

class popclass.posterior.Posterior(samples, parameter_labels)

popclass object containing the user’s posterior information. This object can either be initialized from data arrays, or come from outside libraries in a compatible format. Acceptable formats from outside sources are listed below.

Supported Formats:

• ArViz

• BAGLE (Microlensing specific, see below)

classmethod from_arviz(arviz_posterior_object)

Utility to convert an ArViz posterior object directly to popclass posterior object.

Parameters:

arviz_posterior_object (arviz.InferenceData) – InferenceData from an ArViz run.

Returns:

A popclass.Posterior object generated from the ArViz posterior.

Return type:

popclass.Posterior

Raises:

ValueError – if the number of parameters is not less than the number of samples.

classmethod from_pymultinest(pymultinest_analyzer_object, parameter_labels)

Utility to convert a PyMultiNest posterior to a popclass posterior object.

Parameters:

• pymultinest_analyzer_object – Analyzer object from PyMultiNest

• parameter_labels (list[str]) – Ordered list of parameters. Should correspond to the order of parameters in pymultinest_analyzer_object.

Returns:

A Posterior object with samples from the PyMultiNest analysis.

Return type:

popclass.Posterior

Raises:

ValueError – if the number of parameters is not less than the number of samples.

marginal(parameter_list)

Get marginal distribution for some ordered subset of parameters in Posterior

Parameters:

parameter_list (list[str]) – List of parameters for generating a marginal distribution. Should be a subset of Posterior.parameter_labels().

Returns:

New instance of the Posterior object only containing samples determined and ordered by parameter_list.

Raises:

ValueError – if the number of parameters is not less than the number of samples.

property parameters

Defines an ordered list of parameters for the Posterior object.

Returns:

Ordered list of parameters in the Posterior object.

Return type:

parameters (list [str])

to_inference_data(prior_density)

Go from the Posterior object to a new InferenceData object.

Parameters:

• posterior_object (popclass.Posterior) – Either a popclass Posterior or ``Posterior.marginal() `` object.

• prior_density (array-like) – 1D array representing the prior density with an expected shape of (number of samples,). Prior density corresponds to samples in posterior_object, as the number of entries must match the number of rows in the posterior samples array.

Returns:

An InferenceData object that contains all the information needed to pass to a classifier.

Return type:

popclass.InferenceData

model

In order to make object classification probabilities, we must define a galactic model. popclass allows the user to either specify one of the models included with the library or supply their own, given that it is in ASDF file format.

class popclass.model.CustomKernelDensity(data, **kwargs)

An example of defining a custom kernel for a PopulationModel. Wraps sklearn.neighbors.KernelDensity to conform to the template needed by PopulationModel and classify.

evaluate(pts)

Evaluation method for calculating the pdf of the kernel at a set of points.

Parameters:

pts (numpy.array) – array of points to evaluate the density on. Shape: [# dimensions, # of points].

Returns:

the probability density values at each of the corresponding points.

Return type:

evaluated_density (numpy.array)

class popclass.model.MultivariateGaussianKernel(data)

An example of defining a custom kernel for a PopulationModel. Wraps scipy.stats.multivariate_normal to conform to the template needed by PopulationModel and classify.

evaluate(pts)

Evaluation method for calculating the pdf of the kernel at a set of points.

Parameters:

pts (numpy.array) – array of points to evaluate the density on. Shape: [# dimensions, # of points].

Returns:

the probability density values at each of the corresponding points.

Return type:

evaluated_density (numpy.array)

class popclass.model.PopulationModel(population_samples, class_weights, parameters, citation=None, density_estimator=<class 'scipy.stats._kde.gaussian_kde'>, density_kwargs={})

Used to store information on simulation data necessary for classification.

property citation

Return the citation of the population model.

Returns:

List of DOI entries corresponding to cite the model.

class_weight(class_name)

Return the class weight for a given class.

Returns:

Class Weight for the specified class.

property classes

Return all classes available in the population model.

Returns:

List of all classes available.

evaluate_density(class_name, parameters, points)

Evaluate the kernel density estimate of a point for a class.

Parameters:

• class_name (str) – name of class to evaluate density.

• parameters (list[str]) – parameters to evaluate population model density over. Order sets the order of the second dimension of points.

• points (np.ndarray) – data to evalute density on. Has shape (num_data_points, len(parameters)).

Returns:

density_evaluation (np.ndarray)

classmethod from_asdf(path)

Build population model from data in an asdf file. This file can be user-generated, but must adhere to the schema of the files included in the library.

Parameters:

path (str) – path to the asdf file

Returns:

PopulationModel populated with the data from the asdf file.

classmethod from_library(model_name, library_path=None)

Build population model from available models.

Available models include

• popsycle_singles_raithel18

• popsycle_singles_spera15

• popsycle_singles_sukhboldn20

Parameters:

• model_name (str) – Name of the model.

• library_path (str) – Path to library of models.

Returns:

PopulationModel from library of avaible models.t

property parameters

Return all parameters available in the population model.

Returns:

List of all parameters.

samples(class_name, parameters)

Return simulation samples for a given class and given list of parameters.

Parameters:

• class_name – (str): name of class to get population samples for.

• parameters – (list[str]): List of parameters to get samples for.

Returns:

samples of shape (num_samples, len(parameters)) with the order of the second dimension being set by the order of parameters.

to_asdf(path, model_name)

Save population model to asdf file.

Parameters:

• path (str) – path to save the asdf file

• model_name (str) – Name of the model to be saving in the asdf file.

popclass.model.validate_asdf_population_model(asdf_object)

Check if PopulationModel asdf file is valid.

Parameters:

asdf_object (asdf) – asdf file to validate against a Population model required format.

Returns:

True if asdf is valid. False otherwise.

classify

Main function and usage case for popclass. Will take an InferenceData and PopulationModel object and return object class probabilities for classes in PopulationModel.classes().

popclass.classify.classify(inference_data, population_model, parameters, additive_uq=None)

popclass classification function. Takes in popclass.InferenceData and popclass.PopulationModel objects, then returns class probabilities.

Parameters:

• inference_data (popclass.InferenceData) – popclass InferenceData object

• population_model (popclass.PopulationModel) – popclass PopulationModel object

• parameters (list) – Parameters to use for classification.

Returns:

Dictionary of classes in PopulationModel.classes() and associated probability.

visualization

Light visualization library.

popclass.visualization.get_bounds(PopulationModel, parameters)

Creates bounds on the basis of a PopulationModel and given parameters, if they are not specified by the user. Bounds are automatically constructed to be 10% of the extent in samples beyond the minimum and maximum value found in samples for each parameter.

Parameters:

• PopulationModel (class) –

• parameters (list of str) - a subset of parameters for visualization (must be found in PopulationModel.parameters) –

Return type:

bounds (numpy.ndarray) - pairs of upper and lower bounds for each parameter. Shape (N_dim, 2), where N_dim is equal to the number of parameters and has the same order.

popclass.visualization.plot_population_model(PopulationModel, parameters=None, plot_samples=False, plot_kdes=True, bounds=None, N_bins=200, N_hist=40, levels=5, legend=False)

Represent the population samples and/or their KDEs in the defined parameter space for each individual class in a figure.

Parameters:

• PopulationModel (class) –

• parameters (list of str) - a subset of parameters of the population model to create a subspace for visualization (must be found in PopulationModel.parameters) –

• plot_samples (bool, optional) – False.

• plot_kdes (bool, optional) - flag for plotting the simulated population KDEs (according to the evaluate_density method specified in PopulationModel) – True.

• bounds (array-like or None, optional) - pairs of upper and lower bounds for each parameter or None. If provided, should have a shape (N_dim, 2) – None.

• N_bins (int, optional) - Resolution of the grid to evaluate the KDEs on (if plot_kdes=True) –

• N_hist (int, optional) - Resolution of the 1D histogram of samples (if plot_samples=True) –

• levels (int or array-like, optional) - Number and/or positions of contour lines (for >1D KDE plotting) –

• legend (bool) – False.

Return type:

fig, ax (matplotlib objects) - figure visualising population distributions in the specified parameter space

popclass.visualization.plot_rel_prob_surfaces(PopulationModel, parameters=None, plot_samples=False, bounds=None, N_bins=1000, create_none_class=None, none_kde=None, none_kde_kwargs={})

Plots 2D relative probability surfaces (p(class | parameters, model)). A visualisation of probability the classifier would return, for points with exactly known parameters, of belonging to the given class, taking into account distributions and weights of all classes.

Parameters:

• PopulationModel (class) –

• parameters (list of str) - a subset of parameters of the population model to create a subspace for visualization (must be found in PopulationModel.parameters) –

• plot_samples (bool, optional) – False.

• bounds (array-like or None, optional) - pairs of upper and lower bounds for each parameter or None. If provided, should have a shape (N_dim, 2) – None.

• N_bins (int, optional) –

• create_none_class (popclass.NoneClassUQ-like or None, optional) – None.

• none_kde (scipy.stats.gaussian_kde-like, optional) – None.

• none_kde_kwargs (dictionary) – {}.

Return type:

figs, axes (lists of matplotlib objects) - figures visualising relative probability surfaces in the specified parameter space (one for each class)

uncertainty quantification

The classification framework is susceptible to systematic error through a variety of sources, including model assumptions (e.g. incomplete populations) or simulation noise in the tails of the distribution. This set of utilities allows users to incorporate uncertainty quantification into the classification.

popclass.uq.calculate_square_grid_centers(grid)

Calculates the coordinates of the corners for a grid bounded in some domain in arbitrary dimension.

Parameters:

grid (dictionary) – dictionary containing the bin edges for each dimension, keyed by the parameter name

Returns:

Dictionary containing the grid edges in each dimension. Format: {parameter_key : np.array(size=grid_size-1)}

grid_mesh_centers (numpy.array):

Numpy containing the meshed grid, shape [dimensions, grid_size-1, …] with a total of dimensions + 1 along the first axis

grid_centers_raveled (numpy.array):

Numpy array containing the raveled grid corner coordinates, shape [(grid_size-1)***dimensions, dimensions]

Return type:

grid_centers (dictionary)

popclass.uq.calculate_square_grid_coordinates(grid_size, bounds)

Calculates the coordinates of the corners for a grid bounded in some domain in arbitrary dimension.

Parameters:

• grid_size (int) – number of bin edges per dimension

• bounds (dictionary) – Dictionary containing the lower and upper bounds of the parameter space, with keys matching the supplied ``parameter’’ list. Format: {key : [lower_bound, upper_bound]}

Returns:

Dictionary containing the grid edges in each dimension. Format: {parameter_key : np.array(size=grid_size)}

grid_mesh (numpy.array):

Numpy containing the meshed grid, shape [dimensions, grid_size, …] with a total of dimensions + 1 along the first axis

grid_corners (numpy.array):

Numpy array containing the raveled grid corner coordinates, shape [grid_size**dimensions, dimensions]

Return type:

grid (dictionary)