HaloCat

HaloCat is defined in halocat/halo_cat.py and is the main data container used throughout the package.

Constructor

HaloCat(
    fields=None,
    *,
    boxsize=None,
    redshift=None,
    periodic=True,
    cosmology=None,
    metadata=None,
    units=None,
    copy=False,
    **named_fields,
)

Important constructor behavior:

• Fields can be passed as a dictionary or as named keyword arrays.
• Vector fields can be given as positions / pos and velocities / vel with shape (N, 3).
• All stored fields must be one-dimensional and must have the same length.
• boxsize may be a scalar, a length-3 sequence, or a mapping with keys x, y, and z.
• A scalar boxsize is expanded internally to a length-3 array.
• Field arrays are copied only when copy=True.

Core API

Construction and persistence:

• HaloCat.from_file(path, ...)
• cat.save(path, ...)
• cat.copy(deep=True)

Inspection:

• len(cat)
• cat.summary()
• cat.field_names
• cat.size
• cat.has_field(name)
• cat.get_field(name)
• cat.get_positions()
• cat.get_velocities()

Mutation:

• cat.add_field(name, values)

Selections:

• cat.select(mask)
• cat.select_by_mass(mmin=None, mmax=None)
• cat.select_by_field(field, min_value=None, max_value=None, values=None)
• cat.select_region(x=None, y=None, z=None)

Conversion helpers:

• cat.to_dict()
• cat.to_dataframe()

Measurement aliases:

• cat.measure_hmf(...)
• cat.measure_chmf(...)
• cat.measure_dhmf(...)
• cat.measure_dndlog10M(...)
• cat.measure_2PCF(...)
• cat.measure_velocity_moments(...)
• cat.measure_binned_statistic(...)
• cat.measure_bias(...)

Metadata

The object stores:

• boxsize
• redshift
• periodic
• cosmology
• metadata
• units

The default units dictionary follows the conventions used in the older scripts:

• x, y, z: Mpc/h
• vx, vy, vz: km/s
• mass: Msun/h

summary() returns a dictionary containing:

• size
• fields
• boxsize
• redshift
• periodic
• units

File loading

HaloCat.from_file(...) is a thin wrapper around halocat.io.load_catalog_file(...).

Supported input formats are:

• bdm
• hdf5
• npz
• npy
• csv
• text

If format is omitted, it is inferred from the file suffix.

Metadata stored on disk can populate:

• boxsize
• redshift
• periodic
• cosmology
• units

Explicit keyword arguments passed to from_file(...) override metadata loaded from disk.

Example

import numpy as np

from halocat import HaloCat

cat = HaloCat(
    positions=np.array([[0.0, 0.0, 0.0], [5.0, 0.0, 0.0], [8.0, 0.0, 0.0]]),
    velocities=np.array([[100.0, 0.0, 0.0], [120.0, 0.0, 0.0], [90.0, 0.0, 0.0]]),
    mass=np.array([1.0e12, 2.0e12, 6.0e12]),
    halo_id=np.array([11, 12, 13]),
    boxsize=1024.0,
    redshift=0.25,
)

massive = cat.select_by_mass(1.5e12, 1.0e13)
massive.add_field("log10mass", np.log10(massive.get_field("mass")))

print(massive.summary())