Dataset registry

This page documents 13 public symbols. Each entry includes its purpose, import path, full API docstring, and the maintained example that exercises it.

Conceptual guide

load_dataset

Load a bundled example dataset by name.

Property	Value
Type	function
Import	from pygwrx.io import load_dataset
Signature	load_dataset(name: str, return_type: str = 'frame', data_dir: Union[str, os.PathLike[str], NoneType] = None, dropna: bool = True) -> Any
Maintained example	examples/io/01_bundled_datasets.py

load_dataset

load_dataset(
    name: str,
    return_type: str = "frame",
    data_dir: Optional[Union[str, PathLike[str]]] = None,
    dropna: bool = True,
) -> Any

Load a bundled example dataset by name.

Load an example dataset distributed with pyGWRx.

Parameters:

Name	Type	Description	Default
name	str	Canonical dataset name or registered alias.	required
return_type	str	'frame' returns the raw frame; 'arrays' returns (X, y, coords); 'dict' returns aligned modelling arrays, metadata and both filtered/raw frames; 'path' returns the absolute file path without reading the dataset.	'frame'
data_dir	Optional[Union[str, PathLike[str]]]	Override the bundled data directory.	None
dropna	bool	For 'arrays' and 'dict', remove rows containing non-finite modelling values or coordinates. This option does not alter the raw frame returned by return_type='frame'.	True

Returns:

Type	Description
Any	DataFrame | GeoDataFrame | tuple | dict | str: The requested dataset representation.

Source code in src/pygwrx/io/datasets.py

def load_dataset(
    name: str,
    return_type: str = "frame",
    data_dir: Optional[Union[str, PathLike[str]]] = None,
    dropna: bool = True,
) -> Any:
    """Load a bundled example dataset by name.

    Load an example dataset distributed with pyGWRx.

    Args:
        name: Canonical dataset name or registered alias.
        return_type: ``'frame'`` returns the raw frame; ``'arrays'`` returns
            ``(X, y, coords)``; ``'dict'`` returns aligned modelling arrays,
            metadata and both filtered/raw frames; ``'path'`` returns the absolute
            file path without reading the dataset.
        data_dir: Override the bundled data directory.
        dropna: For ``'arrays'`` and ``'dict'``, remove rows containing non-finite
            modelling values or coordinates. This option does not alter the raw
            frame returned by ``return_type='frame'``.

    Returns:
        DataFrame | GeoDataFrame | tuple | dict | str: The requested dataset representation.
    """
    key = _resolve_name(name)
    normalized_return_type = _normalize_return_type(return_type)
    dropna = _validate_dropna(dropna)

    spec = _DATASETS[key]
    path = _get_data_dir(data_dir).joinpath(*spec["path"]).resolve()

    if not path.exists():
        raise FileNotFoundError(
            f"Dataset '{key}' was not found at:\n  {path}\n"
            "The example datasets are normally bundled with pyGWRx. If this "
            "file is missing, set PYGWRX_DATA_DIR or pass data_dir=... .\n"
            f"Source: {spec['reference']}"
        )
    if not path.is_file():
        raise FileNotFoundError(f"Dataset path is not a file: {path}")

    if normalized_return_type == "path":
        # Preserve the original public contract: path results are strings.
        return str(path)

    frame = _read_frame(spec, path)

    if normalized_return_type == "frame":
        return frame

    needed: List[str] = list(spec["features"]) + [spec["response"]]
    missing = [column for column in needed if column not in frame.columns]
    if missing:
        raise ValueError(
            f"Dataset '{key}' is missing expected columns {missing}. "
            f"Available columns: {list(frame.columns)}"
        )

    coords_all = _extract_coords(frame, spec)
    numeric = frame[needed].apply(pd.to_numeric, errors="coerce")
    numeric_values = numeric.to_numpy(dtype=float)

    if dropna:
        valid_mask = np.isfinite(numeric_values).all(axis=1)
        valid_mask &= np.isfinite(coords_all).all(axis=1)
    else:
        valid_mask = np.ones(len(frame), dtype=bool)

    if not np.any(valid_mask):
        raise ValueError(
            f"Dataset '{key}' contains no usable rows after applying dropna={dropna}."
        )

    model_frame = frame.loc[valid_mask].copy()
    model_numeric = numeric.loc[valid_mask]
    coords = np.asarray(coords_all[valid_mask], dtype=float)
    X = model_numeric[spec["features"]].to_numpy(dtype=float)
    y = model_numeric[spec["response"]].to_numpy(dtype=float)

    if normalized_return_type == "arrays":
        return X, y, coords

    file_crs = _frame_crs(frame)
    return {
        "data": X,
        "target": y,
        "coords": coords,
        "feature_names": list(spec["features"]),
        "target_name": spec["response"],
        # frame is deliberately aligned with data/target/coords.
        "frame": model_frame,
        "raw_frame": frame,
        "row_index": model_frame.index.to_numpy(copy=True),
        "description": spec["name"],
        "description_zh": spec["name_zh"],
        "n_samples": int(len(y)),
        "registered_n_samples": int(spec["n_samples"]),
        "n_features": len(spec["features"]),
        "filepath": str(path),
        "spatial_unit": spec["spatial_unit"],
        "study_area": spec["study_area"],
        # Keep the historical `crs` key as the registry/declaration value and
        # expose the CRS actually read from a spatial file separately.
        "crs": spec["crs"],
        "declared_crs": spec["crs"],
        "file_crs": file_crs,
        "reference": spec["reference"],
        "license": spec["license"],
        "source_url": spec["source_url"],
        "processing": spec["processing"],
        "source_version": spec["source_version"],
        "source_release_date": spec["source_release_date"],
        "source_revision": spec["source_revision"],
        "source_path": spec["source_path"],
        "evidence_date": spec["evidence_date"],
        "integrity": spec["integrity"],
    }

load_dublin_voter

Load the Dublin voter turnout dataset. See :func:load_dataset.

Property	Value
Type	function
Import	from pygwrx.io import load_dublin_voter
Signature	load_dublin_voter(return_type: str = 'frame', **kwargs: Any) -> Any
Maintained example	examples/io/01_bundled_datasets.py

load_dublin_voter

load_dublin_voter(
    return_type: str = "frame", **kwargs: Any
) -> Any

Load the Dublin voter turnout dataset. See :func:load_dataset.

Source code in src/pygwrx/io/datasets.py

def load_dublin_voter(return_type: str = "frame", **kwargs: Any) -> Any:
    """Load the Dublin voter turnout dataset. See :func:`load_dataset`."""
    return load_dataset("dublin_voter", return_type=return_type, **kwargs)

load_hiv

Load the county-level HIV prevalence dataset. See :func:load_dataset.

Property	Value
Type	function
Import	from pygwrx.io import load_hiv
Signature	load_hiv(return_type: str = 'frame', **kwargs: Any) -> Any
Maintained example	examples/io/01_bundled_datasets.py

load_hiv

load_hiv(return_type: str = 'frame', **kwargs: Any) -> Any

Load the county-level HIV prevalence dataset. See :func:load_dataset.

Source code in src/pygwrx/io/datasets.py

def load_hiv(return_type: str = "frame", **kwargs: Any) -> Any:
    """Load the county-level HIV prevalence dataset. See :func:`load_dataset`."""
    return load_dataset("hiv", return_type=return_type, **kwargs)

load_crime

Load the county-level crime dataset. See :func:load_dataset.

Property	Value
Type	function
Import	from pygwrx.io import load_crime
Signature	load_crime(return_type: str = 'frame', **kwargs: Any) -> Any
Maintained example	examples/io/01_bundled_datasets.py

load_crime

load_crime(
    return_type: str = "frame", **kwargs: Any
) -> Any

Load the county-level crime dataset. See :func:load_dataset.

Source code in src/pygwrx/io/datasets.py

def load_crime(return_type: str = "frame", **kwargs: Any) -> Any:
    """Load the county-level crime dataset. See :func:`load_dataset`."""
    return load_dataset("crime", return_type=return_type, **kwargs)

load_housing

Load the neighborhood house-price dataset. See :func:load_dataset.

Property	Value
Type	function
Import	from pygwrx.io import load_housing
Signature	load_housing(return_type: str = 'frame', **kwargs: Any) -> Any
Maintained example	examples/io/01_bundled_datasets.py

load_housing

load_housing(
    return_type: str = "frame", **kwargs: Any
) -> Any

Load the neighborhood house-price dataset. See :func:load_dataset.

Source code in src/pygwrx/io/datasets.py

def load_housing(return_type: str = "frame", **kwargs: Any) -> Any:
    """Load the neighborhood house-price dataset. See :func:`load_dataset`."""
    return load_dataset("housing", return_type=return_type, **kwargs)

load_columbus

Load the Columbus (OH) crime dataset. See :func:load_dataset.

Property	Value
Type	function
Import	from pygwrx.io import load_columbus
Signature	load_columbus(return_type: str = 'frame', **kwargs: Any) -> Any
Maintained example	examples/io/01_bundled_datasets.py

load_columbus

load_columbus(
    return_type: str = "frame", **kwargs: Any
) -> Any

Load the Columbus (OH) crime dataset. See :func:load_dataset.

Source code in src/pygwrx/io/datasets.py

def load_columbus(return_type: str = "frame", **kwargs: Any) -> Any:
    """Load the Columbus (OH) crime dataset. See :func:`load_dataset`."""
    return load_dataset("columbus", return_type=return_type, **kwargs)

load_ewhp

Load the England & Wales house-price dataset. See :func:load_dataset.

Property	Value
Type	function
Import	from pygwrx.io import load_ewhp
Signature	load_ewhp(return_type: str = 'frame', **kwargs: Any) -> Any
Maintained example	examples/io/01_bundled_datasets.py

load_ewhp

load_ewhp(return_type: str = 'frame', **kwargs: Any) -> Any

Load the England & Wales house-price dataset. See :func:load_dataset.

Source code in src/pygwrx/io/datasets.py

def load_ewhp(return_type: str = "frame", **kwargs: Any) -> Any:
    """Load the England & Wales house-price dataset. See :func:`load_dataset`."""
    return load_dataset("ewhp", return_type=return_type, **kwargs)

load_georgia

Load the Georgia educational-attainment dataset. See :func:load_dataset.

Property	Value
Type	function
Import	from pygwrx.io import load_georgia
Signature	load_georgia(return_type: str = 'frame', **kwargs: Any) -> Any
Maintained example	examples/io/01_bundled_datasets.py

load_georgia

load_georgia(
    return_type: str = "frame", **kwargs: Any
) -> Any

Load the Georgia educational-attainment dataset. See :func:load_dataset.

Source code in src/pygwrx/io/datasets.py

def load_georgia(return_type: str = "frame", **kwargs: Any) -> Any:
    """Load the Georgia educational-attainment dataset. See :func:`load_dataset`."""
    return load_dataset("georgia", return_type=return_type, **kwargs)

get_dublin_voter

Load the Dublin voter turnout dataset. See :func:load_dataset.

Property	Value
Type	function
Import	from pygwrx.io import get_dublin_voter
Signature	get_dublin_voter(return_type: str = 'frame', **kwargs: Any) -> Any
Maintained example	examples/io/01_bundled_datasets.py

get_dublin_voter module-attribute

get_dublin_voter = load_dublin_voter

load_dubvoter

Load the Dublin voter turnout dataset. See :func:load_dataset.

Property	Value
Type	function
Import	from pygwrx.io import load_dubvoter
Signature	load_dubvoter(return_type: str = 'frame', **kwargs: Any) -> Any
Maintained example	examples/io/01_bundled_datasets.py

load_dubvoter module-attribute

load_dubvoter = load_dublin_voter

get_dubvoter

Load the Dublin voter turnout dataset. See :func:load_dataset.

Property	Value
Type	function
Import	from pygwrx.io import get_dubvoter
Signature	get_dubvoter(return_type: str = 'frame', **kwargs: Any) -> Any
Maintained example	examples/io/01_bundled_datasets.py

get_dubvoter module-attribute

get_dubvoter = load_dublin_voter

get_dataset_info

Return registry metadata for a dataset without loading its data file.

Property	Value
Type	function
Import	from pygwrx.io import get_dataset_info
Signature	get_dataset_info(dataset_name: str = 'dublin_voter') -> Dict[str, Any]
Maintained example	examples/io/01_bundled_datasets.py

get_dataset_info

get_dataset_info(
    dataset_name: str = "dublin_voter",
) -> Dict[str, Any]

Return registry metadata for a dataset without loading its data file.

Source code in src/pygwrx/io/datasets.py

def get_dataset_info(dataset_name: str = "dublin_voter") -> Dict[str, Any]:
    """Return registry metadata for a dataset without loading its data file."""
    key = _resolve_name(dataset_name)
    spec = _DATASETS[key]
    relative_path = Path(*spec["path"])
    return {
        "key": key,
        "name": spec["name"],
        "name_zh": spec["name_zh"],
        "format": spec["format"],
        "n_samples": spec["n_samples"],
        "n_features": len(spec["features"]),
        "feature_names": list(spec["features"]),
        "target_name": spec["response"],
        "coords": tuple(spec["coords"]),
        "spatial_unit": spec["spatial_unit"],
        "study_area": spec["study_area"],
        "crs": spec["crs"],
        "declared_crs": spec["crs"],
        "aliases": list(spec.get("aliases", [])),
        "relative_path": str(relative_path),
        "reference": spec["reference"],
        "license": spec["license"],
        "source_url": spec["source_url"],
        "processing": spec["processing"],
        "source_version": spec["source_version"],
        "source_release_date": spec["source_release_date"],
        "source_revision": spec["source_revision"],
        "source_path": spec["source_path"],
        "evidence_date": spec["evidence_date"],
        "integrity": spec["integrity"],
        "loader_function": f"load_{key}",
        "readme": f"data/{spec['path'][0]}/README.md",
    }

list_datasets

List available built-in datasets and optionally print their metadata.

Property	Value
Type	function
Import	from pygwrx.io import list_datasets
Signature	list_datasets(verbose: bool = True) -> List[str]
Maintained example	examples/io/01_bundled_datasets.py

list_datasets

list_datasets(verbose: bool = True) -> List[str]

List available built-in datasets and optionally print their metadata.

Source code in src/pygwrx/io/datasets.py

def list_datasets(verbose: bool = True) -> List[str]:
    """List available built-in datasets and optionally print their metadata."""
    if not isinstance(verbose, (bool, np.bool_)):
        raise TypeError("verbose must be a boolean.")
    names = list(_DATASETS)
    if verbose:
        print("Available pyGWRx datasets:")
        print("=" * 70)
        for i, key in enumerate(names, 1):
            s = _DATASETS[key]
            print(f"{i}. {key}  —  {s['name']} / {s['name_zh']}")
            print(
                f"   n={s['n_samples']}, {len(s['features'])} features, "
                f"y='{s['response']}', {s['format']}  |  load_{key}()"
            )
        print("\nUse: load_dataset('<name>', return_type='arrays')")
    return names

Runnable examples used on this page

examples/io/01_bundled_datasets.py

# SPDX-FileCopyrightText: 2026 Jinghao Hu
# SPDX-License-Identifier: MIT

"""List, describe, and load every bundled dataset and compatibility alias."""

# Allow this script to run directly from any working directory.
import sys
from pathlib import Path

_PROJECT_ROOT = Path(__file__).resolve().parents[2]
_EXAMPLES_ROOT = _PROJECT_ROOT / "examples"
_SRC_ROOT = _PROJECT_ROOT / "src"
for _path in (_SRC_ROOT, _EXAMPLES_ROOT):
    if str(_path) not in sys.path:
        sys.path.insert(0, str(_path))

from pygwrx.io import (
    get_dataset_info,
    get_dublin_voter,
    get_dubvoter,
    list_datasets,
    load_columbus,
    load_crime,
    load_dataset,
    load_dublin_voter,
    load_dubvoter,
    load_ewhp,
    load_georgia,
    load_hiv,
    load_housing,
)

loaders = {
    "dublin_voter": load_dublin_voter,
    "hiv": load_hiv,
    "crime": load_crime,
    "housing": load_housing,
    "columbus": load_columbus,
    "ewhp": load_ewhp,
    "georgia": load_georgia,
}
print("datasets=", list_datasets(verbose=False))
for name, loader in loaders.items():
    info = get_dataset_info(name)
    frame = loader(return_type="frame")
    generic = load_dataset(name, return_type="frame")
    print(name, info["n_samples"], frame.shape, generic.shape)
print(
    "alias_shapes=",
    [
        fn(return_type="frame").shape
        for fn in (get_dublin_voter, load_dubvoter, get_dubvoter)
    ],
)