The `lightcone` Module

The SimIM lightcone module is designed to construct light cones - tables of galaxies with angular position and redshift and redshift dependent galaxy properties comparable to real astrophysical surveys - out of simulation cubes. The module has two main components lightcone.LCMaker which generates new light cone files, and lightcone.LCHandler which provides a handler instance for interacting with and analyzing the lightcones built by lightcone.LCMaker.

Making Light Cones

Light cones can inherit any property associated with their parent simulation, except for those relating to position, which are transformed into coordinates within the lightcone.

class simim.lightcone.LCMaker(sim, name, openangle, aspect=1, redshift_min=0, redshift_max='max', minimum_mass=0, mode='box', overwrite='check')

class for handling lightcone generation.

Methods

`add_pos_properties`(*keys)	Select additional properties to include in the light cone for properties with position information (ie velocity).
`add_properties`(*keys)	Select additional properties to include in the light cone.
`build_lightcones`([n, rng])	Code to construct a specified number of light cones
`get_LCIterator`([in_h_units])	Return a LCIterator object that can be used to iteratively analyse the light cones

Initialize light cone generator.

Specify the simulation and light cone dimensions that will be used for creating light cones. Initializing the LCMaker will not create any light cones. This is done by the LCMaker.build_lightcones method.

Parameters:

simstr: The name of the simulation to be used. The simulation must be supported by simim and downloaded in the simim_resources path
namestr: The name to give to generated light cones. They will be saved in the path [simim_resources]/lightcones/[sim]/[name]/lc_[number].hdf5
openanglefloat: The opening angle of the light cone, specified in degrees. For circular light cones this will be the diameter of the light cone, for square light cones this will be the side length of the box, for rectangular light cones this will be the length of the longer side
aspectfloat beteen 0 and 1, optional: The aspect ratio for the sides of a rectangular box, the long side is determined by openangle and the short side is aspect x openangle
redshift_minfloat, optional: Minimum redshift to include in the lightcone, default is 0
redshift_maxfloat or ‘max’, optional: Maximum redshift to include in the lightcone, default is the maximum redshift of the simulation
minimum_massfloat (optional): the minimum halo mass to include, in Msun/h. Default is 0 (include all halos).
mode{‘box’, ‘circle’}, optional: defines the profile of the light cone - circular or rectangular, default is rectangular (‘box’)
overwrite{‘check’, True, False}

Methods

`add_pos_properties`(*keys)	Select additional properties to include in the light cone for properties with position information (ie velocity).
`add_properties`(*keys)	Select additional properties to include in the light cone.
`build_lightcones`([n, rng])	Code to construct a specified number of light cones
`get_LCIterator`([in_h_units])	Return a LCIterator object that can be used to iteratively analyse the light cones

Returns:

No return

build_lightcones(n=1, rng=Generator(PCG64) at 0x78410A44F680)

Code to construct a specified number of light cones

Parameters:

nint: Number of light cones to make
rngnumpy rng: Random number generator instance used to generate lightcone useful for producing repeatable results.

Returns:

none: Light cones are saved in the lightcones file in the resources folder.

add_pos_properties(*keys)

Select additional properties to include in the light cone for properties with position information (ie velocity).

This will be done for all lightcones in the set.

Parameters:

keysfloat or floats: the keys used to identify fields to include in the light cone (exclude the _x, _y, _z components, ie for velocity give keys=[‘v’] not keys=[‘v_x’,’v_y’,’v_z’])

Returns:

none

add_properties(*keys)

Select additional properties to include in the light cone. Should not be used for properties with position information (ie velocity) which have to be transformed into the correct coordinates. Use add_pos_properties instead.

This will be done for all lightcones in the set.

Parameters:

keysfloat or floats: the keys used to identify fields to add to the light cone

Returns:

none

get_LCIterator(in_h_units=False)

Return a LCIterator object that can be used to iteratively analyse the light cones

Parameters:

in_h_unitsbool: If True, values returned, plotted, etc. by the LCIterator will be in in units including little h. If False, little h dependence will be removed. This can be overridden in most method calls.

The Light Cone Handler

The handler for lightcones is almost entirely analogous to the hander for simulation snapshots, making interfacing with data in “simulation space” and “observer space” fairly similar.

class simim.lightcone.LCHandler(sim, name, number, in_h_units=False)

Class to handle I/O and basic analysis for light cone hdf5 files

This class handles basic operations for accessing and analyzing lightcone data.

The general philosophy of Handlers is to not load actual properties of a halo into memory until they are requested, and to remove them from memory when they are no longer in use (or at least make it convenient to do so).

Methods

`animate`([save, use_all_inds, colorpropname, ...])	Make an animation of the light cone
`delete_property`(*property_names)	Remove a property from the saved file on the disk
`eval_stat`(stat_function, kwargs[, kw_remap, ...])	Evaluate stat_function over the objects in a Handler instance and return the result
`eval_stat_evo`(redshift_bins, stat_function, ...)	Compute the evolution of a statistic over a specified set of redshift bins
`extract_keys`([set])	Get the fields attached to a file
`grid`(*property_names[, restfreq, ...])	Place selected properties into a 3d grid
`has_loaded`(property_name)	Check whether a property has been loaded into memory
`has_property`(property_name)	Check whether a property has been loaded into memory
`hist`(*property_names[, use_all_inds, ...])	Make a histogram of a property
`load_property`(*property_names)	Load a property from file into memory
`make_property`(property[, rename, kw_remap, ...])	Use a galprops.prop instance to evaluate a new property
`plot`(xname, *ynames[, use_all_inds, save, ...])	Make a scatter plot of two properties
`return_property`(property_name[, ...])	Load a property from file and return
`set_in_h_units`(in_h_units)	Globally set whether units are interpreted to be in little h units
`set_property_range`([property_name, pmin, ...])	Set a range in a given property to be the active indices.
`unload_property`(*property_names)	Remove a property from memory (does not erase from file on disk)
`volume`([redshift_min, redshift_max, shape, ...])	Compute the comoving volume of the light cone
`write_property`(*property_names[, overwrite, ...])	Write a property from object memory onto the saved file on the disk

Initialize Handler for a specified lightcone

This class a generic interface for interacting with data in SimIM’s standardized lightcone format.

Light cones must first be built using simim.lightcone.LCMaker. Lightcones are saved in sets in the SimIM data directory, each set of lightcones can contain one or many individual lightcones, created in a uniform way from a parent simulation. Accessing one of these lightcones in a Handler requires specifying the name of the parent simulation, the name of the lightcone set, and the number of the desired lightcone (indexed starting at 0).

Parameters:

simstr: The name of the simulation from which the lightcone was generated.
namestr: The name of the lightcone set.
numberint: The numeric index of the lightcone within the set
in_h_unitsbool: If True, values will be returned, plotted, etc. in units including little h. If False, little h dependence will be removed. This can be overridden in most method calls.

Methods

`animate`([save, use_all_inds, colorpropname, ...])	Make an animation of the light cone
`delete_property`(*property_names)	Remove a property from the saved file on the disk
`eval_stat`(stat_function, kwargs[, kw_remap, ...])	Evaluate stat_function over the objects in a Handler instance and return the result
`eval_stat_evo`(redshift_bins, stat_function, ...)	Compute the evolution of a statistic over a specified set of redshift bins
`extract_keys`([set])	Get the fields attached to a file
`grid`(*property_names[, restfreq, ...])	Place selected properties into a 3d grid
`has_loaded`(property_name)	Check whether a property has been loaded into memory
`has_property`(property_name)	Check whether a property has been loaded into memory
`hist`(*property_names[, use_all_inds, ...])	Make a histogram of a property
`load_property`(*property_names)	Load a property from file into memory
`make_property`(property[, rename, kw_remap, ...])	Use a galprops.prop instance to evaluate a new property
`plot`(xname, *ynames[, use_all_inds, save, ...])	Make a scatter plot of two properties
`return_property`(property_name[, ...])	Load a property from file and return
`set_in_h_units`(in_h_units)	Globally set whether units are interpreted to be in little h units
`set_property_range`([property_name, pmin, ...])	Set a range in a given property to be the active indices.
`unload_property`(*property_names)	Remove a property from memory (does not erase from file on disk)
`volume`([redshift_min, redshift_max, shape, ...])	Compute the comoving volume of the light cone
`write_property`(*property_names[, overwrite, ...])	Write a property from object memory onto the saved file on the disk

volume(redshift_min=None, redshift_max=None, shape=None, open_angle=None, aspect_ratio=None, in_h_units=None)

Compute the comoving volume of the light cone

Parameters:

redshift_min, redshift_maxfloat, optional: The minimum/maximum redshift to consider - the minimum/maximum redshift of the lightcone by default
open_anglefloat, optional: The opening angle of the lightcone - by default matches the lightcone
aspect_ratiofloat, optional: The aspect ratio of the box sides (for square lightcones) - by default matches the lightcone
shape‘box’, ‘circle’, optional: The shape of the box - by default matches the lightcone
in_h_unitsbool (default is determined by self.default_in_h_units): If True, values will be returned in units including little h. If False, little h dependence will be removed. Defaults to whatever is set globally for the Handler instance.

Returns:

volumefloat: The volume of the lightcone in comoving Mpc^3

eval_stat_evo(redshift_bins, stat_function, kwargs, kw_remap={}, other_kws={}, zmin_kw=False, zmax_kw=False, volume_kw=False, give_args_in_h_units=None): Compute the evolution of a statistic over a specified set of redshift bins

grid(*property_names, restfreq=None, in_h_units=None, use_all_inds=False, res=None, ralim=None, declim=None, zlim=None, norm=None)

Place selected properties into a 3d grid

Uses the properties of the array to construct a position (ra,dec,redshift)-value (property_names) grid. Only required argument is a valid property name or names. Additional arguments can specify the limits and resolution of the grid. Passing a line rest frequency to restfreq will cause the grid to be constructed in terms of the corresponding observed frequencies instead of redshift.

Parameters:

property_namesstr: The name or names of properties in the Handler instance
restfreqfloat: A rest frequency to use for converting the third axis from redshift to frequency. The returned axis will be constructed as restfreq/(1+z)
in_h_unitsbool (default is determined by self.default_in_h_units): If True, positions and property values fed to the gridder will be in units including little h. If False, little h dependence will be removed. Defaults to whatever is set globally for the Handler instance.
use_all_indsbool, default=False: If True function all halos will be gridded, otherwise only active halos will be included.
resfloat, optional: The resolution for the grid in Mpc (if in_h_units==False) or Mpc/h (if in_h_units==True). If no value is specified, it will default to 1/100th of the box edge length
ralim, decylim, zlimtuples, optional: Tuples containing minimum and maximum values of the grid along the x, y, and z axes, in units of Mpc (if in_h_units==False) or Mpc/h (if in_h_units==True). If no values are specified the defaults are (0, box edge length).
normNone, float: Apply a normalization to the gridded values. If a float is given each cell will multiplied by the float

Returns:

gridsimim.map.grid instance: The gridded properties

animate(save=None, use_all_inds=False, colorpropname='mass', colorscale='log', sizepropname='mass', sizescale='log', in_h_units=None)

Make an animation of the light cone

Parameters:

use_all_indsbool, optional: If True values will be assigned for all halos, otherwise only active halos will be evaluated, and others will be assigned nan. Default is False.
savestr, optional: If specified, the plot will be saved to the given location
colorpropnamestr: Name of the property used to determine marker color for each galaxy, default is ‘mass’
colorpropscale‘log’ or ‘linear’: Determines how the colorbar will be applied. Default is ‘log’
in_h_unitsbool (default is determined by self.default_in_h_units): If True, values will be plotted in units including little h. If False, little h dependence will be removed. Defaults to whatever is set globally for the Handler instance.

Returns:

None

delete_property(*property_names)

Remove a property from the saved file on the disk

Parameters:

property_namesstr: The name of the field to be written, can give multiple

Returns:

None

eval_stat(stat_function, kwargs, kw_remap={}, other_kws={}, use_all_inds=False, give_args_in_h_units=None)

Evaluate stat_function over the objects in a Handler instance and return the result

This can be used to evaluate any function of the the properties contained in the simulation, but is generally envisioned as a way to compute ensemble statistics (means, luminosity functions, correlations, etc.)

Parameters:

stat_functionfunction: Any function which can be applied to data in a Handler instance
kwargslist: List containing the arguments that must be passed to stat_function
kw_remapdict: Dictionary mapping between function arguments (listed in kwargs) as the keys and the names of Handler properties to feed in as values. E.g. to provide handler property ‘mass’ to stat_function argument ‘a’ one would use kw_remap={‘a’:’mass’}
other_kwsdict, optional: A dictionary of additional keyword arguments passed directly to the stat_function call
use_all_indsbool, default=False: If True function will be computed using all halos, otherwise only active halos will be evaluated.
give_args_in_h_unitsbool (default is determined by self.default_in_h_units): If True, values will be fed to stat_function in units including little h. If False, little h dependence will be removed first. Defaults to whatever is set globally for the Handler instance.

Returns:

vals: The value(s) returned by stat_function

Examples

Compute the total halo mass in a simulation accesed via the variable handler:

>>> handler.eval_stat(np.sum, kwargs=['a'], kw_remap={'a':'mass'})

extract_keys(set='any')

Get the fields attached to a file

Parameters:

set{‘any’,’loaded’,’saved’,’generated’}: What type of keys to return, default is all

Returns:

keys: The fields associated with the lightcone

has_loaded(property_name)

Check whether a property has been loaded into memory

Parameters:

property_namestr: The name of the field to be loaded

Returns:

loadedbool: True if the property is loaded, otherwise, false

has_property(property_name)

Check whether a property has been loaded into memory

Parameters:

property_namestr: The name of the field to be loaded

Returns:

existsbool: True if the property is present, otherwise, false

hist(*property_names, use_all_inds=False, logtransform=False, save=None, axkws={}, plotkws={}, in_h_units=None)

Make a histogram of a property

Parameters:

*property_namesstr: The name(s) of the field(s) to use, multiple fields can be given and will be plotted on the same axes with the same settings
logtransformbool, optional: If set to True, will take the log of the property before making the histogram
use_all_indsbool, optional: If True values will be assigned for all halos, otherwise only active halos will be evaluated, and others will be assigned nan.
savestr, optional: If specified, the plot will be saved to the given location
axkwsdict, optional: A dictionary of keyword args and values that will be fed to ax.set() when creating the plot axes
plotkwsdict, optional: A dictionary of keyword args and values that will be fed to plt.hist() when creating the plot data
in_h_unitsbool (default is determined by self.default_in_h_units): If True, values will be plotted in units including little h. If False, little h dependence will be removed. Defaults to whatever is set globally for the Handler instance.

Returns:

None

load_property(*property_names)

Load a property from file into memory

Parameters:

property_namesstr: The name of the field to be loaded, can give multiple

Returns:

none

make_property(property, rename=None, kw_remap={}, other_kws={}, overwrite=False, use_all_inds=False, write_to_disk=False, overwrite_to_disk=False, dtype_to_disk=None, unload_to_disk=False)

Use a galprops.prop instance to evaluate a new property

Parameters:

propertygalprops.prop instance: The galprops.property instance containing the property information and generating function
renamelist, optional: List of names specifying how to rename the property from the name specified in the galprops.prop instance
kw_remapdict, optional: A dictinary remaping kwargs of the property generating function to different properties of the lightcone. By default if the function calls for kwarg ‘x’ it will be evaluated on simulation property ‘x’, but passing the dictionary {‘x’:’y’} will result in the function being evaluated on simulation property ‘y’.
other_kwsdict, optional: A dictionary of additional keyword arguments passed directly to the property.prop_function call
overwritebool, optional: Default is False. If a property name is already in use and overwrite is False, an error will be raised. Otherwise the property will be overwritten.
use_all_indsbool: If True values will be assigned for all halos, otherwise only active halos will be evaluated, and others will be assigned nan.
write_to_diskbool: Default is False. If True, write assessed property to disk (note use_all_inds must be True)
overwrite_to_diskbool: Default is False. If a property name is already in use on disk and overwrite_to_disk is False, an error will be raised when trying to write to disk. Otherwise the property will be overwritten. Be careful if you set this to True.
dtype_to_diskNone or data type: Specify the data type to use for saving writing the data - useful for converting to lower precision floats for using less storage
unload_to_diskbool: Default is False. If True, will unload properties after writing them to disk.

Returns:

None

plot(xname, *ynames, use_all_inds=False, save=None, axkws={}, plotkws={}, in_h_units=None)

Make a scatter plot of two properties

Parameters:

xnamestr: The name of the field to use as the x-value
*ynamesstr: The name(s) of the field(s) to use as the y-value. Multiple fields can be given and will be plotted on the same axes against a single x vale
use_all_indsbool or ‘compare’, optional: If True values will be assigned for all halos, otherwise only active halos will be evaluated, and others will be assigned nan. If ‘compare’, both sets of indices will be plotted to allow easy comparison.
savestr, optional: If specified, the plot will be saved to the given location
axkwsdict, optional: A dictionary of keyword args and values that will be fed to ax.set() when creating the plot axes
plotkwsdict, optional: A dictionary of keyword args and values that will be fed to plt.plot() when creating the plot data
in_h_unitsbool (default is determined by self.default_in_h_units): If True, values will be plotted in units including little h. If False, little h dependence will be removed. Defaults to whatever is set globally for the Handler instance.

Returns:

None

return_property(property_name, use_all_inds=False, in_h_units=None)

Load a property from file and return

Parameters:

property_namestr: The name of the field to be loaded
use_all_indsbool: If True values will be returned for all halos, otherwise only active halos will be returned. Default is False, but by default all halos are active
in_h_unitsbool (default is determined by self.default_in_h_units): If True, values will be returned in units including little h. If False, little h dependence will be removed. Defaults to whatever is set globally for the Handler instance.

Returns:

property_valuesarray: Values of the requested property

set_in_h_units(in_h_units)

Globally set whether units are interpreted to be in little h units

Changes the default way units are processed

Parameters:

in_h_unitsbool: If True, values will, by default, be returned in units including little h. If False, little h dependence will be removed.

set_property_range(property_name=None, pmin=-inf, pmax=inf, reset=True, in_h_units=None)

Set a range in a given property to be the active indices. If no arguments are passed, this resets the active indices to all halos

Parameters:

property_namestr: The name of the field to use
pminfloat: The minimum value of the property to bracket the selected range.
pmaxfloat: The maximum value of the property to bracket the selected range.
resetbool, optional: If True, the active indices will be those selected between pmin and pmax. If False, the active indices will be that satisfy pmin<=p<=pmax and which were previously in the active indices (ie this allows selection over multiple properties.)
in_h_unitsbool (default is determined by self.default_in_h_units): If True, pmin and pmax will be taken to have units including little h, otherwise, they will be assumed to have units with no h dependence (and have the correct dependency applied before setting cuts for parameters where the stored catalog values are in h units). Defaults to whatever is set globally for the Handler instance.

Returns:

None

unload_property(*property_names)

Remove a property from memory (does not erase from file on disk)

Parameters:

property_namesstr: The name of the field to be loaded, can give multiple

Returns:

none

write_property(*property_names, overwrite=False, dtype=None)

Write a property from object memory onto the saved file on the disk

Parameters:

property_namesstr: The name of the field to be written, can specify multiple
overwritebool, optional: Default is False. If a property name is already in use and overwrite is False, an error will be raised. Otherwise the property will be overwritten. Be careful if you set this to True.
dtypeNone or data type: Specify the data type to use for saving writing the data - useful for converting to lower precision floats for using less storage

Returns:

None

The lightcone Module

Making Light Cones

The Light Cone Handler

The `lightcone` Module