Catalogue (`catalogue`)#

Handle catalogue I/O and processing.

`MissingValueError`	Value error raised when a mandatory field is missing/empty in a catalogue.
`DefaultValueWarning`	Warning issued when values of a field are not provided and set to the default.
`ParticleCatalogue`(x, y, z[, nz, ws, wc, logger])	Catalogue holding particle coordinates, weights and redshift-dependent mean number density.

exception triumvirate.catalogue.MissingValueError[source]#

Bases: ValueError

Value error raised when a mandatory field is missing/empty in a catalogue.

exception triumvirate.catalogue.DefaultValueWarning[source]#

Bases: UserWarning

Warning issued when values of a field are not provided and set to the default.

class triumvirate.catalogue.ParticleCatalogue(x, y, z, nz=None, ws=1.0, wc=1.0, logger=None)[source]#

Bases: object

Catalogue holding particle coordinates, weights and redshift-dependent mean number density.

Parameters

x, y, z (1-d array of float) – Cartesian coordinates of particles. x, y and z must have the same length.
nz ((1-d array of) float, optional) – Redshift-dependent mean number density (defaults is None). If an array, it must be of the same length as x, y and z.
ws, wc ((1-d array of) float, optional) – Sample weight and clustering weight of particles (defaults are 1.). If an array, it must be of the same length as x, y and z. See the note below for more details.
logger (logging.Logger, optional) – Program logger (default is None).

Variables

bounds (dict of {str: tuple of (float, float)}) – Particle coordinate bounds.
ntotal (int) – Total particle number.
wtotal (float) – Total particle overall weight.
wstotal (float) – Total particle sample weight.

Sample and clustering weights

There are two types of weights: sample weight ws (e.g. completeness weights) and clustering weight wc (e.g. Feldman–Kaiser–Peacock weights). The overall weight is the product of the two for each particle.

Note the naming convention above: in particular, wc is not the completeness weight (which is a component of ws instead).

classmethod read_from_file(filepath, reader='astropy', names=None, format='ascii.no_header', table_kwargs=None, file_kwargs=None, name_mapping=None, logger=None)[source]#

Read particle data from file.

Parameters

filepath (str or pathlib.Path) – Catalogue file path.
reader ({‘astropy’, ‘nbodykit’}, optional) – If ‘astropy’ (default), astropy.table.Table is used for reading in the catalogue file; else if ‘nbodykit’, child classes of nbodykit.source.catalog.file.FileCatalogBase is used (if nbodykit is available).
names (sequence of str, list of tuple or numpy.dtype, optional) – Catalogue file field names or data types. If None (default), the header in the file may be used to infer the field names or data types. See the note below for more details.
format (str, optional) – File format specifier (default is ‘ascii.no_header’ for default reader value ‘astropy’). See the note below for more details.
name_mapping (dict of {str: str}, optional) – Mapping between any of the default column names ‘x’, ‘y’, ‘z’, ‘nz’, ‘ws’ and ‘wc’ (keys) and the corresponding field names (values) in names (default is None).
table_kwargs (dict, optional) – Keyword arguments to be passed to astropy.table.Table.read (default is None). Used only when reader='astropy'.
file_kwargs (dict, optional) – Keyword arguments to be passed to child classes of nbodykit.source.catalog.file.FileCatalogBase (default is None). Used only when reader='nbodykit'. See also the hint below.
logger (logging.Logger, optional) – Program logger (default is None).

Examples

>>> ParticleCatalogue.read_from_file(
...     filepath,
...     reader='astropy',
...     format='fits',
...     # Match original data column names to the default names.
...     name_mapping={
...         'x': 'X', 'y': 'Y', 'z': 'Z',
...         'nz': 'NZ', 'ws': 'WEIGHT_SYS', 'wc': 'WEIGHT_FKP',
...     }
... )
>>> ParticleCatalogue.read_from_file(
...     filepath,
...     reader='nbodykit',
...     format='hdf5',
...     # `root` keyword argument is passed to `HDFCatalog`.
...     file_kwargs={root='particles'}
... )

format and names arguments

For reader='astropy', supported format can be found in ‘Built-In Table Readers/Writers’, and names correspond to the names keyword argument (sequence of str) in astropy.table.Table.read for a subset of formats. See astropy.table.Table for more details including appropriate table_kwargs.

For reader='nbodykit', supported format and the argument corresponding to names in the reader are—

'text' and names (sequence of str): plain-text files read in by nbodykit.source.catalog.file.CSVCatalog;
'binary' and dtype (list of tuple or numpy.dtype): binary files read in by nbodykit.source.catalog.file.BinaryCatalog;
'hdf5' and not applicable: HDF files read in by nbodykit.source.catalog.file.HDFCatalog (pass file_kwargs as appropriate).

See ‘Reading Catalogs from Disk’ for more details.

Hint

If any of the ‘nz’, ‘ws’ and ‘wc’ columns are not provided, these columns are initialised with the default values in ParticleCatalogue.

__getitem__(key)[source]#

Return one or more data entries.

Parameters: key ((list of) str, (list of) int or slice) – Data entry key(s) or selectors (indices or slices).
Returns: Data entry/entries.
Return type: numpy.ndarray

__setitem__(key, val)[source]#

Set data column.

Parameters

key (str) – Data column name.
val (1-d array_like) – Data column array.

compute_los()[source]#

Compute the line of sight to each particle.

Returns: los – Normalised line-of-sight vectors.
Return type: (N, 3) numpy.ndarray

compute_mean_density(volume=None, boxsize=None)[source]#

Compute the mean density over a volume.

This sets the ‘nz’ column to ntotal divided by volume or cubic (product of) boxsize, and is typically used for calculating the homogeneous background number density in a simulation box.

Parameters

volume (double, optional) – Volume over which the mean density is calculated.
boxsize (float or sequence of [float, float, float], optional) – Box size (in each dimension) over which the mean density is calculated. Used only when volume is None.

Attention

The invocation of this method resets the particle data column 'nz'.

centre(boxsize, catalogue_ref=None)[source]#

Centre a (pair of) catalogue(s) in a box.

Parameters

boxsize (float or sequence of [float, float, float]) – Box size (in each dimension).
catalogue_ref (ParticleCatalogue, optional) – Reference catalogue used for box alignment, also to be centred in the same box. If None (default), the current catalogue itself is used as the reference catalogue.

Note

The reference catalogue is typically the random-source catalogue (if provided). Particle coordinates in both catalogues are shifted by the same displacement vector such that the mid-point of particle coordinate extents in the reference catalogue is at the centre of the box.

pad(boxsize, ngrid=None, boxsize_pad=None, ngrid_pad=None, catalogue_ref=None)[source]#

Pad a (pair of) catalogue(s) in a box.

The particle coordinates are shifted away from the box corner at the origin such that in each dimension the minimum particle coordinate is given by the amount of padding, which can be set as a fraction of the box size or a multiple of the grid cell size.

Parameters

boxsize (float or sequence of [float, float, float]) – Box size in each dimension.
ngrid (int or sequence of [int, int, int], optional) – Grid number in each dimension (default is None). Must be provided if ngrid_pad is set.
boxsize_pad (float or sequence of [float, float, float], optional) – Box size padding factor. If not None (default), then ngrid_pad must be None.
ngrid_pad (float or sequence of [float, float, float], optional) – Grid padding factor. If not None (default), then boxsize_pad must be None.
catalogue_ref (ParticleCatalogue, optional) – Reference catalogue used for box alignment, also to be put in the same box. If None (default), the current catalogue itself is used as the reference catalogue.

Raises

ValueError – If boxsize_pad and ngrid_pad are both set to not None.

Note

The reference catalogue is typically the random-source catalogue (if provided). Particle coordinates in both catalogues are shifted by the same displacement vector such that the minimum particle coordinates in the reference catalogue are the amounts of padding specified.

periodise(boxsize)[source]#

Place particles in a periodic box of given box size.

Parameters: boxsize (float or sequence of [float, float, float]) – Box size (in each dimension).

offset_coords(origin)[source]#

Offset particle coordinates for a given origin.

Parameters: origin (float or sequence of [float, float, float]) – Coordinates of the new origin.

write_attrs_as_header(catalogue_ref=None)[source]#

Write catalogue attributes as a header.

Parameters: catalogue_ref (ParticleCatalogue, optional) – Reference catalogue (default is None) whose attributes are also written out. This is typically the random-source catalogue.
Returns: text_header – Catalogue attributes as a header string.
Return type: str

Catalogue (catalogue)

Catalogue (catalogue)#

Catalogue (`catalogue`)#