Skip to content

Overview

loaders

File-backed population catalogue loaders.

Classes

FilePopulationLoader 

FilePopulationLoader(source_type: str, path: str | PathLike, *, column_map: dict[str, str] | None = None, hdf5_dataset: str = _HDF5_DATASET_NAME, cache_dir: str | PathLike[str] | None = None, refresh: bool = False, token: str | None = None, credentials: Mapping[str, str] | Mapping[str, Mapping[str, str]] | None = None, download_timeout: int = 300)

Load an external population catalogue from HDF5 or CSV.

The loader reads the input file eagerly during construction, normalizes the catalogue into a mapping of 1-D jax.Array columns, and then provides a :meth:simulate method that samples catalogue rows without replacement. This keeps the runtime surface compatible with :class:gwmock_pop.protocols.ExternalPopulationLoader and :class:gwmock_pop.protocols.GWPopSimulator without introducing a shared inheritance hierarchy.

Load and validate a population catalogue from disk or a remote URL.

Parameters:

Name Type Description Default
source_type str

Non-empty routing key used by downstream simulators, such as "bbh" or "bns".

 required
path str | PathLike

Path or supported URL to the input catalogue file. Supported local and remote formats are .hdf5, .h5, and .csv.

 required
column_map dict[str, str] | None

Optional mapping from file column names to canonical gwmock-pop parameter names. Keys must exist in the loaded catalogue.

 None
hdf5_dataset str

Dataset name to read from HDF5 files.

 _HDF5_DATASET_NAME
cache_dir str | PathLike[str] | None

Optional cache directory for remotely fetched catalogues.

 None
refresh bool

Whether to force a re-download for remote URLs even when a cached copy already exists.

 False
token str | None

Optional bearer token used for authenticated remote fetches.

 None
credentials Mapping[str, str] | Mapping[str, Mapping[str, str]] | None

Optional mapping of request headers or scheme-specific credential fields for remote fetches.

 None
download_timeout int

Timeout in seconds for HTTP(S) downloads.

 300

Raises:

Type Description
ValueError

If source_type is empty, the file format is unsupported, the file contents do not expose named columns, the column mapping is invalid, or the resulting catalogue is empty.
Attributes
parameter_names property 
parameter_names: list[str]

Return the stable ordered parameter names exposed by this loader.

Returns:

Type Description
list[str]

Sorted list of parameter names available in the loaded catalogue.
source_type property 
source_type: str

Return the routing key associated with this population catalogue.

Returns:

Type Description
str

Source type passed at construction time.
metadata property 
metadata: dict[str, Any]

Return loader metadata, including remote cache details when relevant.

provenance property 
provenance: dict[str, Any] | None

Return the provenance record the loaded catalogue carries, if any.

Returns:

Type Description
dict[str, Any] | None

The record found in or beside the input file, or None when the
dict[str, Any] | None

catalogue arrived undocumented.
Methods:
provenance_origin 
provenance_origin(engine: EngineDescription) -> dict[str, Any]

Describe this loaded catalogue as the origin of a new one.

The fetch details the loader already recorded for a remote catalogue -- URL, cache key and ETag -- are folded in rather than restated, and the record the input file carried is chained rather than dropped.

Parameters:

Name Type Description Default
engine EngineDescription

Identity of the engine that produced the input catalogue, including a pointer to that engine's own run record.

 required

Returns:

Type Description
dict[str, Any]

An origin block for :func:gwmock_pop.provenance.build_provenance_record.
simulate 
simulate(n_samples: int | None = None, **kwargs: Any) -> Mapping[str, Array]

Sample catalogue rows without replacement.

Parameters:

Name Type Description Default
n_samples int | None

Number of catalogue rows to draw. Pass None to return all rows in the catalogue.

 None
**kwargs Any

Optional backend-agnostic random-state hints. Supported keys include seed, key, and rng (in that priority).

 {}

Returns:

Type Description
Mapping[str, Array]

Mapping from parameter name to a 1-D jax.Array of sampled
Mapping[str, Array]

values.

Raises:

Type Description
ValueError

If n_samples is negative or exceeds the number of rows in the loaded catalogue.

Functions:

read_population_catalogue 

read_population_catalogue(path: str | PathLike, *, column_map: Mapping[str, str] | None = None, hdf5_dataset: str = _HDF5_DATASET_NAME) -> dict[str, np.ndarray]

Read a named-column population catalogue from disk.

write_population_catalogue 

write_population_catalogue(output_path: str | PathLike, population: Mapping[str, Array | ndarray], *, provenance: Mapping[str, Any] | None = None, compression: str | None = None) -> None

Persist a population mapping using named-column CSV/HDF5 conventions.

This is the only catalogue writer in the package, so every file it produces can carry the same record and none of them can drift into a private layout.

Parameters:

Name Type Description Default
output_path str | PathLike

Destination .csv, .h5, or .hdf5 file.

 required
population Mapping[str, Array | ndarray]

Mapping from parameter name to a 1-D column. Insertion order is the output column order.

 required
provenance Mapping[str, Any] | None

Record describing how the catalogue was produced, built by :func:gwmock_pop.provenance.build_provenance_record. HDF5 files carry it internally; CSV files get a JSON sidecar next to them.

 None
compression str | None

Optional HDF5 compression filter, such as "gzip". Ignored for CSV.

 None

Raises:

Type Description
ValueError

If the destination suffix names an unsupported format.