Skip to content

Overview

loaders

File-backed population catalogue loaders.

Classes

FetchResult dataclass 

FetchResult(path: Path, metadata: dict[str, Any])

Resolved file location and fetch metadata.

Attributes
path instance-attribute 
path: Path

Resolved file path.

metadata instance-attribute 
metadata: dict[str, Any]

Fetch metadata.

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:

is_population_url 

is_population_url(path: str | PathLike[str]) -> bool

Return whether path is a supported remote URL.

Parameters:

Name Type Description Default
path str | PathLike[str]

The path to check.

 required

Returns:

Type Description
bool

Whether the path is a supported remote URL.

resolve_digest_pinned_path 

resolve_digest_pinned_path(path: str | PathLike[str], *, sha256: str, size: int | None = None, filename: str | None = None, cache_dir: str | PathLike[str] | None = None, refresh: bool = False, offline: bool = False, timeout: int = 300) -> FetchResult

Resolve a remote URL into the cache, checking the bytes against a known digest.

Unlike :func:resolve_population_path, the cached copy is not trusted on the strength of its presence: its SHA-256 is recomputed and compared with sha256 on every call, so a truncated download or a file overwritten since it was cached is re-fetched rather than used. The identity of the bytes is the digest, not the URL, which is what makes an unversioned document-server URL safe to pin against. The cache key is the URL and the expected digest together, so one URL pinned at two digests keeps a separate cache entry per pin rather than the two colliding.

The digest is checked before the network is touched: a cache entry whose digest already matches is returned without a request, so the common path keeps working when the source is unreachable. A cold cache with offline=True raises rather than silently proceeding without the data.

Parameters:

Name Type Description Default
path str | PathLike[str]

Remote URL to fetch. http(s) and zenodo:// are supported.

 required
sha256 str

Expected lowercase or uppercase hex SHA-256 of the file contents.

 required
size int | None

Optional expected size in bytes, checked alongside the digest.

 None
filename str | None

File name the URL names, used to keep the cache suffix (the ET document server carries it in a query parameter rather than the path).

 None
cache_dir str | PathLike[str] | None

Cache directory. Defaults to the package cache location.

 None
refresh bool

Whether to re-download even when a matching entry is cached.

 False
offline bool

Whether to refuse network access and use only a matching cache.

 False
timeout int

Timeout in seconds for the download.

 300

Returns:

Type Description
FetchResult

The resolved path and fetch metadata, with verified true and
FetchResult

content_sha256 equal to the expected digest.

Raises:

Type Description
PopulationFetchError

If path is not a remote URL, if the scheme is unsupported for a pinned fetch, if the downloaded (or cached) bytes do not match the expected digest or size, or if the file is not cached while offline is set.

resolve_population_path 

resolve_population_path(path: str | PathLike[str], *, 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, timeout: int = 300) -> FetchResult

Resolve a local path or fetch a remote URL into the population cache.

Parameters:

Name Type Description Default
path str | PathLike[str]

The path to resolve.

 required
cache_dir str | PathLike[str] | None

The directory to cache the population in.

 None
refresh bool

Whether to refresh the cache.

 False
token str | None

The token to use for authentication.

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

The credentials to use for authentication.

 None
timeout int

The timeout for the request.

 300

Returns:

Type Description
FetchResult

The resolved path and fetch metadata.

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.