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)[source]¶
Function used to calculate the mean value of some quantity in
sample2
as a function of 3d distance from the points insample1
.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 insample1
. The documentation below shows how to calculate the mean mass accretion rate ofsample2
as a function of \(r / R_{\rm vir}\), the Rvir-normalized halo-centric distance from points insample1
.Note that this function can also be used to calculate number density profiles of
sample2
points as a function of halo-centric distance fromsample1
points. If you are only interested in number counts, you can pass in any dummy array for the inputsample2_quantity
, and set thereturn_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
andsample2
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 insample1
.- 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, orrbins_normalized
andnormalize_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 thenormalize_rbins_by
argument. While scaling by \(R_{\rm vir}\) is common, you are not limited to this normalization choice; in principle you can use therbins_normalized
andnormalize_rbins_by
arguments to scale your distances by any length-scale associated with points insample1
. Default is None, in which case therbins_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 insample1
, then the input numerical values x stored inrbins_normalized
will be interpreted as referring to bins of \(x = r / R_{\rm vir}\). Default is None, in which case the inputrbins_absolute
argument must be passed instead ofrbins_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 forapprox_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 insample1
.- countsarray_like, optional
Numpy array of length Nrbins containing the number of pairs of points in
sample1
andsample2
as a function of 3d distance from the points. Only returned ifreturn_counts
is set to True (default is False).
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 themock_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 insample2
in the bins of distance from halos insample1
determined byrbins_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
andnormalize_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)