random_indices_within_bin

halotools.utils.random_indices_within_bin(binned_multiplicity, desired_binned_occupations, seed=None, min_required_entries_per_bin=None)

Given two equal-length arrays, with desired_binned_occupations defining the number of desired random draws per bin, and binned_multiplicity defining the number of indices in each bin that are available to be randomly drawn, return a set of indices such that only the appropriate indices will be drawn for each bin, and the total number of such random draws is in accord with the input desired_binned_occupations.

The random_indices_within_bin function is the kernel of the calculation in which satellites are assigned to host halos that do not have enough subhalos to serve as satellites. The algorithm implemented here enables, for example, the random selection of a subhalo that resides in a host of a nearby mass.

Parameters:

binned_multiplicityarray

Array of length-Nbins storing how many total items reside in each bin.

All entries of binned_multiplicity must be at least as large as min_required_entries_per_bin, enforcing a user-specified requirement that in each bin, you must have “enough” entries to draw from.

desired_binned_occupationsarray

Array of length-Nbins of non-negative integers storing the number of times to draw from each bin.

seedinteger, optional

Random number seed used when drawing random numbers with numpy.random. Useful when deterministic results are desired, such as during unit-testing. Default is None, producing stochastic results.

min_required_entries_per_binint, optional

Minimum requirement on the number of entries in each bin. Default is 1. This requirement is only applied for bins with non-zero values of desired_binned_occupations.

Returns:

indicesarray

Integer array of length equal to desired_binned_occupations.sum() whose values can be used to index the appropriate entries of the subhalo table.

Examples

>>> binned_multiplicity = np.array([1, 2, 2, 1, 3])
>>> desired_binned_occupations = np.array([2, 1, 3, 0, 2])
>>> idx = random_indices_within_bin(binned_multiplicity, desired_binned_occupations)

The idx array has desired_binned_occupations.sum() total entries, with each entry storing the index of the subhalo table that will serve as a randomly selected satellite.