Skip to content

Loaders

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.

Functions
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.