popsynth package

Subpackages

• popsynth.aux_samplers package
  • Submodules
    • popsynth.aux_samplers.delta_aux_sampler module
    • popsynth.aux_samplers.lognormal_aux_sampler module
    • popsynth.aux_samplers.normal_aux_sampler module
    • popsynth.aux_samplers.plaw_aux_sampler module
    • popsynth.aux_samplers.sky_sampler module
    • popsynth.aux_samplers.trunc_normal_aux_sampler module
    • popsynth.aux_samplers.viewing_angle_sampler module
  • Module contents
• popsynth.distributions package
  • Submodules
    • popsynth.distributions.bpl_distribution module
    • popsynth.distributions.cosmological_distribution module
    • popsynth.distributions.delta_distribution module
    • popsynth.distributions.flatland_distribution module
    • popsynth.distributions.log10_normal_distribution module
    • popsynth.distributions.log_normal_distribution module
    • popsynth.distributions.pareto_distribution module
    • popsynth.distributions.schechter_distribution module
    • popsynth.distributions.spherical_distribution module
    • popsynth.distributions.spiral_galaxy_distribution module
    • popsynth.distributions.uniform_distribution module
  • Module contents
• popsynth.populations package
  • Submodules
    • popsynth.populations.bpl_population module
    • popsynth.populations.lognormal_population module
    • popsynth.populations.pareto_populations module
    • popsynth.populations.schechter_populations module
    • popsynth.populations.spatial_populations module
  • Module contents
• popsynth.selection_probability package
  • Submodules
    • popsynth.selection_probability.flux_selectors module
    • popsynth.selection_probability.generic_selectors module
    • popsynth.selection_probability.selection_probability module
    • popsynth.selection_probability.spatial_selection module
  • Module contents
• popsynth.utils package
  • Submodules
    • popsynth.utils.array_to_cmap module
    • popsynth.utils.configuration module
    • popsynth.utils.cosmology module
    • popsynth.utils.hdf5_utils module
    • popsynth.utils.logging module
    • popsynth.utils.meta module
    • popsynth.utils.package_data module
    • popsynth.utils.progress_bar module
    • popsynth.utils.registry module
    • popsynth.utils.rejection_sample module
    • popsynth.utils.spherical_geometry module
  • Module contents

Submodules

• popsynth.auxiliary_sampler module
• popsynth.distribution module
• popsynth.population module
• popsynth.population_synth module
• popsynth.simulated_variable module

Module contents

class popsynth.AuxiliarySampler(name: str, observed: bool = True, uses_distance: bool = False, uses_luminosity: bool = False, uses_sky_position: bool = False)

Bases: object

__init__(name: str, observed: bool = True, uses_distance: bool = False, uses_luminosity: bool = False, uses_sky_position: bool = False) → None

Base class for auxiliary samplers.

Parameters

• name (str) – Name of the sampler

• observed (bool) – True if the property is observed, False if it is latent. Defaults to True

• uses_distance (bool) – True if sampler uses distance values

• uses_luminosity (bool) – True if sampler uses luminosities

• uses_sky_position (bool) – True if sampler uses sky positions

display()

set_luminosity(luminosity: Union[_SupportsArray[dtype], _NestedSequence[_SupportsArray[dtype]], bool, int, float, complex, str, bytes, _NestedSequence[Union[bool, int, float, complex, str, bytes]]]) → None

Set the luminosity values.

Parameters

luminosity (ArrayLike) – Luminosity

set_spatial_values(value: SpatialContainer) → None

Set the spatial values.

Parameters

value (SpatialContainer) – Spatial values

set_selection_probability(selector: SelectionProbability) → None

Set a selection probabilty for this sampler.

Parameters

selector (SelectionProbability) – A selection probability oobject

Returns

_apply_selection() → None

Default selection if none is specfied in child class.

set_secondary_sampler(sampler: AuxiliarySampler) → None

Add a secondary sampler upon which this sampler will depend. The sampled values can be accessed via an internal dictionary with the samplers ‘name’

self._secondary_sampler[‘name’].true_values self._secondary_sampler[‘name’].obs_values

Parameters

sampler ("AuxiliarySampler") – An auxiliary sampler

Returns

draw(size: int = 1)

Draw the primary and secondary samplers. This is the main call.

Parameters

size (int) – The number of samples to draw

property probability: ndarray

reset()

Reset all the selections.

make_secondary(parent_name: str) → None

sets this sampler as secondary for book keeping

Parameters

parent_name (str) –

Returns

get_secondary_properties(graph=None, primary=None, spatial_distribution=None) → SecondaryStorage

Get properties of secondary samplers.

Parameters

• graph – Graph

• primary – Primary sampler

• spatial_distribution – Spatial Distribution

Returns

Dict of samplers

Return type

SamplerDict

get_secondary_objects(recursive_secondaries: Optional[Dict[str, Any]] = None) → Dict[str, Any]

Get secondary objects.

Parameters

recursive_secondaries – Recursive dict of secondaries

Returns

Dict of objects

Return type

Dict[str, Any]

property secondary_samplers: Dict[str, Dict[str, Union[_SupportsArray[dtype], _NestedSequence[_SupportsArray[dtype]], bool, int, float, complex, str, bytes, _NestedSequence[Union[bool, int, float, complex, str, bytes]]]]]

Secondary samplers. :returns: Dict of secondary samplers :rtype: SamplerDict

property is_secondary: bool

If another sampler depends on this

Returns

property parents: List[str]

The parents of this sampler

property has_secondary: bool

if this sampler has a secondary :returns:

property observed: bool

if this sampler is observed

Returns

property name: str

The name of the sampler

Returns

property obs_name: str

property true_values: ndarray

The true or latent values

Returns

property obs_values: ndarray

The values obscured by measurement error.

Returns

property selection: ndarray

The selection booleans on the values

Returns

property selector: SelectionProbability

The selection probability object

Returns

property truth: Dict[str, float]

A dictionary containing true paramters used to simulate the distribution

property uses_distance: bool

If this uses distance

Returns

property uses_sky_position: bool

If this uses sky position

Returns

property uses_luminosity: ndarray

If this uses luminosity

Returns

property luminosity_distance

luminosity distance if needed.

abstract true_sampler(size: int = 1)

observation_sampler(size: int = 1) → ndarray

class popsynth.DerivedLumAuxSampler(name: str, uses_distance: bool = False)

Bases: AuxiliarySampler

__init__(name: str, uses_distance: bool = False)

Base class for generating luminosity from other properties.

Parameters

• name (str) – Name of the sampler

• uses_distance (bool) – True if sampler uses distance values

abstract compute_luminosity()

class popsynth.Population(luminosities: Union[_SupportsArray[dtype], _NestedSequence[_SupportsArray[dtype]], bool, int, float, complex, str, bytes, _NestedSequence[Union[bool, int, float, complex, str, bytes]]], distances: Union[_SupportsArray[dtype], _NestedSequence[_SupportsArray[dtype]], bool, int, float, complex, str, bytes, _NestedSequence[Union[bool, int, float, complex, str, bytes]]], known_distances: Union[_SupportsArray[dtype], _NestedSequence[_SupportsArray[dtype]], bool, int, float, complex, str, bytes, _NestedSequence[Union[bool, int, float, complex, str, bytes]]], known_distance_idx: Union[_SupportsArray[dtype], _NestedSequence[_SupportsArray[dtype]], bool, int, float, complex, str, bytes, _NestedSequence[Union[bool, int, float, complex, str, bytes]]], unknown_distance_idx: Union[_SupportsArray[dtype], _NestedSequence[_SupportsArray[dtype]], bool, int, float, complex, str, bytes, _NestedSequence[Union[bool, int, float, complex, str, bytes]]], fluxes: Union[_SupportsArray[dtype], _NestedSequence[_SupportsArray[dtype]], bool, int, float, complex, str, bytes, _NestedSequence[Union[bool, int, float, complex, str, bytes]]], flux_obs: Union[_SupportsArray[dtype], _NestedSequence[_SupportsArray[dtype]], bool, int, float, complex, str, bytes, _NestedSequence[Union[bool, int, float, complex, str, bytes]]], selection: Union[_SupportsArray[dtype], _NestedSequence[_SupportsArray[dtype]], bool, int, float, complex, str, bytes, _NestedSequence[Union[bool, int, float, complex, str, bytes]]], flux_sigma: float, r_max: float, n_model: int, lf_params: Dict[str, Any], spatial_params: Optional[Dict[str, Any]] = None, model_spaces: Optional[Union[_SupportsArray[dtype], _NestedSequence[_SupportsArray[dtype]], bool, int, float, complex, str, bytes, _NestedSequence[Union[bool, int, float, complex, str, bytes]]]] = None, seed: int = 1234, name: Optional[str] = None, spatial_form: Optional[Dict[str, Any]] = None, lf_form: Optional[Dict[str, Any]] = None, auxiliary_quantities: Optional[SecondaryStorage] = None, truth: Dict[str, float] = {}, graph: Optional[Dict[str, Any]] = None, theta=None, phi=None, pop_synth: Optional[Dict[str, Any]] = None, probability: Optional[ndarray] = None)

Bases: object

__init__(luminosities: Union[_SupportsArray[dtype], _NestedSequence[_SupportsArray[dtype]], bool, int, float, complex, str, bytes, _NestedSequence[Union[bool, int, float, complex, str, bytes]]], distances: Union[_SupportsArray[dtype], _NestedSequence[_SupportsArray[dtype]], bool, int, float, complex, str, bytes, _NestedSequence[Union[bool, int, float, complex, str, bytes]]], known_distances: Union[_SupportsArray[dtype], _NestedSequence[_SupportsArray[dtype]], bool, int, float, complex, str, bytes, _NestedSequence[Union[bool, int, float, complex, str, bytes]]], known_distance_idx: Union[_SupportsArray[dtype], _NestedSequence[_SupportsArray[dtype]], bool, int, float, complex, str, bytes, _NestedSequence[Union[bool, int, float, complex, str, bytes]]], unknown_distance_idx: Union[_SupportsArray[dtype], _NestedSequence[_SupportsArray[dtype]], bool, int, float, complex, str, bytes, _NestedSequence[Union[bool, int, float, complex, str, bytes]]], fluxes: Union[_SupportsArray[dtype], _NestedSequence[_SupportsArray[dtype]], bool, int, float, complex, str, bytes, _NestedSequence[Union[bool, int, float, complex, str, bytes]]], flux_obs: Union[_SupportsArray[dtype], _NestedSequence[_SupportsArray[dtype]], bool, int, float, complex, str, bytes, _NestedSequence[Union[bool, int, float, complex, str, bytes]]], selection: Union[_SupportsArray[dtype], _NestedSequence[_SupportsArray[dtype]], bool, int, float, complex, str, bytes, _NestedSequence[Union[bool, int, float, complex, str, bytes]]], flux_sigma: float, r_max: float, n_model: int, lf_params: Dict[str, Any], spatial_params: Optional[Dict[str, Any]] = None, model_spaces: Optional[Union[_SupportsArray[dtype], _NestedSequence[_SupportsArray[dtype]], bool, int, float, complex, str, bytes, _NestedSequence[Union[bool, int, float, complex, str, bytes]]]] = None, seed: int = 1234, name: Optional[str] = None, spatial_form: Optional[Dict[str, Any]] = None, lf_form: Optional[Dict[str, Any]] = None, auxiliary_quantities: Optional[SecondaryStorage] = None, truth: Dict[str, float] = {}, graph: Optional[Dict[str, Any]] = None, theta=None, phi=None, pop_synth: Optional[Dict[str, Any]] = None, probability: Optional[ndarray] = None) → None

A population container for all the properties of the population.

Parameters

• luminosities (ArrayLike) – The luminosities

• distances (ArrayLike) – The distances

• known_distances (ArrayLike) – The known distances

• known_distance_idx (ArrayLike) – The index of the known distances

• unknown_distance_idx (ArrayLike) – The index of the unknown distances

• fluxes (ArrayLike) – The latent fluxes

• flux_obs (ArrayLike) – The observed fluxes

• selection (ArrayLike) – The selection vector

• flux_sigma (float) – The uncertainty on the observed flux

• r_max (float) – The maximum distance of the survey

• n_model (int) – Number of models

• lf_params (Dict[str, Any]) – Luminosity function parameters

• spatial_params (Optional[Dict[str, Any]]) – Spatial distribution parameters

• model_spaces (ArrayLike) – Model spaces

• seed (int) – Random seed

• name (str) – Name of the population

• spatial_form (Optional[Dict[str, Any]]) – Form of the spatial distribution

• lf_form (Optional[Dict[str, Any]]) – Form of the luminosity function

• auxiliary_quantities (Optional[Dict[str, Any]]) – Dict of auxiliary quantities

• truth (Dict[str, float]) – Dict of true values

• graph (Optional[Dict[str, Any]]) – Graph of generative model

• theta – Theta

• phi – Phi

• pop_synth (Optional[Dict[str, Any]]) – Population synth

property graph

The networkx graph of the population

Returns

property probability: Optional[SimulatedVariable]

property pop_synth: Dict[str, Any]

Dictionary population synth used to create this population

property truth

The simulated truth parameters

property flux_sigma: float

The simulated flux sigma

property theta: SimulatedVariable

The polar angle of the objects

property phi: SimulatedVariable

The phi angle of the objects

property dec: SimulatedVariable

The declination of the objects

property ra: SimulatedVariable

The right ascension of the objects

property luminosities: SimulatedVariable

the luminosities of the objects

Returns

property luminosities_latent: ndarray

The true luminosities of the objects. These are always latent as one cannot directly observe them.

property distances: SimulatedVariable

The distances to the objects

property known_distances: ndarray

The observed distances

property selection: ndarray

The selection vector

property fluxes: SimulatedVariable

the fluxes of the objects

Returns

property fluxes_latent: ndarray

The latent fluxes of the objects

property fluxes_observed: ndarray

All of the observed fluxes, i.e., scattered with error

property selected_fluxes_observed: ndarray

The selected obs fluxes

property selected_fluxes_latent: ndarray

The selected latent fluxes

property selected_distances: ndarray

The selected distances. Note, this is different than the KNOWN distances.

property hidden_fluxes_observed: ndarray

The observed fluxes that are hidden by the selection

property hidden_distances: ndarray

The distances that are hidden by the selection

property hidden_fluxes_latent: ndarray

The latent fluxes that are hidden by the selection

property hard_cut: bool

property distance_probability: float

property luminosity_parameters

property n_objects: int

The number of objects in the population

property n_detections: int

The number of DETECTED objects in the population

property n_non_detections: int

The number of NON-DETECTED objects in the population

property has_detections: bool

If the population has detections

property spatial_parameters

spatial parameters

Returns

to_stan_data() → dict

Create Stan input

writeto(file_name: str) → None

Write population to an HDF5 file

Parameters

file_name (str) – Name of the file

addto(file_name: str, group_name: str) → None

Write population to a group in an existing HDF5 file.

Parameters

• file_name (str) – Name of the file

• group_name (str) – Name of the group

_writeto(f)

Write to an HDF5 file or group.

Parameters

f – h5py file or group handle

classmethod from_file(file_name: str)

Load a population from a file.

Parameters

file_name (str) – Name of the file

classmethod from_group(file_name: str, group_name: str)

Load a population from a group in a file.

Parameters

• file_name (str) – Name of the file

• group_name (str) – Name of the group

classmethod _loadfrom(f)

Load from and HDF5 file or group.

Parameters

f – h5py file or group handle

to_sub_population(observed: bool = True) → Population

Create a population that is down selected from either the observed or unobserved population

Parameters

observed (bool) – Extract the observed or unobserved object

Returns

A new population object

Return type

Population

display()

Display the simulation parameters.

display_true_fluxes(ax=None, flux_color='#8F2727', **kwargs)

Display the fluxes.

Parameters

• ax – Axis on which to plot

• flux_color – Color of fluxes

display_obs_fluxes(ax=None, flux_color='#8F2727', **kwargs)

Display the observed fluxes.

Parameters

• ax – Axis on which to plot

• flux_color – Color of fluxes

display_fluxes(ax=None, true_color='#dec3c3', obs_color='#8F2727', arrow_color='k', with_arrows=True, **kwargs)

Display the fluxes.

Parameters

• ax – Axis on which to plot

• true_color – Color of true values

• obs_color – Color of obs values

• arrow_color – Color of arrows

• with_arrows – If True, display arrows

display_luminosities(ax=None, true_color='#dec3c3', obs_color='#8F2727', **kwargs)

Display the luminosities

Parameters

• ax – Axis on which to plot

• true_color – Color of true values

• obs_color – Color of obs values

display_obs_fluxes_sphere(cmap='magma', distance_transform=None, use_log=False, background_color='white', show=True, **kwargs)

display_hidden_fluxes_sphere(cmap='magma', distance_transform=None, use_log=False, background_color='white', show=True, **kwargs)

display_flux_sphere(seen_cmap='Reds', unseen_cmap='Blues', distance_transform=None, use_log=False, background_color='white', **kwargs)

display_distances(ax=None)

Display the distances

Parameters

ax – Axis on which to plot

class popsynth.PopulationSynth(spatial_distribution: SpatialDistribution, luminosity_distribution: Optional[LuminosityDistribution] = None, seed: int = 1234)

Bases: object

__init__(spatial_distribution: SpatialDistribution, luminosity_distribution: Optional[LuminosityDistribution] = None, seed: int = 1234)

Basic and generic population synth. One specifies the spatial and luminosity distribution OR derived luminosity distribution and everything is setup.

Parameters

• spatial_distribution (SpatialDistribution) – The spatial distribution to sample locations from

• luminosity_distribution (LuminosityDistribution) – The optional luminosity distribution

• seed (int) – Random seed

clean(reset: bool = False)

Clean the auxiliary samplers, selections, etc from the population synth

Parameters

reset (bool) – If True, reset any attached distributions and samplers

write_to(file_name: str) → None

Write the population synth to a YAML file.

Parameters

file_name (str) – the file name of the output YAML

to_dict() → Dict[str, Any]

Convert the population synth to a dictionary

Returns

Popsynth dict

Return type

Dict[str, Any]

classmethod from_dict(input: Dict[str, Any]) → PopulationSynth

Build a PopulationSynth object from a dictionary

Parameters

input (Dict[str, Any]) – the dictionary from which to build

Returns

Popsynth object

Return type

PopulationSynth

classmethod from_file(file_name: str) → PopulationSynth

read the population in from a yaml file

Parameters

file_name – the file name of the population synth

property spatial_distribution: SpatialDistribution

property luminosity_distribution: Optional[LuminosityDistribution]

add_model_space(name, start, stop, log=True)

Add a model space for stan generated quantities

Parameters

• name – Name that Stan will use

• start – Start of the grid

• stop – Stop of the grid

• log – Use log10 or not

add_auxiliary_sampler(auxiliary_sampler: Union[DerivedLumAuxSampler, AuxiliarySampler])

Add an auxiliary sampler or derived luminosity sampler to the population synth.

Parameters

auxiliary_sampler (Union[DerivedLumAuxSampler, AuxiliarySampler]) – The auxiliary_sampler

add_observed_quantity(auxiliary_sampler: Union[DerivedLumAuxSampler, AuxiliarySampler])

Add an auxiliary sampler or derived luminosity sampler to the population synth

Parameters

auxiliary_sampler (Union[DerivedLumAuxSampler, AuxiliarySampler]) – The auxiliary_sampler

set_distance_selection(selector: SelectionProbability) → None

Set the selection type for the distance.

Parameters

selector (SelectionProbability) – The selector

set_flux_selection(selector: SelectionProbability) → None

Set the selection type for the flux

Parameters

selector (SelectionProbability) – The selector

add_spatial_selector(spatial_selector: SelectionProbability) → None

Add a spatial selector into the mix

Parameters

spatial_selector (SelectionProbability) – The spatial selector

property name: str

draw_log10_fobs(f, f_sigma, size=1) → ndarray

Draw the log10 of the the fluxes.

draw_log_fobs(f, f_sigma, size=1) → ndarray

Draw the log10 of the the fluxes.

draw_survey(flux_sigma: Optional[float] = None, log10_flux_draw: bool = True, n_samples: Optional[int] = None, normalize: bool = False) → Population

Draw the total survey and return a Population object.

This will sample all attached distributions and apply selection functions.

If a value of flux_sigma is given, the log10 observed fluxes are sampled with measurement error.

Parameters

• flux_sigma (Optional[float]) – The homoskedastic sigma for the flux in log10 space

• log10_flux_draw (bool) – if True, fluxes are drawn in log space

Returns

a Population object

Return type

Population

display() → None

Display the simulation parameters.

property graph

_build_graph()

Builds the graph for all the samplers.