Source code for cmdstanpy.stanfit.laplace

"""
Container for the result of running a laplace approximation.
"""

from __future__ import annotations

import json
import os
from collections.abc import Hashable, Mapping, Sequence
from dataclasses import dataclass, field
from pathlib import Path
from typing import Any, ClassVar, MutableMapping

import numpy as np
import pandas as pd

try:
    import xarray as xr

    XARRAY_INSTALLED = True
except ImportError:
    XARRAY_INSTALLED = False

from cmdstanpy.utils.data_munging import build_xarray_data
from cmdstanpy.utils.filesystem import accompanying_json

from .base import SingleFileFit
from .metadata import (
    AnyMethodConfig,
    LaplaceConfig,
    LaplaceRunConfig,
    StanConfig,
)
from .mle import CmdStanMLE

# TODO list:
# - docs and example notebook


def _validate_mode_compatible(
    laplace: StanConfig[AnyMethodConfig],
    mode: StanConfig[AnyMethodConfig],
    laplace_path: Path,
    mode_path: Path,
) -> None:
    """Validate the model, Stan version, and Jacobian of associated outputs."""
    if (
        laplace.model_name != mode.model_name
        or laplace.stan_major_version != mode.stan_major_version
        or laplace.stan_minor_version != mode.stan_minor_version
        or laplace.stan_patch_version != mode.stan_patch_version
    ):
        raise ValueError(
            f'Laplace config {laplace_path} and optimization mode config '
            f'{mode_path} do not describe the same model and Stan version.'
        )
    laplace_jacobian = getattr(laplace.method_config, 'jacobian', None)
    mode_jacobian = getattr(mode.method_config, 'jacobian', None)
    if laplace_jacobian != mode_jacobian:
        raise ValueError(
            f'Laplace config {laplace_path} and optimization mode config '
            f'{mode_path} disagree on the jacobian setting.'
        )


def _laplace_mode_name(
    config: StanConfig[AnyMethodConfig], config_path: Path
) -> str:
    method_config = config.method_config
    if not isinstance(method_config, LaplaceConfig):
        raise ValueError(f'Config JSON {config_path} is not from Laplace.')
    return Path(method_config.mode).name


def _discover_mode_files(
    config: StanConfig[AnyMethodConfig], config_path: Path, csv_file: Path
) -> tuple[Path, Path]:
    """Find mode files beside a managed bundle, ignoring stale paths."""
    mode_csv = config_path.parent / _laplace_mode_name(config, config_path)
    mode_config = Path(accompanying_json(mode_csv, 'config'))
    missing = [
        str(path)
        for path in (csv_file, mode_csv, mode_config)
        if not path.is_file()
    ]
    if missing:
        raise ValueError(
            f'Laplace fit for {config_path} is missing its Laplace '
            'CSV or optimization mode CSV/config JSON: '
            + ', '.join(missing)
            + '. Pass the Laplace and mode files explicitly, or call '
            'CmdStanLaplace.from_files().'
        )
    return mode_csv, mode_config


def _unique_csv_for_config(
    config: StanConfig[AnyMethodConfig],
    config_path: Path,
    csv_files: Sequence[Path],
    role: str,
) -> Path:
    names = {
        Path(name.strip()).name
        for name in config.output.file.split(',')
        if name.strip()
    }
    matches = [path for path in csv_files if path.name in names]
    if len(matches) != 1:
        raise ValueError(
            f'Cannot identify the {role} CSV associated with config JSON '
            f'{config_path} among the explicitly supplied files. Use the '
            'method-specific from_files() constructor for explicit association.'
        )
    return matches[0]


def _associate_laplace_files(
    configs: Mapping[Path, StanConfig[AnyMethodConfig]],
    csv_files: Sequence[Path],
) -> tuple[Path, Path, Path, Path]:
    """Return Laplace and mode CSV/config paths using only supplied files."""
    laplace_configs = [
        path
        for path, config in configs.items()
        if config.method_config.method == 'laplace'
    ]
    optimize_configs = [
        path
        for path, config in configs.items()
        if config.method_config.method == 'optimize'
    ]
    if (
        len(laplace_configs) != 1
        or len(optimize_configs) != 1
        or len(configs) != 2
    ):
        raise ValueError(
            'Explicit Laplace loading requires exactly one Laplace config JSON '
            'and the optimization mode config JSON. Alternatively call '
            'CmdStanLaplace.from_files() with an explicit mode object.'
        )
    if len(csv_files) != 2:
        raise ValueError(
            'Explicit Laplace loading requires the Laplace CSV and the '
            f'optimization mode CSV; found {len(csv_files)} CSV files.'
        )
    laplace_path = laplace_configs[0]
    mode_path = optimize_configs[0]
    laplace = configs[laplace_path]
    mode = configs[mode_path]
    _validate_mode_compatible(laplace, mode, laplace_path, mode_path)
    laplace_csv = _unique_csv_for_config(
        laplace, laplace_path, csv_files, 'Laplace'
    )
    mode_name = _laplace_mode_name(laplace, laplace_path)
    mode_matches = [path for path in csv_files if path.name == mode_name]
    if len(mode_matches) == 1:
        mode_csv = mode_matches[0]
    else:
        mode_csv = _unique_csv_for_config(mode, mode_path, csv_files, 'mode')
    if mode_csv == laplace_csv:
        raise ValueError('Laplace CSV and optimization mode CSV must differ.')
    return laplace_csv, laplace_path, mode_csv, mode_path


def _mode_from_files(
    mode_file: str, laplace_csv_file: str | os.PathLike
) -> CmdStanMLE:
    """Build a CmdStanMLE for the mode. If the provided mode output file isn't
    found, falls back to looking for a sibling file with the same name."""
    mode_csv = Path(mode_file)
    if not mode_csv.exists():
        sibling = Path(laplace_csv_file).parent / mode_csv.name
        if sibling.exists():
            mode_csv = sibling
        else:
            raise ValueError(
                f'Mode file {mode_file} recorded in the laplace config not '
                f'found.'
            )
    mode_config = Path(accompanying_json(mode_csv, 'config'))
    if not mode_config.exists():
        raise ValueError(
            f'No config file {mode_config.name} found alongside mode file '
            f'{mode_csv}.'
        )
    return CmdStanMLE.from_files(csv_file=mode_csv, config_file=mode_config)


[docs] @dataclass(kw_only=True) class CmdStanLaplace(SingleFileFit[LaplaceConfig]): """ Container for outputs from the Laplace approximation. Created by :meth:`CmdStanModel.laplace_sample`. """ mode: CmdStanMLE diagnostic_file: str | None = None _FILE_ATTRS: ClassVar[tuple[str, ...]] = ( 'csv_file', 'config_file', 'stdout_file', 'diagnostic_file', ) _hessian: np.ndarray | None = field(default=None, init=False) @classmethod def from_files( cls, csv_file: str | os.PathLike, config_file: str | os.PathLike, stdout_file: str | os.PathLike | None = None, mode: CmdStanMLE | None = None, diagnostic_file: str | os.PathLike | None = None, ) -> CmdStanLaplace: kwargs = cls._from_files_kwargs( csv_file, config_file, stdout_file, LaplaceRunConfig ) if mode is None: mode = _mode_from_files( kwargs['config'].method_config.mode, csv_file ) return cls( mode=mode, diagnostic_file=( os.fspath(diagnostic_file) if diagnostic_file is not None else None ), **kwargs, ) @property def hessian(self) -> np.ndarray | None: """ The Hessian of the log density at the mode, on the unconstrained scale, read from CmdStan's diagnostic file. This is the matrix from which the Laplace approximation is built. ``None`` if the diagnostic file was not saved; see the ``save_diagnostics`` argument of :meth:`CmdStanModel.laplace_sample`. """ if self.diagnostic_file is None: return None if self._hessian is None: with open(self.diagnostic_file) as fd: self._hessian = np.array(json.load(fd)['Hessian'], dtype=float) return self._hessian
[docs] def save_output_files(self, dir: str | None = None) -> None: """Move the Laplace outputs and optimization mode outputs together.""" self.mode.save_output_files(dir) super().save_output_files(dir)
[docs] def draws(self) -> np.ndarray: """ Return a numpy.ndarray containing the draws from the approximate posterior distribution. This is a 2-D array of shape (draws, parameters). """ self._assemble() return self._draws
def draws_pd( self, vars: list[str] | str | None = None, ) -> pd.DataFrame: if vars is not None: if isinstance(vars, str): vars_list = [vars] else: vars_list = vars self._assemble() cols = [] if vars is not None: for var in dict.fromkeys(vars_list): if var in self.metadata.method_vars: cols.append(var) elif var in self.metadata.stan_vars: info = self.metadata.stan_vars[var] cols.extend( self.column_names[info.start_idx : info.end_idx] ) else: raise ValueError(f'Unknown variable: {var}') else: cols = list(self.column_names) return pd.DataFrame(self._draws, columns=self.column_names)[cols]
[docs] def draws_xr( self, vars: str | list[str] | None = None, ) -> xr.Dataset: """ Returns the sampler draws as a xarray Dataset. :param vars: optional list of variable names. See Also -------- CmdStanMCMC.draws_xr CmdStanGQ.draws_xr """ if not XARRAY_INSTALLED: raise RuntimeError( 'Package "xarray" is not installed, cannot produce draws array.' ) if vars is None: vars_list = list(self.metadata.stan_vars.keys()) elif isinstance(vars, str): vars_list = [vars] else: vars_list = vars self._assemble() attrs: MutableMapping[Hashable, Any] = { "stan_version": f"{self.config.stan_major_version}." f"{self.config.stan_minor_version}." f"{self.config.stan_patch_version}", "model": self.model_name, } data: MutableMapping[Hashable, Any] = {} coordinates: MutableMapping[Hashable, Any] = { "draw": np.arange(self._draws.shape[0]), } for var in vars_list: build_xarray_data( data, self.metadata.stan_vars[var], self._draws[:, np.newaxis, :], ) return ( xr.Dataset(data, coords=coordinates, attrs=attrs) .transpose('draw', ...) .squeeze() )
def __repr__(self) -> str: mode_repr = '\n'.join( ['\t' + line for line in repr(self.mode).splitlines()] )[1:] lines = [ f'CmdStanLaplace: model={self.model_name}', f' mode=({mode_repr})', f' csv_file:\n\t{self.csv_file}', ] if self.config_file is not None: lines.append(f' config_file:\n\t{self.config_file}') if self.stdout_file is not None: lines.append(f' output_file:\n\t{self.stdout_file}') if self.diagnostic_file is not None: lines.append(f' diagnostic_file:\n\t{self.diagnostic_file}') return '\n'.join(lines)