popsynth package

Subpackages

Submodules

popsynth.auxiliary_sampler module

class popsynth.auxiliary_sampler.SecondaryContainer(name: str, true_values: Union[_SupportsArray[dtype], _NestedSequence[_SupportsArray[dtype]], bool, int, float, complex, str, bytes, _NestedSequence[Union[bool, int, float, complex, str, bytes]]], obs_values: 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]]], probability: Union[_SupportsArray[dtype], _NestedSequence[_SupportsArray[dtype]], bool, int, float, complex, str, bytes, _NestedSequence[Union[bool, int, float, complex, str, bytes]]])[source]

Bases: object

__init__(name: str, true_values: Union[_SupportsArray[dtype], _NestedSequence[_SupportsArray[dtype]], bool, int, float, complex, str, bytes, _NestedSequence[Union[bool, int, float, complex, str, bytes]]], obs_values: 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]]], probability: Union[_SupportsArray[dtype], _NestedSequence[_SupportsArray[dtype]], bool, int, float, complex, str, bytes, _NestedSequence[Union[bool, int, float, complex, str, bytes]]]) → None[source]

A container for secondary properties that adds dict and dictionary access

Parameters

  • name (str) – the name of the secondary

  • true_values (ArrayLike) –

  • obs_values (ArrayLike) –

  • selection (ArrayLike) –

  • probability (ArrayLike) –

Returns

Returns

property name: str
property true_values: Union[_SupportsArray[dtype], _NestedSequence[_SupportsArray[dtype]], bool, int, float, complex, str, bytes, _NestedSequence[Union[bool, int, float, complex, str, bytes]]]

The true (latent) values of the sampler

Returns

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

The observed values of the sampler

Returns

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

The the slection of the values

Returns

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

The the probability of the draws

Returns

class popsynth.auxiliary_sampler.SecondaryStorage[source]

Bases: DotMap

__init__()[source]

A container for secondary samplers

Returns

add_secondary(secondary_values: SecondaryContainer) → None[source]

Add on a new secondary

Parameters

secondary_values (SecondaryContainer) –

Returns

class popsynth.auxiliary_sampler.AuxiliaryParameter(default: Optional[float] = None, vmin: Optional[float] = None, vmax: Optional[float] = None, free: bool = True, is_normalization: bool = False)[source]

Bases: Parameter

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

Bases: object

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

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()[source]
set_luminosity(luminosity: Union[_SupportsArray[dtype], _NestedSequence[_SupportsArray[dtype]], bool, int, float, complex, str, bytes, _NestedSequence[Union[bool, int, float, complex, str, bytes]]]) → None[source]

Set the luminosity values.

Parameters

luminosity (ArrayLike) – Luminosity

set_spatial_values(value: SpatialContainer) → None[source]

Set the spatial values.

Parameters

value (SpatialContainer) – Spatial values

set_selection_probability(selector: SelectionProbability) → None[source]

Set a selection probabilty for this sampler.

Parameters

selector (SelectionProbability) – A selection probability oobject

Returns

_apply_selection() → None[source]

Default selection if none is specfied in child class.

set_secondary_sampler(sampler: AuxiliarySampler) → None[source]

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)[source]

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

Parameters

size (int) – The number of samples to draw

property probability: ndarray
reset()[source]

Reset all the selections.

make_secondary(parent_name: str) → None[source]

sets this sampler as secondary for book keeping

Parameters

parent_name (str) –

Returns

get_secondary_properties(graph=None, primary=None, spatial_distribution=None) → SecondaryStorage[source]

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][source]

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)[source]
observation_sampler(size: int = 1) → ndarray[source]
class popsynth.auxiliary_sampler.NonObservedAuxSampler(name: str, uses_distance: bool = False, uses_luminosity: bool = False)[source]

Bases: AuxiliarySampler

__init__(name: str, uses_distance: bool = False, uses_luminosity: bool = False)[source]

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

class popsynth.auxiliary_sampler.DerivedLumAuxSampler(name: str, uses_distance: bool = False)[source]

Bases: AuxiliarySampler

__init__(name: str, uses_distance: bool = False)[source]

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()[source]

popsynth.distribution module

class popsynth.distribution.DistributionParameter(default: Optional[float] = None, vmin: Optional[float] = None, vmax: Optional[float] = None, free: bool = True, is_normalization: bool = False)[source]

Bases: Parameter

class popsynth.distribution.Distribution(name: str, seed: int, form: str)[source]

Bases: object

__init__(name: str, seed: int, form: str) → None[source]

A distribution base class.

Parameters

  • name (str) – Name of the distribution

  • seed (int) – Random seed

  • form (str) – the LaTeX form

property normalization_parameter: Optional[float]
property name: str

The name of the distribution

Returns

property form: str

The latex form of the distribution

Returns

property params: Dict[str, float]

The parameters of the distribution

property truth: Dict[str, float]

value of the parameters used to simulate

property probability: ndarray
display()[source]

use ipython pretty display to display the functions

Returns

class popsynth.distribution.SpatialContainer(distance: Union[_SupportsArray[dtype], _NestedSequence[_SupportsArray[dtype]], bool, int, float, complex, str, bytes, _NestedSequence[Union[bool, int, float, complex, str, bytes]]], theta: Union[_SupportsArray[dtype], _NestedSequence[_SupportsArray[dtype]], bool, int, float, complex, str, bytes, _NestedSequence[Union[bool, int, float, complex, str, bytes]]], phi: Union[_SupportsArray[dtype], _NestedSequence[_SupportsArray[dtype]], bool, int, float, complex, str, bytes, _NestedSequence[Union[bool, int, float, complex, str, bytes]]])[source]

Bases: object

Container for 3D spatial values.

distance: Union[_SupportsArray[dtype], _NestedSequence[_SupportsArray[dtype]], bool, int, float, complex, str, bytes, _NestedSequence[Union[bool, int, float, complex, str, bytes]]]
theta: Union[_SupportsArray[dtype], _NestedSequence[_SupportsArray[dtype]], bool, int, float, complex, str, bytes, _NestedSequence[Union[bool, int, float, complex, str, bytes]]]
phi: Union[_SupportsArray[dtype], _NestedSequence[_SupportsArray[dtype]], bool, int, float, complex, str, bytes, _NestedSequence[Union[bool, int, float, complex, str, bytes]]]
property dec: ndarray
property ra: ndarray
__init__(distance: Union[_SupportsArray[dtype], _NestedSequence[_SupportsArray[dtype]], bool, int, float, complex, str, bytes, _NestedSequence[Union[bool, int, float, complex, str, bytes]]], theta: Union[_SupportsArray[dtype], _NestedSequence[_SupportsArray[dtype]], bool, int, float, complex, str, bytes, _NestedSequence[Union[bool, int, float, complex, str, bytes]]], phi: Union[_SupportsArray[dtype], _NestedSequence[_SupportsArray[dtype]], bool, int, float, complex, str, bytes, _NestedSequence[Union[bool, int, float, complex, str, bytes]]]) → None
class popsynth.distribution.SpatialDistribution(name: str, seed: int, form: Optional[str] = None)[source]

Bases: Distribution

r_max
__init__(name: str, seed: int, form: Optional[str] = None)[source]

A base class for spatial distributions, such as redshift distributions.

Parameters

  • name (str) – Name of the distribution

  • seed (int) – Random seed

  • form (Union[str, None]) – the LaTeX form

abstract differential_volume(distance)[source]

The differential volume

Parameters

distance – Distance

abstract dNdV(distance)[source]

The differential number of objects per volume element

Parameters

distance –

Returns

time_adjustment(distance)[source]

The time adjustment

Parameters

distance – Distance

abstract transform(flux, distance)[source]

The transform from luminosity to flux for the

Parameters

  • flux –

  • distance –

Returns

property theta: ndarray

the polar coordinate of the objects

Returns

property phi: ndarray

the longitudinal coordinate fo the objects

Returns

property dec: ndarray

The declination of the objects

Returns

property ra: ndarray

the right acension of the objects

Returns

property distances: ndarray

the distances to the objects

Returns

property spatial_values

All the spatial values of the objects :returns:

draw_sky_positions(size: int) → None[source]

Draw the sky positions of the objects

Parameters

size (int) –

Returns

draw_distance(size: int, normalize: bool = False) → None[source]

Draw the distances from the specified dN/dr model.

Parameters

size (int) – Number of distances to sample

class popsynth.distribution.LuminosityDistribution(name: str, seed: int, form: Optional[str] = None)[source]

Bases: Distribution

__init__(name: str, seed: int, form: Optional[str] = None)[source]

A base class for luminosity distributions.

Parameters

  • name (str) – Name of the distribution

  • seed (int) – Random seed

  • form (Union[str, None]) – the LaTeX form

abstract phi(luminosity)[source]

The functional form of the distribution. not required for sampling :param luminosity: Luminosity

abstract draw_luminosity(size: int) → ndarray[source]

function to draw the luminosity via an alternative method must be implemented in child class

Parameters

size –

Returns

compute_probability(L: ndarray) → None[source]

popsynth.population module

class popsynth.population.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)[source]

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[source]

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[source]

Create Stan input

writeto(file_name: str) → None[source]

Write population to an HDF5 file

Parameters

file_name (str) – Name of the file

addto(file_name: str, group_name: str) → None[source]

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)[source]

Write to an HDF5 file or group.

Parameters

f – h5py file or group handle

classmethod from_file(file_name: str)[source]

Load a population from a file.

Parameters

file_name (str) – Name of the file

classmethod from_group(file_name: str, group_name: str)[source]

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)[source]

Load from and HDF5 file or group.

Parameters

f – h5py file or group handle

to_sub_population(observed: bool = True) → Population[source]

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()[source]

Display the simulation parameters.

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

Display the fluxes.

Parameters

  • ax – Axis on which to plot

  • flux_color – Color of fluxes

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

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)[source]

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)[source]

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)[source]
display_hidden_fluxes_sphere(cmap='magma', distance_transform=None, use_log=False, background_color='white', show=True, **kwargs)[source]
display_flux_sphere(seen_cmap='Reds', unseen_cmap='Blues', distance_transform=None, use_log=False, background_color='white', **kwargs)[source]
display_distances(ax=None)[source]

Display the distances

Parameters

ax – Axis on which to plot

popsynth.population_synth module

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

Bases: object

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

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)[source]

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[source]

Write the population synth to a YAML file.

Parameters

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

to_dict() → Dict[str, Any][source]

Convert the population synth to a dictionary

Returns

Popsynth dict

Return type

Dict[str, Any]

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

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[source]

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)[source]

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])[source]

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])[source]

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[source]

Set the selection type for the distance.

Parameters

selector (SelectionProbability) – The selector

set_flux_selection(selector: SelectionProbability) → None[source]

Set the selection type for the flux

Parameters

selector (SelectionProbability) – The selector

add_spatial_selector(spatial_selector: SelectionProbability) → None[source]

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[source]

Draw the log10 of the the fluxes.

draw_log_fobs(f, f_sigma, size=1) → ndarray[source]

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[source]

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[source]

Display the simulation parameters.

property graph
_build_graph()[source]

Builds the graph for all the samplers.

popsynth.simulated_variable module

class popsynth.simulated_variable.SimulatedVariable(observed_values: ndarray, latent_values: ndarray, selection: ndarray)[source]

Bases: ndarray

SimulatedVariables hold the observed and latent values from a population synth variable as well as its selection.

The array displays as the observed values. The latent values can be accessed with x.latent

Subsets of selected and non-selected values can be accessed:

x.selected x.non_selected

which return a SimulatedVariable that is a subset of the values.

Math operations applied to the object will be applied to the observed and latent values.

property latent: ndarray

The latent values simulated which are unobscured by measurement error

Returns

property selected: SimulatedVariable

returns the latent and observed values that were selected as a new SimulatedVariable

property non_selected: SimulatedVariable

returns the latent and observed values that were selected as a new SimulatedVariable

Module contents

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

Bases: object

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

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()[source]
set_luminosity(luminosity: Union[_SupportsArray[dtype], _NestedSequence[_SupportsArray[dtype]], bool, int, float, complex, str, bytes, _NestedSequence[Union[bool, int, float, complex, str, bytes]]]) → None[source]

Set the luminosity values.

Parameters

luminosity (ArrayLike) – Luminosity

set_spatial_values(value: SpatialContainer) → None[source]

Set the spatial values.

Parameters

value (SpatialContainer) – Spatial values

set_selection_probability(selector: SelectionProbability) → None[source]

Set a selection probabilty for this sampler.

Parameters

selector (SelectionProbability) – A selection probability oobject

Returns

_apply_selection() → None[source]

Default selection if none is specfied in child class.

set_secondary_sampler(sampler: AuxiliarySampler) → None[source]

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)[source]

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

Parameters

size (int) – The number of samples to draw

property probability: ndarray
reset()[source]

Reset all the selections.

make_secondary(parent_name: str) → None[source]

sets this sampler as secondary for book keeping

Parameters

parent_name (str) –

Returns

get_secondary_properties(graph=None, primary=None, spatial_distribution=None) → SecondaryStorage[source]

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][source]

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)[source]
observation_sampler(size: int = 1) → ndarray[source]
class popsynth.DerivedLumAuxSampler(name: str, uses_distance: bool = False)[source]

Bases: AuxiliarySampler

__init__(name: str, uses_distance: bool = False)[source]

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()[source]
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)[source]

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[source]

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[source]

Create Stan input

writeto(file_name: str) → None[source]

Write population to an HDF5 file

Parameters

file_name (str) – Name of the file

addto(file_name: str, group_name: str) → None[source]

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)[source]

Write to an HDF5 file or group.

Parameters

f – h5py file or group handle

classmethod from_file(file_name: str)[source]

Load a population from a file.

Parameters

file_name (str) – Name of the file

classmethod from_group(file_name: str, group_name: str)[source]

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)[source]

Load from and HDF5 file or group.

Parameters

f – h5py file or group handle

to_sub_population(observed: bool = True) → Population[source]

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()[source]

Display the simulation parameters.

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

Display the fluxes.

Parameters

  • ax – Axis on which to plot

  • flux_color – Color of fluxes

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

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)[source]

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)[source]

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)[source]
display_hidden_fluxes_sphere(cmap='magma', distance_transform=None, use_log=False, background_color='white', show=True, **kwargs)[source]
display_flux_sphere(seen_cmap='Reds', unseen_cmap='Blues', distance_transform=None, use_log=False, background_color='white', **kwargs)[source]
display_distances(ax=None)[source]

Display the distances

Parameters

ax – Axis on which to plot

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

Bases: object

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

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)[source]

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[source]

Write the population synth to a YAML file.

Parameters

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

to_dict() → Dict[str, Any][source]

Convert the population synth to a dictionary

Returns

Popsynth dict

Return type

Dict[str, Any]

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

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[source]

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)[source]

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])[source]

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])[source]

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[source]

Set the selection type for the distance.

Parameters

selector (SelectionProbability) – The selector

set_flux_selection(selector: SelectionProbability) → None[source]

Set the selection type for the flux

Parameters

selector (SelectionProbability) – The selector

add_spatial_selector(spatial_selector: SelectionProbability) → None[source]

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[source]

Draw the log10 of the the fluxes.

draw_log_fobs(f, f_sigma, size=1) → ndarray[source]

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[source]

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[source]

Display the simulation parameters.

property graph
_build_graph()[source]

Builds the graph for all the samplers.