.. _leauthaud11_composite_model:
*********************************************
Leauthaud et al. (2011) Composite Model
*********************************************
.. currentmodule:: halotools.empirical_models
This section of the documentation describes the basic behavior of
the ``leauthaud11`` composite HOD model. To see how this composite
model is built by the `~halotools.empirical_models.PrebuiltHodModelFactory` class,
see `~halotools.empirical_models.leauthaud11_model_dictionary`.
Overview of the Leauthaud et al. (2011) Model Features
========================================================
This HOD-style model is based on Leauthaud et al. (2011), arXiv:1103.2077.
The behavior of this model is governed by an assumed underlying stellar-to-halo-mass relation.
There are two populations, centrals and satellites.
Central occupation statistics are given by a nearest integer distribution
with first moment given by an ``erf`` function; the class governing this
behavior is `~halotools.empirical_models.Leauthaud11Cens`.
Central galaxies are assumed to reside at the exact center of the host halo;
the class governing this behavior is `~halotools.empirical_models.TrivialPhaseSpace`.
Satellite occupation statistics are given by a Poisson distribution
with first moment given by a power law that has been truncated at the low-mass end;
the class governing this behavior is `~halotools.empirical_models.Leauthaud11Sats`;
satellites in this model follow an (unbiased) NFW profile, as governed by the
`~halotools.empirical_models.NFWPhaseSpace` class.
Building the Leauthaud et al. (2011) Model
============================================
You can build an instance of this model using the
`~halotools.empirical_models.PrebuiltHodModelFactory` class as follows:
>>> from halotools.empirical_models import PrebuiltHodModelFactory
>>> model = PrebuiltHodModelFactory('leauthaud11')
Customizing the Leauthaud et al. (2011) Model
=================================================
There are two keyword arguments you can use to customize
the instance returned by the factory:
First, the ``threshold`` keyword argument pertains to the minimum
stellar mass of the galaxy sample, in logarithmic units of Msun in h=1 units:
>>> model = PrebuiltHodModelFactory('leauthaud11', threshold = 10.75)
Second, the ``redshift`` keyword argument must be set to the redshift of the
halo catalog you might populate with this model.
>>> model = PrebuiltHodModelFactory('leauthaud11', threshold = 11, redshift = 2)
It is not permissible to dynamically change the ``threshold`` and ``redshift``
of the model instance. If you want to explore the effects of different
thresholds and redshifts, you should instantiate multiple models.
As described in :ref:`altering_param_dict`, you can always change the model parameters
after instantiation by changing the values in the ``param_dict`` dictionary. For example,
>>> model.param_dict['alphasat'] = 1.1
The above line of code changes the power law slope between
halo mass and satellite occupation number, :math:`\langle N_{\rm sat} \rangle \propto M_{\rm halo}^{\alpha}`.
See :ref:`leauthaud11_parameters` for a description of all parameters of this model.
Populating Mocks and Generating Leauthaud et al. (2011) Model Predictions
===========================================================================
As with any Halotools composite model, the model instance
can populate N-body simulations with mock galaxy catalogs.
In the following, we'll show how to do this
with fake simulation data via the ``halocat`` argument.
>>> from halotools.sim_manager import FakeSim
>>> halocat = FakeSim()
>>> model = PrebuiltHodModelFactory('leauthaud11')
>>> model.populate_mock(halocat) # doctest: +SKIP
See `ModelFactory.populate_mock` for information about how to
populate your model into different simulations.
See :ref:`galaxy_catalog_analysis_tutorial` for a sequence of worked examples
on how to use the `~halotools.mock_observables` sub-package
to study a wide range of astronomical statistics predicted by your model.
Studying the Leauthaud et al. (2011) Model Features
======================================================
In addition to populating mocks, the ``leauthaud11`` model also gives you access to
its underlying analytical relations. Here are a few examples:
>>> import numpy as np
>>> halo_mass = np.logspace(11, 15, 100)
To compute the mean number of each galaxy type as a function of halo mass:
>>> mean_ncen = model.mean_occupation_centrals(prim_haloprop = halo_mass)
>>> mean_nsat = model.mean_occupation_satellites(prim_haloprop = halo_mass)
To compute the mean stellar mass of central galaxies as a function of halo mass:
>>> mean_sm_cens = model.mean_stellar_mass_centrals(prim_haloprop = halo_mass)
Now suppose you wish to know the mean halo mass of a central galaxy with known stellar mass:
>>> log_stellar_mass = np.linspace(9, 12, 100)
>>> inferred_log_halo_mass = model.mean_log_halo_mass_centrals(log_stellar_mass)
.. _leauthaud11_parameters:
Parameters of the Leauthaud et al. (2011) model
=================================================
The best way to learn what the parameters of a model do is to
just play with the code: change parameter values, make plots of how the
underying analytical relations vary, and also of how the
mock observables vary. Here we just give a simple description of the meaning
of each parameter. You can also refer to the original
Leauthaud et al. (2011) publication, arXiv:1103.2077, and also the original
Behroozi et al. (2010) publication, arXiv:1001.0015,
for further details. A succinct summary also appears in Section 2.4 of arXiv:1512.03050.
To see how the following parameters are implemented, see `Leauthaud11Cens.mean_occupation` and `Behroozi10SmHm.mean_stellar_mass`.
* param_dict['smhm_m0_0'] - Characteristic stellar mass at redshift-zero in the :math:`\langle M_{\ast} \rangle(M_{\rm halo})` map.
* param_dict['smhm_m0_a'] - Redshift evolution of the characteristic stellar mass.
* param_dict['smhm_m1_0'] - Characteristic halo mass at redshift-zero in the :math:`\langle M_{\ast} \rangle(M_{\rm halo})` map.
* param_dict['smhm_m1_a'] - Redshift evolution of the characteristic halo mass.
* param_dict['smhm_beta_0'] - Low-mass slope at redshift-zero of the :math:`\langle M_{\ast} \rangle(M_{\rm halo})` map.
* param_dict['smhm_beta_a'] - Redshift evolution of the low-mass slope.
* param_dict['smhm_delta_0'] - High-mass slope at redshift-zero of the :math:`\langle M_{\ast} \rangle(M_{\rm halo})` map.
* param_dict['smhm_delta_a'] - Redshift evolution of the high-mass slope.
* param_dict['smhm_gamma_0'] - Transition between low- and high-mass behavior at redshift-zero of the :math:`\langle M_{\ast} \rangle(M_{\rm halo})` map.
* param_dict['smhm_gamma_a'] - Redshift evolution of the transition.
* param_dict['u'scatter_model_param1'] - Log-normal scatter in the stellar-to-halo mass relation.
To see how the following parameters are implemented, see `Leauthaud11Sats.mean_occupation` and `Behroozi10SmHm.mean_stellar_mass`.
* param_dict['alphasat'] - Power law slope of the relation between halo mass and :math:`\langle N_{\rm sat} \rangle`.
* param_dict['betasat'] - Controls the amplitude of the power law slope :math:`\langle N_{\rm sat} \rangle`.
* param_dict['bsat'] - Also controls the amplitude of the power law slope :math:`\langle N_{\rm sat} \rangle`.
* param_dict['betacut'] - Controls the low-mass cutoff of :math:`\langle N_{\rm sat} \rangle`.
* param_dict['bcut'] - Also controls the low-mass cutoff of :math:`\langle N_{\rm sat} \rangle`.