The `map` Module

The SimIM map module is used for converting the halo/galaxy catalogs contained in simulation and lightcone catalogs into pixelized maps and/or cubes. It also provides a number of convenient utilities for interacting with these cubes once created.

The underlying functionality is implemented in the map.Grid class. A number of sub-classes exist for conveniently generating grids for different types of objects (e.g. maps or data-cubes of astrophysical sources, instrument PSFs).

class simim.map.Grid(n_properties, center_point, side_length, pixel_size, axunits=None, gridunits=None)

Parent class for grids

This class contains most of the functionality, for making and analyzing grids (maps, 3d cubes, spectral cubes, etc). Child classes defined elsewhere should be used to actually initialize and construct the grid.

Methods

`add_from_cat`(positions[, values, new_props, ...])	Add values to the grid
`add_from_pos_plus_array`(positions, values[, ...])	Add values to a grid from a list of positions (dimension N-1), and the values along the final dimension
`add_from_spec_func`(positions, spec_function)	Add spectra to a grid
`add_new_prop`([value])	Add a new property to the grid
`animate`([save, prop_ind, slide_dim, ...])	Animated stepthrough of the grid for visualizing 3d data
`collapse_dimension`(ax[, in_place, weights, mode])	Collapse one or more dimensions of a grid
`convolve`(source[, ax, in_place, pad])	Convolve this Grid with another Grid instance.
`copy`([properties])	Make a copy of this Grid as a new Grid instance
`copy_axes`([n_properties])	Create a new grid instance with the same axes as this one
`crop`(ax[, min, max])	Crop a single grid axis to a specified range of values
`down_sample`(ax, factor[, mode])	Degrade the resolution of the grid along a specified axis by binning groups of pixels.
`fourier_transform`([ax, normalize])	Fourier transform the grid
`init_grid`()	Create the data grid
`pad`(ax, pad[, val])	Pad/unpad the edges of a grid along specified axes
`power_spectrum`([cross_grid, ax, in_place, ...])	Compute the power spectrum of a grid in map space
`sample`(positions[, properties])	Draw samples from the Grid at a list of positions
`save`(path[, compress, overwrite])	Save the grid instance in a .npz file that can be reloaded with the LoadGrid class
`scale_axis`(ax, factor[, axunits, scalecenter])	Rescale an axis or axes of the grid by a constant factor
`spherical_average`([ax, center, shells, ...])	Compute averages in spherical shells along the grid axes
`sum_properties`([properties, in_place])	Sum values of different properties
`visualize`([ax, slice_indices, property, ...])	Quick grid visualizations

Create a Grid instance

This method creates an instance for handling gridded data in arbitrary dimensions. The dimensions and axes of the grid are specified here. The data grid itself is not created in memory until the init_grid method is called.

The constructed grid has N+1 dimensions, where N is the number of “spatial” dimensions of the data, and the final index can be used to access grids for multipl properties.

Parameters:

n_propertiesint >= 1: The number of properties which will be stored in the grid. Note this number can be increased later
center_pointtuple of floats: The center point in each spatial dimension of the grid.
side_lengthfloat or tuple of floats: The length along each spatial dimension of the grid. If a single value is given, all dimensions will be assumed to have the same length. Otherwise the length of the tuple should match the length of the the center_point tuple.
pixel_sizefloat or tuple of floats: The length along each spatial dimension of a single grid cell. If a single value is given, all dimensions will be assumed to have the same length. Otherwise the length of the tuple should match the length of the the center_point tuple. If side_length is not not an an integer multiple of pixel_size the side length will be shortened to give an integer number of pixels.
axunitsstr or tuple of str (optional): A string or tuple of strings specifying the units of the spatial axes.
gridunitsstr or tuple of str (optional): A string or tuple of strings specifying the units of the grid values. A single value can be specified, or one value can be provided for each property, in which case the length of the tuple should equal n_properties.

Methods

`add_from_cat`(positions[, values, new_props, ...])	Add values to the grid
`add_from_pos_plus_array`(positions, values[, ...])	Add values to a grid from a list of positions (dimension N-1), and the values along the final dimension
`add_from_spec_func`(positions, spec_function)	Add spectra to a grid
`add_new_prop`([value])	Add a new property to the grid
`animate`([save, prop_ind, slide_dim, ...])	Animated stepthrough of the grid for visualizing 3d data
`collapse_dimension`(ax[, in_place, weights, mode])	Collapse one or more dimensions of a grid
`convolve`(source[, ax, in_place, pad])	Convolve this Grid with another Grid instance.
`copy`([properties])	Make a copy of this Grid as a new Grid instance
`copy_axes`([n_properties])	Create a new grid instance with the same axes as this one
`crop`(ax[, min, max])	Crop a single grid axis to a specified range of values
`down_sample`(ax, factor[, mode])	Degrade the resolution of the grid along a specified axis by binning groups of pixels.
`fourier_transform`([ax, normalize])	Fourier transform the grid
`init_grid`()	Create the data grid
`pad`(ax, pad[, val])	Pad/unpad the edges of a grid along specified axes
`power_spectrum`([cross_grid, ax, in_place, ...])	Compute the power spectrum of a grid in map space
`sample`(positions[, properties])	Draw samples from the Grid at a list of positions
`save`(path[, compress, overwrite])	Save the grid instance in a .npz file that can be reloaded with the LoadGrid class
`scale_axis`(ax, factor[, axunits, scalecenter])	Rescale an axis or axes of the grid by a constant factor
`spherical_average`([ax, center, shells, ...])	Compute averages in spherical shells along the grid axes
`sum_properties`([properties, in_place])	Sum values of different properties
`visualize`([ax, slice_indices, property, ...])	Quick grid visualizations

init_grid()

Create the data grid

This function is separated out from __init__ so that memory isn’t used up when it isn’t needed, and so that grids can be created in different ways by child classes.

Parameters:

None

pad(ax, pad, val=0)

Pad/unpad the edges of a grid along specified axes

This method adds a specified number of additional cells to BOTH the beginning and end of a grid. The axes to pad can be specified with the ax parameter. By default zero padding is performed, but a different value can be specified in val.

If a value less than zero is specified in pad, the edges of the grid will be cropped.

This method will apply the padding in whatever space a given axis is currently represented in (Fourier or physical space).

Parameters:

axint or tuple of ints: The index or indices of the axis to pad, each value should correspond to a spatial axis of the grid (so for a 3d grid 0, 1, or 2 are valid).
padint or tuple of ints: The number of cells to add to EACH side of the axis(es) specified by the ax parameter. If a tuple is given, it should have the same shape as ax. If a negative value is specified, the axes will be cropped by this number of cells.
valfloat, optional: The value to store in the added cells. This defaults to 0

crop(ax, min=None, max=None)

Crop a single grid axis to a specified range of values

Note that this will only work on axes which are represented in physical (not Fourier) space

Parameters:

axint: The index of the axis to pad. This should correspond to a spatial axis of the grid (so for a 3d grid 0, 1, or 2 are valid inputs).
minfloat (optional): Minimum value along the axis that will be kept. If none is specified the lower end of the grid will not be cropped. Only cells where the cener lies above the value of min are kept.
maxfloat (optional): Maximum value along the axis that will be kept. If none is specified the upper end of the grid will not be cropped. Only cells where the center lies below the value of max are kept.

scale_axis(ax, factor, axunits='same', scalecenter=True)

Rescale an axis or axes of the grid by a constant factor

Note that this transformation is always applied to the real- space axes, the Fourier axes will be rescaled by 1/factor.

Parameters:

axint or tuple of ints: The index or indices of the axis to transform, each value should correspond to a spatial axis of the grid (so for a 3d grid 0, 1, or 2 are valid).
factorfloat or tuple of floats: The factor by which to multiply each axis specified in ax.
scalecenterbool: Specifies whether the center of the grid should also be scaled by the scale factor or if the center point should be held fixed and only the extent of the grid relative to this point should be rescaled.
axunits‘same’ or str: If ‘same’ (default) the axis units will be left unchanged. Otherwise the units of the transformed axis will be changed to the specified string.

copy_axes(n_properties=1)

Create a new grid instance with the same axes as this one

Parameters:

n_propertiesint: The number of properties to include in the new grid

copy(properties=None)

Make a copy of this Grid as a new Grid instance

Parameters:

propertiesint or tuple of ints: Indices of the grid properties to keep in the copy. By default all properties are kept.

save(path, compress=False, overwrite=False)

Save the grid instance in a .npz file that can be reloaded with the LoadGrid class

Parameters:

pathstr: filename to which the data is to be saved
compressbool (default=False): If True the grid will be saved in a compressed format
overwritebool (default=False): If path already exists and overwrite is set to False the file will not be overwritten and an error will be raised.

add_new_prop(value=None): Add a new property to the grid

add_from_cat(positions, values=None, new_props=False, properties=None)

Add values to the grid

Parameters:

positionsarray: The positions of each object should be an n_objects x n_dimensions array
valuesarray (optional): Values to grid, should be an n_objects x n_properties array. If values is not specified and the Grid’s n_properties attribute is equal to 1, counts in cell for each postions value will be added to the grid.
new_propsbool (optional): If True, this method will create new entries along the poperty dimension for each set of values given rather than adding them on top of existing values. Default is False.
propertiesint or list of ints (optional): If specified, the values will only be added to the specified property indices. If None, values will be added to all property indices. Ignored if new_props = True

Add values to a grid from a list of positions (dimension N-1), and the values along the final dimension

Takes an array of positions with 1 dimension less than the dimensionality of the grid plus an array that will be added at that position along the final dimension.

Parameters:

positionsarray: The positions of each object should be an n_objects x (n_dimensions-1) array
valuesarray: Values to grid, should be an n_objects x grid_size_in_final_dimension array.
axint (optional): The axis along which the values are to be added, by default the final position axis is assumed
new_propbool (optional): If True, this method will create a new entry along the poperty dimension of the grid rather than adding values on top of any existing values in the grid. Default is False.
propertiesint or list of ints (optional): If specified, the values will only be added to the specified property indices. If None, values will be added to all property indices. Ignored if new_props = True

Add spectra to a grid

Takes an array of positions with 1 dimension less than the dimensionality of the grid plus a function that is evaluated over the final dimension of the grid. The function is evaulated at axis value along the final axis.

spec_function should take as its first argument an array of frequencies (values of the Grid instances axis matching the spec_ax parameter), and as its second argument an array of shape n_objects x n_parameters containing any additional function arguments for the spec_function. The parameters for each object are then passed as spec_function_arguments. By default, it is assumed that the function will be evaluated simultaneously for all objects, and return an array of shape (n_objects x spec_ax_length).

Example spec_function: >>> # Gaussian spectral line w/ 100 km/s sigma, assumes axis is in GHz >>> # and line rest frequency is 115 GHz >>> def spec_func(axis, params): >>> … lum = params[:,0] >>> … redshift = params[:,1] >>> … nu0 = 115/(1+redshift) # Redshift line center >>> … nu_sig = 300 / 3e5 * nu0 # FWHM in GHz >>> … # Reshape arrays so everything broadcasts together into the right shape: >>> … lum = lum.reshape(-1,1) >>> … nu_sig = nu_sig.reshape(-1,1) >>> … nu0 = nu0.reshape(-1,1) >>> … ax = axis.reshape(1,-1) >>> … spec = lum / np.sqrt(2*np.pi*nu_sig**2) * np.exp(-0.5 * (ax-nu0)**2/nu_sig**2) >>> … return spec The corresponding spec_function_arguments would be >>> spec_function_arguments = np.array([[lum1, redshift1],…,[lumn,redshiftn]])

The optimal way to characterize a spectrum for this type of gridding is in terms of its cumulative value along spectral axis, which can then be evaluated at each bin edge and differenced to return an integrated spectrum that will not depend on the steps along the grid or (for example) lose flux from narrow peaks that aren’t well sampled by the Grid axis. If spec_function is written as a cumulative function, then set is_cumulative to True, and the spectrum will be constructed by evaluating spec_function at the edges of the axis cells and then differencing. This is not the default as it is not common to write analytic formulae for the integral of a spectrum.

Parameters:

positionsarray: The positions of each object should be an n_objects x (n_dimensions-1) array
spec_functionCallable: Function that will be evaluated to compute the spectra of each object
spec_function_argsarray: Array of shape n_objects x n_function_parameters that will be passed to spec_function when evaluating spectra of each object
spec_axint (optional): The axis along which the values are to be added, by default the final position axis is assumed
eval_as_loopbool (default = False): If True, the spec_function will be evaluated in a loop - one call per object in the positions and spec_function_args arrays.
is_cumulativebool (default = False): If True, the spec_function returns the integral of the spectrum from 0 to a given point along the axis, and the final spectrum is calculated by differencing evaluated values at the edge of each bin in the Grid.
careful_with_memorybool (default = True): If True, the input arrays of positions and spec_function_args will be broken up into smaller chunks and added to the grid one chunk at a time. This is helpful for preventing memory overflows when processing large catalogs. The chunk size is determined so that the number of array elements used to hold spectra is never larger than the number of array elements in the grid itself.
new_propbool (optional): If True, this method will create a new entry along the poperty dimension of the grid rather than adding values on top of any existing values in the grid. Default is False.
propertiesint or list of ints (optional): If specified, the values will only be added to the specified property indices. If None, values will be added to all property indices. Ignored if new_props = True

sum_properties(properties=None, in_place=True)

Sum values of different properties

Parameters:

propertiesint or tuple of ints: Indices of the grid properties to include in the sum. By default all properties are used.
in_placebool (default = True): If True, the sum will be stored in a new property index of the current Grid instance. If False, a new grid containing the summed property is returned

Returns:

Grid instance: Either the original grid, with the new property added in the last property index (in_place=True, default) or a new grid containing only the summed property (in_place=False)

sample(positions, properties=None)

Draw samples from the Grid at a list of positions

This function takes a list of positions and returns the value of the grid cell closest to the specified position. Useful for simulating timestreams.

Parameters:

positionsarray: An array containg the positions at which to sample the grid. It should have a shape of (n_samples, n_dimensions) where n_dimensions is the number of dimensions of the grid. Repeats of the same position are allowed.
propertiesint or tuple of ints: Indices of the grid properties to return. By default all properties are returned.

Returns:

samples: An array containing the property values at every requrested position. This array will have the shape (n_samples, n_properites) and is two dimensional even if only one property was requested.

convolve(source, ax=None, in_place=True, pad=None)

Convolve this Grid with another Grid instance.

Carries out convolution of this Grid’s data array with the data array of another Grid instance specified by source. The source grid should typically be psf-like (see e.g. the PSF and Spectral PSF classes) but the method functionality is completely general.

The axes along which to perform the convolution can be specified.

Parameters:

sourceGrid instance: A Grid instance containing the pattern to convolve with the grid.
axint or tuple of ints: The index or indices of the axis to convolve, each value should correspond to a spatial axis of the grid (so for a 3d grid 0, 1, or 2 are valid).
in_placebool (default = True): If True, the convolved grid will overwrite the original data grid of this Grid instance. If False, a new Grid containing the convolved grid property is returned
padint (optional): Specify a number of cells to zero pad onto the each side of the grid during the convolution.

Returns:

convolvedgrid: A Grid instance containing the convolved grid. Either this Grid (in_place=True, default), or a new Grid instance (in_place=False)

down_sample(ax, factor, mode='average')

Degrade the resolution of the grid along a specified axis by binning groups of pixels.

This is only supported in real-space currently

Parameters:

axint or tuple of ints: The index or indices of the axis to donwsample, each value should correspond to a spatial axis of the grid (so for a 3d grid 0, 1, or 2 are valid).
factorint or tuple of ints: Number of pixels to bin together along the axes specified.
mode‘average’ or ‘sum’ (default=’average’): Specify whether bin values should be computed by summing or averaging groups of adjaced cells. Default is average

collapse_dimension(ax, in_place=True, weights=None, mode='average')

Collapse one or more dimensions of a grid

Parameters:

axint or tuple of ints: The index or indices of the axis to collapse, each value should correspond to a spatial axis of the grid (so for a 3d grid 0, 1, or 2 are valid).
in_placebool (default = True): If True, the collapsed grid will overwrite the original data grid of this Grid instance. If False, a new Grid containing the collapsed grid is returned
weightsarray or list of arrays (optional): The weights to apply to each cell along the axis being collapsed. If multipl axes are specified in ax, a list should be specified here. If no values are given, uniform weights are assumed.
mode‘sum’ or ‘average’: Determines whether grids are averaged or summed along the axis being collapsed.

Returns:

collapsededgrid: A Grid instance containing the collapsed grid. Either this Grid (in_place=True, default), or a new Grid instance (in_place=False)

fourier_transform(ax=None, normalize=True)

Fourier transform the grid

This method will fourier transform the grid along specified axes. If the grid is already in Fourier space along a given axis, the inverse fourier transform will be computed instead. These changes are applied directly to the grid.

Parameters:

axint or list of ints (optional): Indices of the axes to be transformed, if no axes are given the operation will be applied to all axes
normalizebool (optional): Determines whether the a normalization should be applied to the transform (the normalization is pixel_size[i] for forward transforms along axis i, and 1/pixel_size[i] for inverse transforms)

power_spectrum(cross_grid=None, ax=None, in_place=False, normalize=True)

Compute the power spectrum of a grid in map space

The default behavior is to return a new grid instance containing the power spectrum, however if in_place is set to True, the original grid will be replaced with the power spectrum. Note that this procedure cannot be reversed.

A cross-power spectrum can be computed by specifying a cross_grid - another grid instance to be taken as the second term in the cross-power.

This function checks whether a grid is already in power spectrum form, and will not run if it is.

Parameters:

cross_gridGrid instance, optional: A second grid, which will be used to compute a cross-power spectrum
axint or list of ints, optional: Indices of the axes to be put into fourier space to compute the power spectrum. If no axes are given the operation will be applied to all axes. It does not matter what space the grid is initially in (coordinate of Fourier) - the method ensures that all axes specified in ax are transformed to Fourier space before computing a power spectrum. Any axes that must be transformed will be transformed back after the power spectrum is computed (unless in_place is set to true, in which case the power spectrum grid is left in Fourier space).
in_placebool, optional: If set to False (default) a grid instance containing the power spectrum will be returned. If set to True the existing grid will be overwritten by the power spectrum.
normalizebool, optional: Determines whether the a normalization should be applied to the fourier transform. See fourier_transform method for details

spherical_average(ax=None, center=None, shells=None, binmode='linear', weights=None, return_std=False, biased_std=True, return_n=False)

Compute averages in spherical shells along the grid axes

This function only works if all axes are in real space or all axes are in Fourier space. Mixtures of the two are not supported.

Parameters:

axint or tuple of ints: The axes or axes in which the data should be averaged. By default all axes will be averaged resulting in a 1d array.
centertuple of floats (optional): The location of the center of the sphere used for averaging. By default the origin of the grid is used.
shellsint or array (optional): If an int is given, the average will be carried out in this number of shells. If an array is given, it will be treated as the shell edges. If no value is given, the shells will be automatically computed.
binmode‘linear’ or ‘log’: Whether spherical shells should be linearly or logarithmically spaced. This is ignored if the shells are specified in the shells keyword.
weightsarray (optional): An array of the same number of dimensions as the grid (including or excluding the properties dimension) specifying the weights to give each grid cell when computing the average. If not specified all cells receive uniform weight.
return_stdbool (default=False): If set to True the standard deviation will be returned in addion to the average
biased_stdbool (default=True): If True the biased standard deviation is computed when return_std is set to True
return_nbool (default=False): If set to True the number of cells used to compute the average in each shell is also returned

Returns:

axes: The axes describing the average - if averaged over all dimensions this will simply be the shells
spherical_average: The average values in each shell
std (optional): The standard deviation in each shell
n (optional): The number of grid cells that fell in each shell

visualize(ax=[0, 1], slice_indices='sum', property=0, figsize=(5, 5), axkws={}, plotkws={})

Quick grid visualizations

Plots a 2D representation of the grid

Parameters:

axlist of two axes: List of len 2 specifying the 2 axes to plot along, other axes will either be collapsed via a sum, or shown at a single slice.
slice_indiceslist or ‘sum’: List containing indices at which to extract values of the other spatial axes of the grid. If ‘sum’ is given, the other axes will be collapsed by summing over all indices.
propertyint (default=0): The index of the property to plot. Shows the property in the 0 index by 0.
figsizetuple: Size of the figure
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.pcolor() when creating the plot data

animate(save=None, prop_ind=0, slide_dim=2, face_dims=[0, 1], i0=0, still=False, logscale=False, minrescale=1, maxrescale=1): Animated stepthrough of the grid for visualizing 3d data

Creating Data Cubes

The map.Gridder method will grid properties from a catalog of objects in an arbitrary of number of dimensions to create maps and data cubes.

class simim.map.Gridder(positions, values=None, center_point=None, side_length=None, pixel_size=1, axunits=None, gridunits=None, setndims=None)

Put properties into a grid

Only required argument is positions - an array of object positions. If no other arguments are specified, code will return a grid of counts in cells and will to construct a grid based on the extremal values of the position list and a pixel edge length of 1 - this will work reasonably for a densely populated grid, but may get poor results if the positions don’t sample the full volume you’re trying to represent.

To specify a grid provide the center_point, side_length, and pixel_size.

To grid a property instead of number counts, specify the values parameter with an array of values equal in length to positions.

Parameters:

positionsarray: The positions of each object should be an n_objects x n_dimensions array
valuesarray (optional): Values to grid, an arbitrary number of properties can be specified and gridded independently. Should be an n_objects x n_properties
center_pointarray (optional): The center of the grid, must match the number of dimensions specified in positions. If left unspecified, it will be set to the point half way between the largest and smallest positions value in each dimension
side_lengthfloat or array (optional): The length of the box edges. Should either be a single value or an array with the same number of elements as the dimensions specified in positions. If left unspecified, it will be set to slightly larger than the stretch between the largest and smallest position in each dimension. If this is not an integer multiple of the pixel_size, it will be increased to the next integer multiple.
pixel_sizefloat or array (optional): The length of the pixel edges. Should either be a single value or an array with the same number of elements as the dimensions specified in positions. Default is 1 in each dimension.
axunitsstr or array (optional): The units of each axis. Should either be a single value or an array with the same number of elements as the dimensions specified in positions
gridunitsstr or array (optional): The units of the grid. Should either be a single value or an array with the same number of elements as the number properties
setndimsint (optional): The number of dimensions of the object positions - the program tries to determine this by default, but may be useful if the positions array is empty.

Methods

`add_from_cat`(positions[, values, new_props, ...])	Add values to the grid
`add_from_pos_plus_array`(positions, values[, ...])	Add values to a grid from a list of positions (dimension N-1), and the values along the final dimension
`add_from_spec_func`(positions, spec_function)	Add spectra to a grid
`add_new_prop`([value])	Add a new property to the grid
`animate`([save, prop_ind, slide_dim, ...])	Animated stepthrough of the grid for visualizing 3d data
`collapse_dimension`(ax[, in_place, weights, mode])	Collapse one or more dimensions of a grid
`convolve`(source[, ax, in_place, pad])	Convolve this Grid with another Grid instance.
`copy`([properties])	Make a copy of this Grid as a new Grid instance
`copy_axes`([n_properties])	Create a new grid instance with the same axes as this one
`crop`(ax[, min, max])	Crop a single grid axis to a specified range of values
`down_sample`(ax, factor[, mode])	Degrade the resolution of the grid along a specified axis by binning groups of pixels.
`fourier_transform`([ax, normalize])	Fourier transform the grid
`init_grid`()	Create the data grid
`pad`(ax, pad[, val])	Pad/unpad the edges of a grid along specified axes
`power_spectrum`([cross_grid, ax, in_place, ...])	Compute the power spectrum of a grid in map space
`sample`(positions[, properties])	Draw samples from the Grid at a list of positions
`save`(path[, compress, overwrite])	Save the grid instance in a .npz file that can be reloaded with the LoadGrid class
`scale_axis`(ax, factor[, axunits, scalecenter])	Rescale an axis or axes of the grid by a constant factor
`spherical_average`([ax, center, shells, ...])	Compute averages in spherical shells along the grid axes
`sum_properties`([properties, in_place])	Sum values of different properties
`visualize`([ax, slice_indices, property, ...])	Quick grid visualizations

add_from_cat(positions, values=None, new_props=False, properties=None)

Add values to the grid

Parameters:

positionsarray: The positions of each object should be an n_objects x n_dimensions array
valuesarray (optional): Values to grid, should be an n_objects x n_properties array. If values is not specified and the Grid’s n_properties attribute is equal to 1, counts in cell for each postions value will be added to the grid.
new_propsbool (optional): If True, this method will create new entries along the poperty dimension for each set of values given rather than adding them on top of existing values. Default is False.
propertiesint or list of ints (optional): If specified, the values will only be added to the specified property indices. If None, values will be added to all property indices. Ignored if new_props = True

Add values to a grid from a list of positions (dimension N-1), and the values along the final dimension

Takes an array of positions with 1 dimension less than the dimensionality of the grid plus an array that will be added at that position along the final dimension.

Parameters:

positionsarray: The positions of each object should be an n_objects x (n_dimensions-1) array
valuesarray: Values to grid, should be an n_objects x grid_size_in_final_dimension array.
axint (optional): The axis along which the values are to be added, by default the final position axis is assumed
new_propbool (optional): If True, this method will create a new entry along the poperty dimension of the grid rather than adding values on top of any existing values in the grid. Default is False.
propertiesint or list of ints (optional): If specified, the values will only be added to the specified property indices. If None, values will be added to all property indices. Ignored if new_props = True

Add spectra to a grid

Takes an array of positions with 1 dimension less than the dimensionality of the grid plus a function that is evaluated over the final dimension of the grid. The function is evaulated at axis value along the final axis.

spec_function should take as its first argument an array of frequencies (values of the Grid instances axis matching the spec_ax parameter), and as its second argument an array of shape n_objects x n_parameters containing any additional function arguments for the spec_function. The parameters for each object are then passed as spec_function_arguments. By default, it is assumed that the function will be evaluated simultaneously for all objects, and return an array of shape (n_objects x spec_ax_length).

Example spec_function: >>> # Gaussian spectral line w/ 100 km/s sigma, assumes axis is in GHz >>> # and line rest frequency is 115 GHz >>> def spec_func(axis, params): >>> … lum = params[:,0] >>> … redshift = params[:,1] >>> … nu0 = 115/(1+redshift) # Redshift line center >>> … nu_sig = 300 / 3e5 * nu0 # FWHM in GHz >>> … # Reshape arrays so everything broadcasts together into the right shape: >>> … lum = lum.reshape(-1,1) >>> … nu_sig = nu_sig.reshape(-1,1) >>> … nu0 = nu0.reshape(-1,1) >>> … ax = axis.reshape(1,-1) >>> … spec = lum / np.sqrt(2*np.pi*nu_sig**2) * np.exp(-0.5 * (ax-nu0)**2/nu_sig**2) >>> … return spec The corresponding spec_function_arguments would be >>> spec_function_arguments = np.array([[lum1, redshift1],…,[lumn,redshiftn]])

The optimal way to characterize a spectrum for this type of gridding is in terms of its cumulative value along spectral axis, which can then be evaluated at each bin edge and differenced to return an integrated spectrum that will not depend on the steps along the grid or (for example) lose flux from narrow peaks that aren’t well sampled by the Grid axis. If spec_function is written as a cumulative function, then set is_cumulative to True, and the spectrum will be constructed by evaluating spec_function at the edges of the axis cells and then differencing. This is not the default as it is not common to write analytic formulae for the integral of a spectrum.

Parameters:

positionsarray: The positions of each object should be an n_objects x (n_dimensions-1) array
spec_functionCallable: Function that will be evaluated to compute the spectra of each object
spec_function_argsarray: Array of shape n_objects x n_function_parameters that will be passed to spec_function when evaluating spectra of each object
spec_axint (optional): The axis along which the values are to be added, by default the final position axis is assumed
eval_as_loopbool (default = False): If True, the spec_function will be evaluated in a loop - one call per object in the positions and spec_function_args arrays.
is_cumulativebool (default = False): If True, the spec_function returns the integral of the spectrum from 0 to a given point along the axis, and the final spectrum is calculated by differencing evaluated values at the edge of each bin in the Grid.
careful_with_memorybool (default = True): If True, the input arrays of positions and spec_function_args will be broken up into smaller chunks and added to the grid one chunk at a time. This is helpful for preventing memory overflows when processing large catalogs. The chunk size is determined so that the number of array elements used to hold spectra is never larger than the number of array elements in the grid itself.
new_propbool (optional): If True, this method will create a new entry along the poperty dimension of the grid rather than adding values on top of any existing values in the grid. Default is False.
propertiesint or list of ints (optional): If specified, the values will only be added to the specified property indices. If None, values will be added to all property indices. Ignored if new_props = True

add_new_prop(value=None): Add a new property to the grid

animate(save=None, prop_ind=0, slide_dim=2, face_dims=[0, 1], i0=0, still=False, logscale=False, minrescale=1, maxrescale=1): Animated stepthrough of the grid for visualizing 3d data

collapse_dimension(ax, in_place=True, weights=None, mode='average')

Collapse one or more dimensions of a grid

Parameters:

axint or tuple of ints: The index or indices of the axis to collapse, each value should correspond to a spatial axis of the grid (so for a 3d grid 0, 1, or 2 are valid).
in_placebool (default = True): If True, the collapsed grid will overwrite the original data grid of this Grid instance. If False, a new Grid containing the collapsed grid is returned
weightsarray or list of arrays (optional): The weights to apply to each cell along the axis being collapsed. If multipl axes are specified in ax, a list should be specified here. If no values are given, uniform weights are assumed.
mode‘sum’ or ‘average’: Determines whether grids are averaged or summed along the axis being collapsed.

Returns:

collapsededgrid: A Grid instance containing the collapsed grid. Either this Grid (in_place=True, default), or a new Grid instance (in_place=False)

convolve(source, ax=None, in_place=True, pad=None)

Convolve this Grid with another Grid instance.

Carries out convolution of this Grid’s data array with the data array of another Grid instance specified by source. The source grid should typically be psf-like (see e.g. the PSF and Spectral PSF classes) but the method functionality is completely general.

The axes along which to perform the convolution can be specified.

Parameters:

sourceGrid instance: A Grid instance containing the pattern to convolve with the grid.
axint or tuple of ints: The index or indices of the axis to convolve, each value should correspond to a spatial axis of the grid (so for a 3d grid 0, 1, or 2 are valid).
in_placebool (default = True): If True, the convolved grid will overwrite the original data grid of this Grid instance. If False, a new Grid containing the convolved grid property is returned
padint (optional): Specify a number of cells to zero pad onto the each side of the grid during the convolution.

Returns:

convolvedgrid: A Grid instance containing the convolved grid. Either this Grid (in_place=True, default), or a new Grid instance (in_place=False)

copy(properties=None)

Make a copy of this Grid as a new Grid instance

Parameters:

propertiesint or tuple of ints: Indices of the grid properties to keep in the copy. By default all properties are kept.

copy_axes(n_properties=1)

Create a new grid instance with the same axes as this one

Parameters:

n_propertiesint: The number of properties to include in the new grid

crop(ax, min=None, max=None)

Crop a single grid axis to a specified range of values

Note that this will only work on axes which are represented in physical (not Fourier) space

Parameters:

axint: The index of the axis to pad. This should correspond to a spatial axis of the grid (so for a 3d grid 0, 1, or 2 are valid inputs).
minfloat (optional): Minimum value along the axis that will be kept. If none is specified the lower end of the grid will not be cropped. Only cells where the cener lies above the value of min are kept.
maxfloat (optional): Maximum value along the axis that will be kept. If none is specified the upper end of the grid will not be cropped. Only cells where the center lies below the value of max are kept.

down_sample(ax, factor, mode='average')

Degrade the resolution of the grid along a specified axis by binning groups of pixels.

This is only supported in real-space currently

Parameters:

axint or tuple of ints: The index or indices of the axis to donwsample, each value should correspond to a spatial axis of the grid (so for a 3d grid 0, 1, or 2 are valid).
factorint or tuple of ints: Number of pixels to bin together along the axes specified.
mode‘average’ or ‘sum’ (default=’average’): Specify whether bin values should be computed by summing or averaging groups of adjaced cells. Default is average

fourier_transform(ax=None, normalize=True)

Fourier transform the grid

This method will fourier transform the grid along specified axes. If the grid is already in Fourier space along a given axis, the inverse fourier transform will be computed instead. These changes are applied directly to the grid.

Parameters:

axint or list of ints (optional): Indices of the axes to be transformed, if no axes are given the operation will be applied to all axes
normalizebool (optional): Determines whether the a normalization should be applied to the transform (the normalization is pixel_size[i] for forward transforms along axis i, and 1/pixel_size[i] for inverse transforms)

init_grid()

Create the data grid

This function is separated out from __init__ so that memory isn’t used up when it isn’t needed, and so that grids can be created in different ways by child classes.

Parameters:

None

pad(ax, pad, val=0)

Pad/unpad the edges of a grid along specified axes

This method adds a specified number of additional cells to BOTH the beginning and end of a grid. The axes to pad can be specified with the ax parameter. By default zero padding is performed, but a different value can be specified in val.

If a value less than zero is specified in pad, the edges of the grid will be cropped.

This method will apply the padding in whatever space a given axis is currently represented in (Fourier or physical space).

Parameters:

axint or tuple of ints: The index or indices of the axis to pad, each value should correspond to a spatial axis of the grid (so for a 3d grid 0, 1, or 2 are valid).
padint or tuple of ints: The number of cells to add to EACH side of the axis(es) specified by the ax parameter. If a tuple is given, it should have the same shape as ax. If a negative value is specified, the axes will be cropped by this number of cells.
valfloat, optional: The value to store in the added cells. This defaults to 0

power_spectrum(cross_grid=None, ax=None, in_place=False, normalize=True)

Compute the power spectrum of a grid in map space

The default behavior is to return a new grid instance containing the power spectrum, however if in_place is set to True, the original grid will be replaced with the power spectrum. Note that this procedure cannot be reversed.

A cross-power spectrum can be computed by specifying a cross_grid - another grid instance to be taken as the second term in the cross-power.

This function checks whether a grid is already in power spectrum form, and will not run if it is.

Parameters:

cross_gridGrid instance, optional: A second grid, which will be used to compute a cross-power spectrum
axint or list of ints, optional: Indices of the axes to be put into fourier space to compute the power spectrum. If no axes are given the operation will be applied to all axes. It does not matter what space the grid is initially in (coordinate of Fourier) - the method ensures that all axes specified in ax are transformed to Fourier space before computing a power spectrum. Any axes that must be transformed will be transformed back after the power spectrum is computed (unless in_place is set to true, in which case the power spectrum grid is left in Fourier space).
in_placebool, optional: If set to False (default) a grid instance containing the power spectrum will be returned. If set to True the existing grid will be overwritten by the power spectrum.
normalizebool, optional: Determines whether the a normalization should be applied to the fourier transform. See fourier_transform method for details

sample(positions, properties=None)

Draw samples from the Grid at a list of positions

This function takes a list of positions and returns the value of the grid cell closest to the specified position. Useful for simulating timestreams.

Parameters:

positionsarray: An array containg the positions at which to sample the grid. It should have a shape of (n_samples, n_dimensions) where n_dimensions is the number of dimensions of the grid. Repeats of the same position are allowed.
propertiesint or tuple of ints: Indices of the grid properties to return. By default all properties are returned.

Returns:

samples: An array containing the property values at every requrested position. This array will have the shape (n_samples, n_properites) and is two dimensional even if only one property was requested.

save(path, compress=False, overwrite=False)

Save the grid instance in a .npz file that can be reloaded with the LoadGrid class

Parameters:

pathstr: filename to which the data is to be saved
compressbool (default=False): If True the grid will be saved in a compressed format
overwritebool (default=False): If path already exists and overwrite is set to False the file will not be overwritten and an error will be raised.

scale_axis(ax, factor, axunits='same', scalecenter=True)

Rescale an axis or axes of the grid by a constant factor

Note that this transformation is always applied to the real- space axes, the Fourier axes will be rescaled by 1/factor.

Parameters:

axint or tuple of ints: The index or indices of the axis to transform, each value should correspond to a spatial axis of the grid (so for a 3d grid 0, 1, or 2 are valid).
factorfloat or tuple of floats: The factor by which to multiply each axis specified in ax.
scalecenterbool: Specifies whether the center of the grid should also be scaled by the scale factor or if the center point should be held fixed and only the extent of the grid relative to this point should be rescaled.
axunits‘same’ or str: If ‘same’ (default) the axis units will be left unchanged. Otherwise the units of the transformed axis will be changed to the specified string.

spherical_average(ax=None, center=None, shells=None, binmode='linear', weights=None, return_std=False, biased_std=True, return_n=False)

Compute averages in spherical shells along the grid axes

This function only works if all axes are in real space or all axes are in Fourier space. Mixtures of the two are not supported.

Parameters:

axint or tuple of ints: The axes or axes in which the data should be averaged. By default all axes will be averaged resulting in a 1d array.
centertuple of floats (optional): The location of the center of the sphere used for averaging. By default the origin of the grid is used.
shellsint or array (optional): If an int is given, the average will be carried out in this number of shells. If an array is given, it will be treated as the shell edges. If no value is given, the shells will be automatically computed.
binmode‘linear’ or ‘log’: Whether spherical shells should be linearly or logarithmically spaced. This is ignored if the shells are specified in the shells keyword.
weightsarray (optional): An array of the same number of dimensions as the grid (including or excluding the properties dimension) specifying the weights to give each grid cell when computing the average. If not specified all cells receive uniform weight.
return_stdbool (default=False): If set to True the standard deviation will be returned in addion to the average
biased_stdbool (default=True): If True the biased standard deviation is computed when return_std is set to True
return_nbool (default=False): If set to True the number of cells used to compute the average in each shell is also returned

Returns:

axes: The axes describing the average - if averaged over all dimensions this will simply be the shells
spherical_average: The average values in each shell
std (optional): The standard deviation in each shell
n (optional): The number of grid cells that fell in each shell

sum_properties(properties=None, in_place=True)

Sum values of different properties

Parameters:

propertiesint or tuple of ints: Indices of the grid properties to include in the sum. By default all properties are used.
in_placebool (default = True): If True, the sum will be stored in a new property index of the current Grid instance. If False, a new grid containing the summed property is returned

Returns:

Grid instance: Either the original grid, with the new property added in the last property index (in_place=True, default) or a new grid containing only the summed property (in_place=False)

visualize(ax=[0, 1], slice_indices='sum', property=0, figsize=(5, 5), axkws={}, plotkws={})

Quick grid visualizations

Plots a 2D representation of the grid

Parameters:

axlist of two axes: List of len 2 specifying the 2 axes to plot along, other axes will either be collapsed via a sum, or shown at a single slice.
slice_indiceslist or ‘sum’: List containing indices at which to extract values of the other spatial axes of the grid. If ‘sum’ is given, the other axes will be collapsed by summing over all indices.
propertyint (default=0): The index of the property to plot. Shows the property in the 0 index by 0.
figsizetuple: Size of the figure
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.pcolor() when creating the plot data

The map.gridder_function function works in the same way as map.Gridder, but instead of creating a map.Grid instance it simply returns the constructed grid and axes.

simim.map.gridder_function(positions, values=None, center_point=None, side_length=None, pixel_size=1, setndims=None)

Wrapper for Gridder to simply return the grid and axes - see gridder docs

Returns:

gridn_dimensions + 1 dimensional array: The gridded values with the first n_dimensions axes corresponding to the positions, and the final axis indexing the different properties that have been gridded.
axeslist of n_dimensions arrays: The physical values along each dimension of the grid

PSFs

For creating representations of simple (Gaussian) instrumental point-spread functions, the map.PSF and map.SpectralPSF classes are available:

class simim.map.PSF(fwhm, pixel_size, side_length=None, axunits=None, norm='area')

Create a grid containing a Nd Gaussian PSF

The number of dimensions is inferred from the length of the fwhm input.

Parameters:

fwhmfloat or tuple of floats: The full width at half half maximum of the PSF in each dimension.
pixel_sizefloat or array: The length of the pixel edges. Should either be a single value or an array with the same number of elements as fwhm.
side_lengthfloat or tuple of floats (optional): The length along each spatial dimension of the grid. If a single value is given, all dimensions will be assumed to have the same length. Otherwise the length of the tuple should match the length of the fwhm. If no value is specified, a side length of 6 times the FWHM is used.
axunitsstr or tuple of str (optional): A string or tuple of strings specifying the units of the spatial axes.
norm‘area’ or ‘peak’: Determines whether the PSF is normalized to have a peak value of 1 or a total area/volume of 1.

Methods

`add_from_cat`(positions[, values, new_props, ...])	Add values to the grid
`add_from_pos_plus_array`(positions, values[, ...])	Add values to a grid from a list of positions (dimension N-1), and the values along the final dimension
`add_from_spec_func`(positions, spec_function)	Add spectra to a grid
`add_new_prop`([value])	Add a new property to the grid
`animate`([save, prop_ind, slide_dim, ...])	Animated stepthrough of the grid for visualizing 3d data
`collapse_dimension`(ax[, in_place, weights, mode])	Collapse one or more dimensions of a grid
`convolve`(source[, ax, in_place, pad])	Convolve this Grid with another Grid instance.
`copy`([properties])	Make a copy of this Grid as a new Grid instance
`copy_axes`([n_properties])	Create a new grid instance with the same axes as this one
`crop`(ax[, min, max])	Crop a single grid axis to a specified range of values
`down_sample`(ax, factor[, mode])	Degrade the resolution of the grid along a specified axis by binning groups of pixels.
`fourier_transform`([ax, normalize])	Fourier transform the grid
`init_grid`()	Create the data grid
`pad`(ax, pad[, val])	Pad/unpad the edges of a grid along specified axes
`power_spectrum`([cross_grid, ax, in_place, ...])	Compute the power spectrum of a grid in map space
`sample`(positions[, properties])	Draw samples from the Grid at a list of positions
`save`(path[, compress, overwrite])	Save the grid instance in a .npz file that can be reloaded with the LoadGrid class
`scale_axis`(ax, factor[, axunits, scalecenter])	Rescale an axis or axes of the grid by a constant factor
`spherical_average`([ax, center, shells, ...])	Compute averages in spherical shells along the grid axes
`sum_properties`([properties, in_place])	Sum values of different properties
`visualize`([ax, slice_indices, property, ...])	Quick grid visualizations

class simim.map.SpectralPSF(spec_axis, spec0, fwhm0, pixel_size, side_length=None, axunits=None, norm='area', exp=1)

Create a grid containing a (N-1)d Gaussian PSF that varies in width along one additional axis

For creating Gaussian beams that varry as a function of wavelength/ frequency.

Parameters:

spec_axisarray: The central wavelengths/frequencies of each channel for which the PSF should be computed. This should be uniformly spaced.
spec0float: The wavelength/frequency at which the FWHM (fwhm0) will be specified
fwhm0float or tuple of floats: The beam FWHM at spec0. A different value may be specified for each dimension.
pixel_sizefloat or array: The length of the pixel edges in the spatial dimensions. Should either be a single value or an array with the same number of elements as fwhm0.
side_lengthfloat or tuple of floats (optional): The length along each spatial dimension of the grid. If no value is specified, a side length of 6 times the FWHM is used.
axunitsstr or tuple of str (optional): A string or tuple of strings specifying the units of the spatial axes. The final value should be the units for the spectral axis.
norm‘area’ or ‘peak’: Determines whether the PSF is normalized to have a peak value of 1 or a total area/volume of 1. Each spectral slice is normalized independently.
expfloat (default=1): The power of spec0/spec (either nu0/nu or lambda0/lambda) by which the FWHM varries. Default is 1 - appropriate for a spectral axis in frequency units for a typical Gaussian beam.

Methods

`add_from_cat`(positions[, values, new_props, ...])	Add values to the grid
`add_from_pos_plus_array`(positions, values[, ...])	Add values to a grid from a list of positions (dimension N-1), and the values along the final dimension
`add_from_spec_func`(positions, spec_function)	Add spectra to a grid
`add_new_prop`([value])	Add a new property to the grid
`animate`([save, prop_ind, slide_dim, ...])	Animated stepthrough of the grid for visualizing 3d data
`collapse_dimension`(ax[, in_place, weights, mode])	Collapse one or more dimensions of a grid
`convolve`(source[, ax, in_place, pad])	Convolve this Grid with another Grid instance.
`copy`([properties])	Make a copy of this Grid as a new Grid instance
`copy_axes`([n_properties])	Create a new grid instance with the same axes as this one
`crop`(ax[, min, max])	Crop a single grid axis to a specified range of values
`down_sample`(ax, factor[, mode])	Degrade the resolution of the grid along a specified axis by binning groups of pixels.
`fourier_transform`([ax, normalize])	Fourier transform the grid
`init_grid`()	Create the data grid
`pad`(ax, pad[, val])	Pad/unpad the edges of a grid along specified axes
`power_spectrum`([cross_grid, ax, in_place, ...])	Compute the power spectrum of a grid in map space
`sample`(positions[, properties])	Draw samples from the Grid at a list of positions
`save`(path[, compress, overwrite])	Save the grid instance in a .npz file that can be reloaded with the LoadGrid class
`scale_axis`(ax, factor[, axunits, scalecenter])	Rescale an axis or axes of the grid by a constant factor
`spherical_average`([ax, center, shells, ...])	Compute averages in spherical shells along the grid axes
`sum_properties`([properties, in_place])	Sum values of different properties
`visualize`([ax, slice_indices, property, ...])	Quick grid visualizations

For more sophisticated PSFs, the map.GridFromAxesAndFunction class may be useful:

class simim.map.GridFromAxesAndFunction(function, *axes, function_kwargs={}, n_properties=1, axunits=None, gridunits=None)

Initialize a Grid from a set of axes and populate it using a function the axes

Create a grid by specifying the axes. Each axis given should be an array specifying the edges of the desired grid cells along that dimension. A function which takes the axis centers (determined as the midpoints along the specified axis edges) as arguments and returns an array is then used to populate the grid.

Parameters:

functionfunction: Function that will be used to populate the grid. This should take as arguments an arbitrary number of arrays (or a number of arrays equal to the number of axes specified) and return an array of shape (n1, n2, … ni).
*axesarray: One or more arrays of evenly spaced numbers describing the edgeds of each grid cell in one dimension.
function_kwargsdict (optional): Dictionary containing additional keyword arguments to pass when calling function.
n_propertiesint >= 1 (optional): The number of properties which will be stored in the grid. Note this number can be increased later.
axunitsstr or tuple of str (optional): A string or tuple of strings specifying the units of the spatial axes.
gridunitsstr or tuple of str (optional): A string or tuple of strings specifying the units of the grid values. A single value can be specified, or one value can be provided for each property, in which case the length of the tuple should equal n_properties.

Methods

`add_from_cat`(positions[, values, new_props, ...])	Add values to the grid
`add_from_pos_plus_array`(positions, values[, ...])	Add values to a grid from a list of positions (dimension N-1), and the values along the final dimension
`add_from_spec_func`(positions, spec_function)	Add spectra to a grid
`add_new_prop`([value])	Add a new property to the grid
`animate`([save, prop_ind, slide_dim, ...])	Animated stepthrough of the grid for visualizing 3d data
`collapse_dimension`(ax[, in_place, weights, mode])	Collapse one or more dimensions of a grid
`convolve`(source[, ax, in_place, pad])	Convolve this Grid with another Grid instance.
`copy`([properties])	Make a copy of this Grid as a new Grid instance
`copy_axes`([n_properties])	Create a new grid instance with the same axes as this one
`crop`(ax[, min, max])	Crop a single grid axis to a specified range of values
`down_sample`(ax, factor[, mode])	Degrade the resolution of the grid along a specified axis by binning groups of pixels.
`fourier_transform`([ax, normalize])	Fourier transform the grid
`init_grid`()	Create the data grid
`pad`(ax, pad[, val])	Pad/unpad the edges of a grid along specified axes
`power_spectrum`([cross_grid, ax, in_place, ...])	Compute the power spectrum of a grid in map space
`sample`(positions[, properties])	Draw samples from the Grid at a list of positions
`save`(path[, compress, overwrite])	Save the grid instance in a .npz file that can be reloaded with the LoadGrid class
`scale_axis`(ax, factor[, axunits, scalecenter])	Rescale an axis or axes of the grid by a constant factor
`spherical_average`([ax, center, shells, ...])	Compute averages in spherical shells along the grid axes
`sum_properties`([properties, in_place])	Sum values of different properties
`visualize`([ax, slice_indices, property, ...])	Quick grid visualizations

The map Module

Creating Data Cubes

PSFs

The `map` Module