halotools.empirical_models.conditional_abunmatch_bin_based(haloprop, galprop, sigma=0.0, npts_lookup_table=1000, seed=None)[source]

Function used to model a correlation between two variables, haloprop and galprop, using conditional abundance matching (CAM).

The input galprop defines a PDF of the desired galaxy property being modeled. We will use the monte_carlo_from_cdf_lookup function to generate Monte Carlo realizations of this input PDF. If there are num_halos in the input haloprop array, we will draw num_halos times from this input PDF, and we will do so in such a way that larger values of galprop will be associated with larger values of haloprop. The returned array will thus be a Monte Carlo realization of the input galprop distribution, but a correlation between the halo property and galaxy property has been introduced. The strength of this correlation can be controlled with the input sigma.

An example application of this technique is age matching, in which it is supposed that earlier forming halos host earlier forming galaxies (See Hearin and Watson 2013). Alternative applications are numerous. For example, conditional abundance matching could be used to model a correlation between galaxy disk size and halo spin, or to model intrinsic alignments by introducing a correlation between halo and galaxy orientation.


Numpy array of shape (num_halos, ) typically storing a halo property


Numpy array of shape (num_gals, ) typically storing a galaxy property

sigmafloat, optional

Level of Gaussian noise that will be introduced to the haloprop–galprop correlation.

Default is 0, for a perfect monotonic relation between haloprop and galprop.

npts_lookup_tableint, optional

Size of the lookup table used to approximate the galprop distribution.

Default is 1000.

seedint, optional

Random number seed used to introduce noise in the haloprop–galprop correlation.

Default is None for stochastic results.


Numpy array of shape (num_halos, ) storing the modeled galprop-values associated with each value of the input haloprop.


To approximate the input galprop distribution, the implementation of conditional_abunmatch_bin_based builds a lookup table for the CDF of the input galprop using a simple call to numpy.interp, which can result in undesired edge case behavior if a large fraction of model galaxies lie outside the range of the data. To ensure your results are not impacted by this, make sure that num_gals >> npts_lookup_table. It is recommended that you always visually check histograms of the distribution of returned values against the desired distribution defined by galprop.

This function is not really intended for traditional abundance matching applications involving Schechter-like abundance functions such as the stellar-to-halo mass relation, where extrapolation at the exponentially decaying high-mass end requires special care. For code that provides careful treatment of this extrapolation in such cases, see the deconvolution abundance matching code written by Yao-Yuan Mao.

With the release of Halotools v0.7, this function had its name changed. The previous name given to this function was “conditional_abunmatch”. Halotools v0.7 has a new function conditional_abunmatch with this name that largely replaces the functionality here. See Tutorial on Conditional Abundance Matching demonstrating how to use the new function in galaxy-halo modeling with several worked examples.


Suppose we would like to do some CAM-style modeling of a correlation between some halo property haloprop and some galaxy property galprop. The conditional_abunmatch_bin_based function can be used to map values of the galaxy property onto the halos in such a way that the PDF of galprop is preserved and a correlation (of variable strength) between haloprop and galprop is introduced.

>>> num_halos_in_mpeak_bin = int(1e4)
>>> mean, size, std = -1.5, num_halos_in_mpeak_bin, 0.3
>>> spin_at_fixed_mpeak = 10**np.random.normal(loc=mean, size=size, scale=std)
>>> num_gals_in_mstar_bin = int(1e3)
>>> some_galprop_at_fixed_mstar = np.random.power(2.5, size=num_gals_in_mstar_bin)
>>> modeled_galprop = conditional_abunmatch_bin_based(spin_at_fixed_mpeak, some_galprop_at_fixed_mstar)