underdensity_prob_func¶
- halotools.mock_observables.underdensity_prob_func(sample1, rbins, n_ran=None, random_sphere_centers=None, period=None, sample_volume=None, u=0.2, num_threads=1, approx_cell1_size=None, approx_cellran_size=None, seed=None)[source]¶
Calculate the underdensity probability function (UPF), \(P_U(r)\).
\(P_U(r)\) is defined as the probability that a randomly placed sphere of size \(r\) encompases a volume with less than a specified number density.
See the Formatting your xyz coordinates for Mock Observables calculations documentation page for instructions on how to transform your coordinate position arrays into the format accepted by the
sample1
argument.See also Galaxy Catalog Analysis Example: Void probability function.
- Parameters:
- sample1array_like
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.- rbinsfloat
size of spheres to search for neighbors Length units are comoving and assumed to be in Mpc/h, here and throughout Halotools.
- n_ranint, optional
integer number of randoms to use to search for voids. If
n_ran
is not passed, you must passrandom_sphere_centers
.- random_sphere_centersarray_like, optional
Npts x 3 array of randomly selected positions to drop down spheres to use to measure the
void_prob_func
. Ifrandom_sphere_centers
is not passed,n_ran
must be passed.- 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. If set to None, PBCs are set to infinity, in which case
sample_volume
must be specified so that the global mean density can be estimated. In this case, it is still necessary to drop down randomly placed spheres in order to compute the UPF. To do so, the spheres will be dropped inside a cubical box whose sides are defined by the smallest/largest coordinate distance of the inputsample1
. Length units are comoving and assumed to be in Mpc/h, here and throughout Halotools.- sample_volumefloat, optional
If period is set to None, you must specify the effective volume of the sample. Length units are comoving and assumed to be in Mpc/h, here and throughout Halotools.
- ufloat, optional
density threshold in units of the mean object density
- num_threadsint, optional
number of ‘threads’ to use in the pair counting. if set to ‘max’, use all available cores. num_threads=0 is the default.
- 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 max(rbins) 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_cellran_sizearray_like, optional
Analogous to
approx_cell1_size
, but for used for randoms. See comments forapprox_cell1_size
for details.- seedint, optional
Random number seed used to randomly lay down spheres, if applicable. Default is None, in which case results will be stochastic.
- Returns:
- upfnumpy.array
len(rbins) length array containing the underdensity probability function \(P_U(r)\) computed for each \(r\) defined by input
rbins
.
Notes
This function requires the calculation of the number of pairs per randomly placed sphere, and thus storage of an array of shape(n_ran,len(rbins)). This can be a memory intensive process as this array becomes large.
Examples
For demonstration purposes we create a randomly distributed set of points within a periodic unit cube.
>>> Npts = 10000 >>> Lbox = 1.0 >>> period = np.array([Lbox,Lbox,Lbox])
>>> x = np.random.random(Npts) >>> y = np.random.random(Npts) >>> z = np.random.random(Npts)
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:>>> coords = np.vstack((x,y,z)).T
>>> rbins = np.logspace(-2,-1,20) >>> n_ran = 1000 >>> upf = underdensity_prob_func(coords, rbins, n_ran=n_ran, period=period, u=0.2)