FoFGroups

class halotools.mock_observables.FoFGroups(positions, b_perp, b_para, period=None, Lbox=None, num_threads=1)[source]

Bases: object

Friends-of-friends (FoF) groups class.

Build FoF groups in redshift space assuming the distant observer approximation.

The first two dimensions (x, y) define the plane for perpendicular distances. The third dimension (z) is used for line-of-sight distances.

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 positions argument.

See also Galaxy Catalog Analysis Example: Galaxy group identification.

Parameters:
positionsarray_like

Npts x 3 numpy array containing 3-D positions of galaxies. Length units are comoving and assumed to be in Mpc/h, here and throughout Halotools.

b_perpfloat

Maximum linking length in the perpendicular direction, normalized to the mean separation between galaxies.

b_parafloat

Maximum linking length in the parallel direction, normalized to the mean separation between galaxies.

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. Length units are comoving and assumed to be in Mpc/h, here and throughout Halotools.

Lboxarray_like, optional

length 3 array defining boundaries of the simulation box.

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.

Examples

In this example we will populate the FakeSim with an HOD-style model to demonstrate how to use the group-finder.

>>> from halotools.sim_manager import FakeSim
>>> halocat = FakeSim()
>>> from halotools.empirical_models import PrebuiltHodModelFactory
>>> model = PrebuiltHodModelFactory('zheng07', threshold = -22)
>>> model.populate_mock(halocat)

Now that we have a mock galaxy catalog, we will extract the 3d coordinates of the galaxy positions and place this information into the shape of the multi-d array expected by the positions argument of FoFGroups using the return_xyz_formatted_array function.

>>> from halotools.mock_observables import return_xyz_formatted_array

Note that FoFGroups is based on 2+1 dimensional positions, with the z-dimension having a separate linking length from the xy-plane. To make our example more realistic, we will apply the redshift-space distortions to the z-coordinate when constructing the positions array.

>>> x = model.mock.galaxy_table['x']
>>> y = model.mock.galaxy_table['y']
>>> z = model.mock.galaxy_table['z']
>>> vz = model.mock.galaxy_table['vz']
>>> positions = return_xyz_formatted_array(x, y, z, velocity = vz, velocity_distortion_dimension = 'z', period=halocat.Lbox)

The b_perp and b_para arguments of FoFGroups control the linking lengths for the group-finding. The values passed for these variables are assumed to be in units of the mean number density of the input points, so that if you want your FoF linking length to be, say, 0.15 times the mean number density, then you should set b_perp to 0.15. Here we adopt the convention given in Berlind et al. (2006) and set b_perp to 0.14 and b_para to 0.75.

>>> b_perp, b_para = (0.14,0.75)
>>> groups = FoFGroups(positions, b_perp, b_para, period=halocat.Lbox)

Now that groups have been identified, we can create a new column of our galaxy_table storing the group ID that each galaxy belongs to.

>>> model.mock.galaxy_table['fof_group_ID'] = groups.group_ids

At this point, we are now in a position to calculate a large variety of group aggregation statistics with the fof_group_ID as our grouping key. The group_member_generator is designed for exactly such calculations. See Galaxy Catalog Analysis Example: Galaxy group identification for a tutorial showing how to use this generator to analyze galaxy groups.

Attributes Summary

group_ids

Determine integer IDs for groups.

n_groups

Calculate the total number of groups, including 1-member groups

Methods Summary

create_graph()

Create graph from FoF sparse matrix (requires igraph package).

get_betweenness()

Calculate the 'betweenness' of each galaxy vertex (requires igraph package).

get_degree()

Calculate the 'degree' of each galaxy vertex (requires igraph package).

get_edge_lengths()

Return the length of all edges (requires igraph package).

get_edges()

Return all edges of the graph (requires igraph package).

get_multiplicity()

Return the multiplicity of galaxies' group (requires igraph package).

Attributes Documentation

group_ids

Determine integer IDs for groups.

Each member of a group is assigned a unique integer ID that it shares with all connected group members.

Returns:
group_idsnp.array

array of group IDs for each galaxy

n_groups

Calculate the total number of groups, including 1-member groups

Returns:
N_groups: int

number of distinct groups

Methods Documentation

create_graph()[source]

Create graph from FoF sparse matrix (requires igraph package).

get_betweenness()[source]

Calculate the ‘betweenness’ of each galaxy vertex (requires igraph package).

Returns:
betweenessnp.array

the ‘betweenness’ of galaxies in groups

get_degree()[source]

Calculate the ‘degree’ of each galaxy vertex (requires igraph package).

Returns:
degreenp.array

the ‘degree’ of galaxies in groups

get_edge_lengths()[source]

Return the length of all edges (requires igraph package).

Returns:
lengths: np.array

The length of an ‘edge’ econnnecting galaxies, i.e. distance between galaxies.

Notes

The length is caclulated as:

\[L_{\rm edge} = \sqrt{r_{\perp}^2 + r_{\parallel}^2},\]

where \(r_{\perp}\) and \(r_{\parallel}\) are the perendicular and parallel distance between galaixes.

get_edges()[source]

Return all edges of the graph (requires igraph package).

Returns:
edges: np.ndarray

N_edges x 2 array of vertices that are connected by an edge. The vertices are indicated by their index.

get_multiplicity()[source]

Return the multiplicity of galaxies’ group (requires igraph package).