radial_profile_3d

halotools.mock_observables.radial_profile_3d(sample1, sample2, sample2_quantity, rbins_absolute=None, rbins_normalized=None, normalize_rbins_by=None, return_counts=False, period=None, num_threads=1, approx_cell1_size=None, approx_cell2_size=None)

Function used to calculate the mean value of some quantity in sample2 as a function of 3d distance from the points in sample1.

As illustrated in the Examples section below, and also in Halo Catalog Analysis Example: calculating radial profiles, the normalize_rbins_by argument allows you to optionally normalize the 3d distances according to some scaling factor defined by the points in sample1. The documentation below shows how to calculate the mean mass accretion rate of sample2 as a function of \(r / R_{\rm vir}\), the Rvir-normalized halo-centric distance from points in sample1.

Note that this function can also be used to calculate number density profiles of sample2 points as a function of halo-centric distance from sample1 points. If you are only interested in number counts, you can pass in any dummy array for the input sample2_quantity, and set the return_counts argument to True. See the Examples below for an explicit demonstration.

Parameters:

sample1array_like

Length-Npts1 x 3 numpy array containing 3-D positions of points. See the Formatting your xyz coordinates for Mock Observables calculations documentation page, or the Examples section below, for instructions on how to transform your coordinate position arrays into the format accepted by the sample1 and sample2 arguments. Length units are comoving and assumed to be in Mpc/h, here and throughout Halotools.

sample2array_like, optional

Length-Npts2 x 3 array containing 3-D positions of points.

sample2_quantity: array_like

Length-Npts2 array containing the sample2 quantity whose mean value is being calculated as a function of distance from points in sample1.

rbins_absolutearray_like, optional

Array of length Nrbins+1 defining the boundaries of bins in which mean quantities and number counts are computed.

Either rbins_absolute must be passed, or rbins_normalized and normalize_rbins_by must be passed.

Length units are comoving and assumed to be in Mpc/h, here and throughout Halotools.

rbins_normalizedarray_like, optional

Array of length Nrbins+1 defining the bin boundaries x, where \(x = r / R_{\rm vir}\), in which mean quantities and number counts are computed. The quantity \(R_{\rm vir}\) can vary from point to point in sample1 and is passed in via the normalize_rbins_by argument. While scaling by \(R_{\rm vir}\) is common, you are not limited to this normalization choice; in principle you can use the rbins_normalized and normalize_rbins_by arguments to scale your distances by any length-scale associated with points in sample1. Default is None, in which case the rbins_absolute argument must be passed.

normalize_rbins_byarray_like, optional

Numpy array of length Npts1 defining how the distance between each pair of points will be normalized. For example, if normalize_rbins_by is defined to be the virial radius of each point in sample1, then the input numerical values x stored in rbins_normalized will be interpreted as referring to bins of \(x = r / R_{\rm vir}\). Default is None, in which case the input rbins_absolute argument must be passed instead of rbins_normalized.

Pay special attention to length-units in whatever halo catalog you are using: while Halotools-provided catalogs will always have length units pre-processed to be Mpc/h, commonly used default settings for ASCII catalogs produced by Rockstar return the Rvir column in kpc/h units, but halo centers in Mpc/h units.

return_countsbool, optional

If set to True, radial_profile_3d will additionally return the number of pairs in each separation bin. Default is False.

periodarray_like, optional

Length-3 sequence defining the periodic boundary conditions in each dimension. If you instead provide a single scalar, Lbox, period is assumed to be the same in all Cartesian directions.

num_threadsint, optional

Number of threads to use in calculation, where parallelization is performed using the python multiprocessing module. Default is 1 for a purely serial calculation, in which case a multiprocessing Pool object will never be instantiated. A string ‘max’ may be used to indicate that the pair counters should use all available cores on the machine.

approx_cell1_sizearray_like, optional

Length-3 array serving as a guess for the optimal manner by how points will be apportioned into subvolumes of the simulation box. The optimum choice unavoidably depends on the specs of your machine. Default choice is to use Lbox/10 in each dimension, which will return reasonable result performance for most use-cases. Performance can vary sensitively with this parameter, so it is highly recommended that you experiment with this parameter when carrying out performance-critical calculations.

approx_cell2_sizearray_like, optional

Analogous to approx_cell1_size, but for sample2. See comments for approx_cell1_size for details.

Returns:

resultarray_like

Numpy array of length Nrbins containing the mean value of sample2_quantity as a function of 3d distance from the points in sample1.

countsarray_like, optional

Numpy array of length Nrbins containing the number of pairs of points in sample1 and sample2 as a function of 3d distance from the points. Only returned if return_counts is set to True (default is False).

See also

Halo Catalog Analysis Example: calculating radial profiles

Examples

In this example, we’ll select two samples of halos, and calculate how the mass accretion of halos in the second set varies as a function of distance from the halos in the first set. For demonstration purposes we’ll use fake halos provided by FakeSim, but the same syntax works for real halos, and likewise for a mock galaxy catalog.

>>> from halotools.sim_manager import FakeSim
>>> halocat = FakeSim()
>>> median_mass = np.median(halocat.halo_table['halo_mvir'])
>>> sample1_mask = halocat.halo_table['halo_mvir'] > median_mass
>>> halo_sample1 = halocat.halo_table[sample1_mask]
>>> halo_sample2 = halocat.halo_table[~sample1_mask]

We transform our x, y, z points into the array shape used by the pair-counter by taking the transpose of the result of numpy.vstack. This boilerplate transformation is used throughout the mock_observables sub-package:

>>> sample1 = np.vstack([halo_sample1['halo_x'], halo_sample1['halo_y'], halo_sample1['halo_z']]).T
>>> sample2 = np.vstack([halo_sample2['halo_x'], halo_sample2['halo_y'], halo_sample2['halo_z']]).T
>>> dmdt_sample2 = halo_sample2['halo_mass_accretion_rate']

>>> rbins_absolute = np.logspace(-1, 1.5, 15)
>>> result1 = radial_profile_3d(sample1, sample2, dmdt_sample2, rbins_absolute=rbins_absolute, period=halocat.Lbox)

The array result1 contains the mean mass accretion rate of halos in sample2 in the bins of distance from halos in sample1 determined by rbins_absolute.

You can retrieve the number counts in these separation bins as follows:

>>> result1, counts = radial_profile_3d(sample1, sample2, dmdt_sample2, rbins_absolute=rbins_absolute, period=halocat.Lbox, return_counts=True)

Now suppose that you wish to calculate the same quantity, but instead as a function of \(x = r / R_{\rm vir}\). In this case, we use the rbins_normalized and normalize_rbins_by arguments. The following choices for these arguments will give us 15 separation bins linearly spaced in x between \(\frac{1}{2}R_{\rm vir}\) and \(10R_{\rm vir}\).

>>> rvir = halo_sample1['halo_rvir']
>>> rbins_normalized = np.linspace(0.5, 10, 15)
>>> result1 = radial_profile_3d(sample1, sample2, dmdt_sample2, rbins_normalized=rbins_normalized, normalize_rbins_by=rvir, period=halocat.Lbox)