Instructions for Working with an Alternative Halo Catalog

This section of the documentation describes how to get started with simulation data besides the Halotools-provided catalogs. If you want to store a new Rockstar catalog in the Halotools cache, see Instructions for Reducing and Caching a Rockstar Catalog. Or if you just want to read Rockstar ASCII data and not cache the reduction, see the docstring of the TabularAsciiReader class. Below we describe how to transform halo catalogs other than those identified with Rockstar into a standard form that will work with the mock-population factories of Halotools, with or without caching the halos.

Basic usage of the UserSuppliedHaloCatalog class

In order to put your halo catalog into a standard form recognized by Halotools, the only thing you need to do is instantiate the UserSuppliedHaloCatalog class by passing your simulation data and metadata to the constructor. Once you have an instance of UserSuppliedHaloCatalog, the halo data is bound to the halo_table attribute of the instance in the form of an Astropy Table; see the UserSuppliedHaloCatalog instance. The docstring of UserSuppliedHaloCatalog gives a detailed description of the arguments required by the constructor.

Notes on properly formatting halo properties

Note that every column of a halo catalog must begin with the halo_ substring. The justification for this requirement is easy to understand. The basic task performed during the generation of a mock galaxy population is to create a galaxy_table, which is an Astropy Table storing the galaxy data. The galaxy_table contains a combination of properties assigned by the model and properties inherited by the underlying halos. No Halotools model is permitted to define a name for a galaxy property that begins with halo_, and all halo catalog properties must begin with halo_. This provides a simple way to guarantee that there there will be no conflicts between the column names of halo properties bound to a mock and the column names created by some Halotools model during mock-population.

In principle, if you are able to instantiate the UserSuppliedHaloCatalog class without raising an exception then this automatically guarantees that the instance can be passed to the Halotools model factories to populate mock galaxies into the catalog. However, different Halotools models require different halo properties to be available. For example, HOD-style models typically only use host halos, and so those models must make some assumption for how to identify which elements of your halo catalog are host halos, and which are subhalos. Other models such as age matching require knowledge of some measure of halo formation time. If you are interested in using your simulation with a specific galaxy-halo model, be sure to check the documentation of that model so that you can properly format your halo catalog.

Storing a UserSuppliedHaloCatalog in cache

All instances of the UserSuppliedHaloCatalog class have a add_halocat_to_cache method that can be used to store your catalog for convenient future use. If you call this method and no exceptions are raised, from then on you will be able to load your halo catalog into memory with the CachedHaloCatalog class using the exact same syntax as you would use to load one of the Halotools-provided catalogs.