UserSuppliedHaloCatalog

class halotools.sim_manager.UserSuppliedHaloCatalog(**kwargs)

Bases: object

Class used to transform a user-provided halo catalog into the standard form recognized by Halotools.

See Instructions for Working with an Alternative Halo Catalog for a tutorial on this class.

Parameters:

**metadatafloat or string

Keyword arguments storing catalog metadata. The quantities Lbox and particle_mass are required and must be in Mpc/h and Msun/h units, respectively. redshift is also required metadata. See Examples section for further notes.

**halo_catalog_columnssequence of arrays

Sequence of length-Nhalos arrays passed in as keyword arguments.

Each key will be the column name attached to the input array. All keys must begin with the substring halo_ to help differentiate halo property from mock galaxy properties. At a minimum, there must be a halo_id keyword argument storing a unique integer for each halo, as well as columns halo_x, halo_y and halo_z. There must also be some additional mass-like variable, for which you can use any name that begins with halo_ See Examples section for further notes.

user_supplied_ptclcattable, optional

Instance of the UserSuppliedPtclCatalog class. If this keyword is passed, the UserSuppliedHaloCatalog instance will have a ptcl_table attribute bound to it storing dark matter particles randomly selected from the snapshot. At a minimum, the table must have columns x, y and z. Default is None.

Examples

Here is an example using dummy data to show how to create a new UserSuppliedHaloCatalog instance from from your own halo catalog. First the setup:

>>> redshift = 0.0
>>> Lbox = 250.
>>> particle_mass = 1e9
>>> num_halos = 100
>>> x = np.random.uniform(0, Lbox, num_halos)
>>> y = np.random.uniform(0, Lbox, num_halos)
>>> z = np.random.uniform(0, Lbox, num_halos)
>>> mass = np.random.uniform(1e12, 1e15, num_halos)
>>> ids = np.arange(0, num_halos)

Now we simply pass in both the metadata and the halo catalog columns as keyword arguments:

>>> halo_catalog = UserSuppliedHaloCatalog(redshift = redshift, Lbox = Lbox, particle_mass = particle_mass, halo_x = x, halo_y = y, halo_z = z, halo_id = ids, halo_mvir = mass)

Your halo_catalog object can be used throughout the Halotools package. The halo catalog itself is stored in the halo_table attribute, with columns accessed as follows:

>>> array_of_masses = halo_catalog.halo_table['halo_mvir']
>>> array_of_x_positions = halo_catalog.halo_table['halo_x']

Each piece of metadata you passed in can be accessed as an ordinary attribute:

>>> halo_catalog_box_size = halo_catalog.Lbox
>>> particle_mass = halo_catalog.particle_mass

If you wish to pass in additional metadata, just include additional keywords:

>>> simname = 'my_personal_sim'

>>> halo_catalog = UserSuppliedHaloCatalog(redshift = redshift, simname = simname, Lbox = Lbox, particle_mass = particle_mass, halo_x = x, halo_y = y, halo_z = z, halo_id = ids, halo_mvir = mass)

Similarly, if you wish to include additional columns for your halo catalog, Halotools is able to tell the difference between metadata and columns of halo data:

>>> spin = np.random.uniform(0, 0.2, num_halos)
>>> halo_catalog = UserSuppliedHaloCatalog(redshift = redshift, halo_spin = spin, simname = simname, Lbox = Lbox, particle_mass = particle_mass, halo_x = x, halo_y = y, halo_z = z, halo_id = ids, halo_mvir = mass)

If you want to store your halo catalog in the Halotools cache, use the add_halocat_to_cache method.

You also have the option to supply a randomly selected downsample of dark matter particles via the user_supplied_ptclcat keyword. This keyword have an instance of the UserSuppliedPtclCatalog class bound to it, which helps ensure consistency between the halo catalog and particles.

Here’s an example of how to use this argument using some fake data:

>>> num_ptcls = int(1e4)
>>> ptcl_x = np.random.uniform(0, Lbox, num_ptcls)
>>> ptcl_y = np.random.uniform(0, Lbox, num_ptcls)
>>> ptcl_z = np.random.uniform(0, Lbox, num_ptcls)

>>> from halotools.sim_manager import UserSuppliedPtclCatalog
>>> ptclcat = UserSuppliedPtclCatalog(x = ptcl_x, y = ptcl_y, z = ptcl_z, Lbox = Lbox, particle_mass = particle_mass, redshift = redshift)
>>> halo_catalog = UserSuppliedHaloCatalog(user_supplied_ptclcat = ptclcat, redshift = redshift, halo_spin = spin, simname = simname, Lbox = Lbox, particle_mass = particle_mass, halo_x = x, halo_y = y, halo_z = z, halo_id = ids, halo_mvir = mass)

In some scenarios, you may already have tabular data stored in an Astropy astropy.table.Table or a Numpy structured array. If you want to transfer all the columns of your table_of_halos to the UserSuppliedHaloCatalog, then you can do so by splatting a python dictionary view of the table:

>>> from astropy.table import Table
>>> table_of_halos = Table()
>>> num_halos = int(1e3)
>>> Lbox = 250.
>>> table_of_halos['halo_mass'] = np.random.uniform(1e10, 1e15, num_halos)
>>> table_of_halos['halo_x'] = np.random.uniform(0, Lbox, num_halos)
>>> table_of_halos['halo_y'] = np.random.uniform(0, Lbox, num_halos)
>>> table_of_halos['halo_z'] = np.random.uniform(0, Lbox, num_halos)
>>> table_of_halos['halo_jcvd'] = np.random.random(num_halos)

>>> table_of_halos['halo_id'] = np.arange(num_halos).astype('i8')

>>> d = {key:table_of_halos[key] for key in table_of_halos.keys()}
>>> halocat = UserSuppliedHaloCatalog(simname = simname, redshift = redshift, Lbox = Lbox, particle_mass = particle_mass, **d)

Methods Summary

add_halocat_to_cache(fname, simname, ...[, ...])

Methods Documentation

add_halocat_to_cache(fname, simname, halo_finder, version_name, processing_notes, overwrite=False, **additional_metadata)

Parameters:

fnamestring

Absolute path of the file where you will store the halo catalog. Your filename must conclude with an hdf5 extension.

The Halotools cache system will remember whatever location you choose, so try to choose a reasonably permanent resting place on disk. You can always relocate your catalog after caching it by following the Relocating Simulation Data and Updating the Cache documentation page.

simnamestring

Nickname of the simulation used as a shorthand way to keep track of the halo catalogs in your cache.

halo_finderstring

Nickname of the halo-finder used to generate the hlist file from particle data.

version_namestring

Nickname of the version of the halo catalog. The version_name is used as a bookkeeping tool in the cache log.

processing_notesstring

String used to provide supplementary notes that will be attached to the hdf5 file storing your halo catalog.

overwritebool, optional

If the chosen fname already exists, then you must set overwrite to True in order to write the file to disk. Default is False.

**additional_metadatasequence of strings, optional

Each keyword of additional_metadata defines the name of a piece of metadata stored in the hdf5 file. The value bound to each key can be any string. When you load your cached halo catalog into memory, each piece of metadata will be stored as an attribute of the CachedHaloCatalog instance.