void_prob_func

halotools.mock_observables.void_prob_func(sample1, rbins, n_ran=None, random_sphere_centers=None, period=None, num_threads=1, approx_cell1_size=None, approx_cellran_size=None, seed=None)

Calculate the void probability function (VPF), \(P_0(r)\), defined as the probability that a random sphere of radius r contains zero points in the input sample.

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 and sample2 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 pass random_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. If random_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 this case, it is still necessary to drop down randomly placed spheres in order to compute the VPF. To do so, the spheres will be dropped inside a cubical box whose sides are defined by the smallest/largest coordinate distance of the input sample1. Length units are comoving and assumed to be in Mpc/h, here and throughout Halotools.

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_cellran_sizearray_like, optional

Analogous to approx_cell1_size, but for randoms. See comments for approx_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:

vpfnumpy.array

len(rbins) length array containing the void probability function \(P_0(r)\) computed for each \(r\) defined by input rbins.

See also

Galaxy Catalog Analysis Example: Void probability function

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 the mock_observables sub-package:

>>> coords = np.vstack((x,y,z)).T

>>> rbins = np.logspace(-2,-1,20)
>>> n_ran = 1000
>>> vpf = void_prob_func(coords, rbins, n_ran=n_ran, period=period)