Package 'HazardMaps' reference manual

Title:	Spatial Dependence Modeling and Pseudoscenario Generation for Natural Hazards
Description:	An R package for reproducible analysis of spatial dependence in environmental and climate-related variables. The package provides a unified workflow to ingest spatial datasets, estimate and visualize spatial correlation structures, fit multiple dependence models including vine copulas (C-vine and D-vine), Gaussian models, and stochastic fields, and compare them using quantitative indicators to support model selection. Based on the selected model, the package enables the generation of spatially dependent pseudoscenarios for uncertainty analysis and simulation studies. The design emphasizes numerical robustness, modularity, and reproducibility across heterogeneous spatial data sources.
Authors:	Maria Valentina Clavijo Mesa [aut, cre]
Maintainer:	Maria Valentina Clavijo Mesa <[email protected]>
License:	MIT + file LICENSE
Version:	0.1.0
Built:	2026-10-07 08:37:12 UTC
Source:	https://github.com/Valentina9619/HazardMaps

Compute spatial cluster sizes of extreme events

Description

For each time step, counts the land cells where the hazard value meets or exceeds threshold. This is the cluster-size metric $B(t)$ (Eq. 21, Appendix C of Clavijo Mesa et al., 2026) used to validate whether a dependence model reproduces the observed spatial footprint.

Usage

hm_cluster_size(X, threshold, time = NULL)
hm_cluster_size(X, threshold, time = NULL)

Arguments

X

Numeric matrix ( $T \times N$ ) from [hm_filter_land_cells()].

threshold

A single finite numeric value.

time

Optional date vector of length $T$ . Defaults to row indices.

Value

A data.frame with columns date, cluster_size, and cluster_fraction.

References

Clavijo Mesa, M.V., Di Maio, F. & Zio, E. (2026). Reliability Engineering & System Safety, 275, 112830.

Examples

## Not run: 
X_land <- hm_filter_land_cells(X)
cs     <- hm_cluster_size(X_land, threshold = 25,
                           time = attr(X_land, "time"))
summary(cs$cluster_size)

## End(Not run)

## Not run: 
X_land <- hm_filter_land_cells(X)
cs     <- hm_cluster_size(X_land, threshold = 25,
                           time = attr(X_land, "time"))
summary(cs$cluster_size)

## End(Not run)

Decode the NetCDF time axis

Description

Converts CF-style time values (e.g. "days since 1970-01-01") to an R Date or POSIXct vector.

Usage

hm_decode_time(x, tz = "UTC")
hm_decode_time(x, tz = "UTC")

Arguments

x

An hm_hazard object returned by [hm_read_netcdf()].

tz

Time zone string for sub-daily data. Defaults to "UTC".

Value

The same object with x$time replaced by a Date vector (daily data) or POSIXct vector (sub-daily data).

Compute pairwise haversine distances between grid cells

Description

Returns a symmetric $N \times N$ distance matrix of great-circle distances in kilometres between all pairs of land cells (Eq. 5 of Clavijo Mesa et al., 2026, SF paper).

Usage

hm_distance_matrix(coords)
hm_distance_matrix(coords)

Arguments

coords

A data.frame with lat and lon columns in decimal degrees. Typically attr(X_land, "coords") from [hm_filter_land_cells()].

Value

A symmetric numeric matrix with diagonal zero.

References

Clavijo Mesa, M.V., Broggi, M., Di Maio, F. & Zio, E. (2026). International Journal of Disaster Risk Reduction, 141, 106172.

Examples

## Not run: 
X_land <- hm_filter_land_cells(X)
D      <- hm_distance_matrix(attr(X_land, "coords"))
range(D)

## End(Not run)

## Not run: 
X_land <- hm_filter_land_cells(X)
D      <- hm_distance_matrix(attr(X_land, "coords"))
range(D)

## End(Not run)

Compute the empirical spatial correlogram

Description

Bins pairwise Kendall correlations by inter-site distance to give average correlation as a function of distance. The result is the key input for fitting a covariance model in [hm_fit_correlation_model()], following Eq. 5–6 of Clavijo Mesa et al. (2026, SF paper).

Usage

hm_empirical_correlogram(tau, D, n_bins = 30L, max_dist = NULL)
hm_empirical_correlogram(tau, D, n_bins = 30L, max_dist = NULL)

Arguments

tau

Symmetric numeric matrix of pairwise Kendall correlations from [hm_empirical_kendall()].

D

Symmetric numeric distance matrix in km from [hm_distance_matrix()]. Must have the same dimensions as tau.

n_bins

Number of equal-width distance bins. Defaults to 30.

max_dist

Maximum distance in km to include. Defaults to the observed maximum.

Value

A data.frame with columns bin_center, mean_tau, n_pairs, bin_lo, and bin_hi.

References

Clavijo Mesa, M.V., Broggi, M., Di Maio, F. & Zio, E. (2026). International Journal of Disaster Risk Reduction, 141, 106172.

Examples

## Not run: 
tau  <- hm_empirical_kendall(pit$Z, cell_idx = 1:50)
D    <- hm_distance_matrix(coords[1:50, ])
corg <- hm_empirical_correlogram(tau, D, n_bins = 20)
head(corg)

## End(Not run)

## Not run: 
tau  <- hm_empirical_kendall(pit$Z, cell_idx = 1:50)
D    <- hm_distance_matrix(coords[1:50, ])
corg <- hm_empirical_correlogram(tau, D, n_bins = 20)
head(corg)

## End(Not run)

Compute the empirical pairwise Kendall correlation matrix

Description

Estimates Kendall's $\hat{\tau}$ between every pair of grid cells from the Gaussian scores matrix Z from [hm_pit_transform()]. Implements Eq. 20 of Clavijo Mesa et al. (2026, Copernicus paper).

Usage

hm_empirical_kendall(Z, cell_idx = NULL)
hm_empirical_kendall(Z, cell_idx = NULL)

Arguments

Z

Numeric matrix ( $T \times N$ ) of centred Gaussian scores from [hm_pit_transform()].

cell_idx

Optional integer vector of column indices. Defaults to all columns.

Details

For large grids (N > 1000) supply a subsample via cell_idx to keep computation feasible.

Value

A symmetric $N \times N$ matrix of Kendall $\hat{\tau}$ values in $[-1, 1]$ .

References

Clavijo Mesa, M.V., Di Maio, F. & Zio, E. (2026). Reliability Engineering & System Safety, 275, 112830.

Examples

## Not run: 
fits <- hm_fit_marginals(X)
pit  <- hm_pit_transform(X, fits)
tau  <- hm_empirical_kendall(pit$Z, cell_idx = 1:30)
range(tau)

## End(Not run)

## Not run: 
fits <- hm_fit_marginals(X)
pit  <- hm_pit_transform(X, fits)
tau  <- hm_empirical_kendall(pit$Z, cell_idx = 1:30)
range(tau)

## End(Not run)

Remove sea and no-data cells from a hazard matrix

Description

Drops columns where the fraction of finite positive values falls below min_valid. Needed for rotated-grid datasets such as EURO-CORDEX where sea cells produce all-NA columns.

Usage

hm_filter_land_cells(X, min_valid = 0.8)
hm_filter_land_cells(X, min_valid = 0.8)

Arguments

X

A numeric matrix as returned by [hm_to_matrix()].

min_valid

Minimum fraction of valid observations required to keep a column. Defaults to 0.8.

Value

A matrix with only land columns retained. Attributes land_idx, coords, and time are attached.

Fit a spatial copula model to the uniform PIT data

Description

Fits a C-vine, D-vine, or Gaussian copula to the uniform PIT matrix from [hm_pit_transform()], following Eq. 6 of Clavijo Mesa et al. (2026). The three structures correspond to the comparison in Table IV of that paper.

Usage

hm_fit_copula(U, type = "cvine", ...)
hm_fit_copula(U, type = "cvine", ...)

Arguments

U

Numeric matrix ( $T \times N$ ) of uniform PIT values from [hm_pit_transform()].

type

Copula structure: "cvine" (default), "dvine", or "gaussian".

...

Additional arguments passed to rvinecopulib::vinecop().

Details

Vine copulas are fitted via rvinecopulib::vinecop(). The Gaussian copula uses the sin-transform $\rho = \sin(\pi \hat{\tau} / 2)$ to convert Kendall $\tau$ to a Pearson correlation matrix. Requires rvinecopulib (listed in Suggests).

Value

An hm_copula list with type, model, n_cells, and n_obs.

References

Clavijo Mesa, M.V., Di Maio, F. & Zio, E. (2026). Reliability Engineering & System Safety, 275, 112830.

Examples

## Not run: 
X_land <- hm_filter_land_cells(X)
fits   <- hm_fit_marginals(X_land)
pit    <- hm_pit_transform(X_land, fits)

cop_c <- hm_fit_copula(pit$U, type = "cvine")
cop_d <- hm_fit_copula(pit$U, type = "dvine")
cop_g <- hm_fit_copula(pit$U, type = "gaussian")

## End(Not run)

## Not run: 
X_land <- hm_filter_land_cells(X)
fits   <- hm_fit_marginals(X_land)
pit    <- hm_pit_transform(X_land, fits)

cop_c <- hm_fit_copula(pit$U, type = "cvine")
cop_d <- hm_fit_copula(pit$U, type = "dvine")
cop_g <- hm_fit_copula(pit$U, type = "gaussian")

## End(Not run)

Fit a parametric spatial correlation model to the empirical correlogram

Description

Fits Matérn, Exponential, Gaussian, and/or Spherical covariance families to the correlogram from [hm_empirical_correlogram()] by weighted least squares (Eq. 6–7 of Clavijo Mesa et al., 2026, SF paper). Selects the best family by RMSE, matching Table 1 of that paper.

Usage

hm_fit_correlation_model(
  corg,
  families = c("matern", "exponential", "gaussian", "spherical"),
  max_dist = NULL
)
hm_fit_correlation_model(
  corg,
  families = c("matern", "exponential", "gaussian", "spherical"),
  max_dist = NULL
)

Arguments

corg

data.frame from [hm_empirical_correlogram()].

families

Covariance families to fit. Any subset of c("matern", "exponential", "gaussian", "spherical"). Defaults to all four.

max_dist

Maximum distance in km to include. Defaults to the full correlogram range.

Value

An hm_corrmodel list with best_family, best_params, best_rmse, all_fits, and corg.

References

Clavijo Mesa, M.V., Broggi, M., Di Maio, F. & Zio, E. (2026). International Journal of Disaster Risk Reduction, 141, 106172.

Examples

## Not run: 
corg  <- hm_empirical_correlogram(tau, D)
model <- hm_fit_correlation_model(corg)
model$best_family
model$all_fits

## End(Not run)

## Not run: 
corg  <- hm_empirical_correlogram(tau, D)
model <- hm_fit_correlation_model(corg)
model$best_family
model$all_fits

## End(Not run)

Fit marginal distributions to each grid cell

Description

Fits candidate parametric distributions to each column of X by maximum likelihood and selects the best fit using AIC or BIC, following the methodology in Clavijo Mesa et al. (2026).

Usage

hm_fit_marginals(X, dists = .hm_supported_dists, criterion = "bic")
hm_fit_marginals(X, dists = .hm_supported_dists, criterion = "bic")

Arguments

X

A numeric matrix ( $T \times N$ ) from [hm_to_matrix()]. All values must be strictly positive.

dists

Candidate families. Any subset of c("weibull", "gamma", "lnorm", "gumbel", "tnorm", "tlaplace").

criterion

Selection criterion: "bic" (default) or "aic".

Value

A data.frame with one row per cell and columns cell_id, best_dist, best_dist_label, params, loglik, aic, bic, n_obs, n_failed. The attribute "fits_full" stores raw per-cell fit results for use in [hm_marginal_gof()].

Extract grid geometry

Description

Computes the bounding box, grid spacing, and cell count from the coordinate table and stores them in x$grid.

Usage

hm_get_grid_geometry(x)
hm_get_grid_geometry(x)

Arguments

x

An hm_hazard object after [hm_standardize_coords()].

Value

The same object with a new $grid element containing nx, ny, dx, dy, bbox, n_cells, and grid_type.

Goodness-of-fit diagnostics for a single grid cell

Description

Returns the KS statistic and QQ data for the best-fitting distribution at a chosen cell. The KS test is a complementary diagnostic — distribution selection is done by AIC/BIC in [hm_fit_marginals()].

Usage

hm_marginal_gof(X, fits, cell_id)
hm_marginal_gof(X, fits, cell_id)

Arguments

X

Numeric matrix passed to [hm_fit_marginals()].

fits

data.frame from [hm_fit_marginals()].

cell_id

Column index to diagnose.

Value

A list with cell_id, dist, dist_label, params, ks_statistic, ks_pvalue, qq, and n_obs.

Apply the Probability Integral Transform

Description

Transforms X to uniform margins using each cell's fitted CDF, then optionally applies the probit transform to obtain centred Gaussian scores. Implements Equations (3)–(4) from Clavijo Mesa et al. (2026, SF paper).

Usage

hm_pit_transform(X, fits, gaussian = TRUE)
hm_pit_transform(X, fits, gaussian = TRUE)

Arguments

X

Numeric matrix ( $T \times N$ ) from [hm_to_matrix()].

fits

data.frame from [hm_fit_marginals()].

gaussian

If TRUE (default), also returns centred Gaussian scores $Z = \Phi^{-1}(U)$ .

Value

A list with U (uniform matrix), Z (Gaussian scores or NULL), n_cells_ok, and n_cells_skipped.

Plot best-fitting marginal distribution by grid cell

Description

Maps each cell by the marginal family selected by [hm_fit_marginals()]. Reproduces Fig. 6 of Clavijo Mesa et al. (2026).

Usage

hm_plot_best_dist(
  x,
  fits,
  bbox = NULL,
  title = NULL,
  show_map = TRUE,
  palette = NULL,
  coord = "fixed"
)
hm_plot_best_dist(
  x,
  fits,
  bbox = NULL,
  title = NULL,
  show_map = TRUE,
  palette = NULL,
  coord = "fixed"
)

Arguments

x

An hm_hazard object after [hm_standardize_coords()].

fits

The data.frame returned by [hm_fit_marginals()].

bbox

Optional named numeric vector with 'lon_min', 'lon_max', 'lat_min', and 'lat_max' to control the plot extent. If 'NULL' (default), the extent is derived from the coordinate table with a small padding so edge points are not clipped.

title

Optional plot title.

show_map

Logical. If 'TRUE', adds a world map background.

palette

Optional named character vector mapping distribution labels to colours. Names must match the values in 'fits$best_dist_label' (e.g. '"Weibull"', '"Gamma"', '"Lognormal"', '"Gumbel"', '"Zero-trunc. Gaussian"', '"Zero-trunc. Laplace"', '"No fit"'). If 'NULL' (default), a built-in muted palette is used.

coord

Coordinate display method. Either '"fixed"' or '"quickmap"'.

Value

A 'ggplot' object.

Examples

## Not run: 
x     <- hm_read_netcdf(f, var = "i10fg")
x     <- hm_standardize_coords(x)
x     <- hm_decode_time(x)
x_ext <- hm_select_extreme_events(x, threshold = 25)
X     <- hm_to_matrix(x_ext)
fits  <- hm_fit_marginals(X)

hm_plot_best_dist(x_ext, fits)

## End(Not run)

## Not run: 
x     <- hm_read_netcdf(f, var = "i10fg")
x     <- hm_standardize_coords(x)
x     <- hm_decode_time(x)
x_ext <- hm_select_extreme_events(x, threshold = 25)
X     <- hm_to_matrix(x_ext)
fits  <- hm_fit_marginals(X)

hm_plot_best_dist(x_ext, fits)

## End(Not run)

Plot the empirical spatial correlogram

Description

Draws the empirical correlogram produced by [hm_empirical_correlogram()]: average Kendall $\hat{\tau}$ as a function of inter-site distance, with point size proportional to the number of cell pairs in each bin. Reproduces the style of Fig. 8 in Clavijo Mesa et al. (2026, SF paper).

Usage

hm_plot_correlogram(
  corg,
  title = NULL,
  colour = "#2166AC",
  show_points = TRUE,
  show_zero = TRUE,
  ylim = NULL
)
hm_plot_correlogram(
  corg,
  title = NULL,
  colour = "#2166AC",
  show_points = TRUE,
  show_zero = TRUE,
  ylim = NULL
)

Arguments

corg

A data.frame returned by [hm_empirical_correlogram()], with columns 'bin_center', 'mean_tau', and 'n_pairs'.

title

Optional plot title.

colour

Line and point colour. Defaults to '"#2166AC"' (steel blue).

show_points

Logical. If 'TRUE' (default), draws points at each bin centre sized by the number of pairs.

show_zero

Logical. If 'TRUE' (default), adds a horizontal dashed line at $\tau = 0$ .

ylim

Optional numeric vector of length 2 for the y-axis range. If 'NULL' (default), the range is set automatically.

Details

A horizontal dashed reference line is drawn at $\tau = 0$ to help identify the distance at which spatial dependence becomes negligible. Point size is scaled by 'sqrt(n_pairs)' so bins with more pairs are visually more prominent without dominating the plot.

Value

A 'ggplot' object.

References

Clavijo Mesa, M.V., Broggi, M., Di Maio, F. & Zio, E. (2026). Inoperability assessment of interdependent critical infrastructures exposed to natural hazards considering climate change. International Journal of Disaster Risk Reduction, 141, 106172.

Examples

## Not run: 
X_land <- hm_filter_land_cells(X)
fits   <- hm_fit_marginals(X_land)
pit    <- hm_pit_transform(X_land, fits)
tau    <- hm_empirical_kendall(pit$Z)
D      <- hm_distance_matrix(attr(X_land, "coords"))
corg   <- hm_empirical_correlogram(tau, D)

hm_plot_correlogram(corg,
  title = "Empirical correlogram — Copernicus wind gust")

## End(Not run)

## Not run: 
X_land <- hm_filter_land_cells(X)
fits   <- hm_fit_marginals(X_land)
pit    <- hm_pit_transform(X_land, fits)
tau    <- hm_empirical_kendall(pit$Z)
D      <- hm_distance_matrix(attr(X_land, "coords"))
corg   <- hm_empirical_correlogram(tau, D)

hm_plot_correlogram(corg,
  title = "Empirical correlogram — Copernicus wind gust")

## End(Not run)

Plot frequency of best-fitting marginal distribution families

Description

Draws a bar chart showing how many grid cells were assigned each distribution family by [hm_fit_marginals()]. Reproduces the style of Fig. A1 in Clavijo Mesa et al. (2026, Appendix A).

Usage

hm_plot_dist_frequency(
  fits,
  title = NULL,
  bar_fill = NULL,
  bar_colour = "white",
  show_pct = TRUE
)
hm_plot_dist_frequency(
  fits,
  title = NULL,
  bar_fill = NULL,
  bar_colour = "white",
  show_pct = TRUE
)

Arguments

fits

The data.frame returned by [hm_fit_marginals()].

title

Optional plot title.

bar_fill

Bar fill colour. If 'NULL' (default), each bar is coloured by distribution family using the same palette as [hm_plot_best_dist()].

bar_colour

Bar border colour.

show_pct

Logical. If 'TRUE', adds percentage labels above each bar.

Value

A 'ggplot' object.

Examples

## Not run: 
fits <- hm_fit_marginals(X)
hm_plot_dist_frequency(fits)

## End(Not run)

## Not run: 
fits <- hm_fit_marginals(X)
hm_plot_dist_frequency(fits)

## End(Not run)

Plot threshold exceedances

Description

Maps exceedance count or frequency at each grid cell. Cells are drawn as filled polygons for both regular and rotated grids.

Usage

hm_plot_exceedance(
  x,
  threshold,
  metric = "count",
  dataset = "auto",
  bbox = NULL,
  title = NULL,
  show_map = TRUE,
  show_grid = TRUE,
  grid_res = NULL,
  colours = c("white", "gold", "orange", "firebrick"),
  grid_colour = "grey55",
  grid_linewidth = 0.25,
  cell_alpha = 0.9,
  legend_title = NULL,
  coord = "fixed"
)
hm_plot_exceedance(
  x,
  threshold,
  metric = "count",
  dataset = "auto",
  bbox = NULL,
  title = NULL,
  show_map = TRUE,
  show_grid = TRUE,
  grid_res = NULL,
  colours = c("white", "gold", "orange", "firebrick"),
  grid_colour = "grey55",
  grid_linewidth = 0.25,
  cell_alpha = 0.9,
  legend_title = NULL,
  coord = "fixed"
)

Arguments

x

An hm_hazard object after [hm_standardize_coords()].

threshold

Numeric threshold defining exceedances.

metric

"count" (default) or "frequency".

dataset

Grid type: "auto", "copernicus", "eurocordex", "regular", or "rotated".

bbox

Optional named numeric vector with lon_min, lon_max, lat_min, lat_max.

title

Optional plot title.

show_map

Logical. Add world map background.

show_grid

Logical. Draw cell borders.

grid_res

Grid resolution in degrees (regular grids only).

colours

Colour ramp for filled cells.

grid_colour

Cell border colour.

grid_linewidth

Cell border width.

cell_alpha

Cell transparency.

legend_title

Optional legend title.

coord

"fixed" or "quickmap".

Value

A ggplot object.

Plot extreme-event days over time

Description

Bar chart of extreme-event days aggregated by year, two-year, five-year or decade periods. A day is counted once when at least one cell exceeds threshold.

Usage

hm_plot_exceedance_time(
  x,
  threshold,
  by = "year",
  title = NULL,
  xlab = NULL,
  ylab = NULL,
  bar_fill = "grey70",
  bar_colour = "grey30"
)
hm_plot_exceedance_time(
  x,
  threshold,
  by = "year",
  title = NULL,
  xlab = NULL,
  ylab = NULL,
  bar_fill = "grey70",
  bar_colour = "grey30"
)

Arguments

x

An hm_hazard object after [hm_standardize_coords()].

threshold

Numeric threshold defining exceedances.

by

Aggregation period: "year", "2_years", "5_years", or "decade".

title

Optional plot title.

xlab

Optional x-axis label.

ylab

Optional y-axis label.

bar_fill

Bar fill colour.

bar_colour

Bar border colour.

Value

A ggplot object.

Plot marginal fit diagnostics for a single grid cell

Description

Produces a three-panel diagnostic figure for the best-fitting marginal distribution at a chosen grid cell: (1) a histogram of the observed values with the fitted PDF overlaid, (2) the empirical vs fitted CDF, and (3) a quantile-quantile plot. Reproduces the style of Fig. 7 and Appendix B (Fig. B1) in Clavijo Mesa et al. (2026).

Usage

hm_plot_marginal_fit(
  X,
  fits,
  cell_id,
  title = NULL,
  x = NULL,
  n_bins = 30,
  colour_fit = "firebrick"
)
hm_plot_marginal_fit(
  X,
  fits,
  cell_id,
  title = NULL,
  x = NULL,
  n_bins = 30,
  colour_fit = "firebrick"
)

Arguments

X

A numeric matrix (same one passed to [hm_fit_marginals()]).

fits

The data.frame returned by [hm_fit_marginals()].

cell_id

Integer. The cell to diagnose (column index of X).

title

Optional overall plot title. Defaults to the cell coordinates when 'x' is supplied, or to the cell index otherwise.

x

Optional 'hm_hazard' object after [hm_standardize_coords()]. When supplied, the cell's geographic coordinates are shown in the title.

n_bins

Number of histogram bins.

colour_fit

Colour used for the fitted PDF and CDF lines.

Value

A 'ggplot' object (three panels arranged with [ggplot2::facet_wrap()] on a long-format data frame).

Examples

## Not run: 
fits <- hm_fit_marginals(X)
hm_plot_marginal_fit(X, fits, cell_id = 1, x = x_ext)

## End(Not run)

## Not run: 
fits <- hm_fit_marginals(X)
hm_plot_marginal_fit(X, fits, cell_id = 1, x = x_ext)

## End(Not run)

Plot spatial domain grid

Description

Plots the spatial grid of a hazard dataset. Detects regular (Copernicus/ERA5) and rotated (EURO-CORDEX) grids automatically or from dataset.

Usage

hm_plot_spatial_domain(
  x,
  dataset = "auto",
  bbox = NULL,
  title = NULL,
  show_map = TRUE,
  show_points = FALSE,
  grid_res = NULL,
  grid_colour = "grey55",
  grid_linewidth = 0.35,
  point_size = 0.5,
  coord = "fixed"
)
hm_plot_spatial_domain(
  x,
  dataset = "auto",
  bbox = NULL,
  title = NULL,
  show_map = TRUE,
  show_points = FALSE,
  grid_res = NULL,
  grid_colour = "grey55",
  grid_linewidth = 0.35,
  point_size = 0.5,
  coord = "fixed"
)

Arguments

x

An hm_hazard object after [hm_standardize_coords()].

dataset

Grid type: "auto", "copernicus", "eurocordex", "regular", or "rotated".

bbox

Optional named numeric vector with lon_min, lon_max, lat_min, lat_max.

title

Optional plot title.

show_map

Logical. Add world map background (requires maps).

show_points

Logical. Add grid-cell centre points.

grid_res

Grid resolution in degrees (regular grids only).

grid_colour

Grid-line colour.

grid_linewidth

Grid-line width.

point_size

Point size when show_points = TRUE.

coord

"fixed" or "quickmap".

Value

A ggplot object.

Read a hazard NetCDF dataset

Description

Reads a NetCDF file containing a hazard variable on a spatial grid (regular or rotated) and returns an 'hm_hazard' object. CRS is not required.

Usage

hm_read_netcdf(file, var = NULL)
hm_read_netcdf(file, var = NULL)

Arguments

file

Path to a NetCDF file.

var

Name of the hazard variable. If NULL and the file contains exactly one variable, it is selected automatically.

Details

Supports CF-convention NetCDF files with regular grids (e.g. Copernicus, ERA5) and rotated or curvilinear grids (e.g. EURO-CORDEX). Coordinate names lat/lon and latitude/longitude are detected automatically.

Value

An object of class hm_hazard.

Select extreme-event days by threshold

Description

Retains only the time steps in which at least one grid cell reaches or exceeds threshold. Call after [hm_decode_time()] and before [hm_to_matrix()].

Usage

hm_select_extreme_events(x, threshold)
hm_select_extreme_events(x, threshold)

Arguments

x

An hm_hazard object after [hm_standardize_coords()] and [hm_decode_time()].

threshold

A single finite numeric value.

Value

The same object with $data and $time restricted to extreme-event days. $meta$filter records the threshold and day counts for reproducibility.

Simulate spatially coherent hazard scenarios from a fitted copula

Description

Draws n_scenarios realisations from a fitted copula and back-transforms to physical units via the inverse marginal CDFs. Implements Eq. 7–8 of Clavijo Mesa et al. (2026).

Usage

hm_simulate_copula(copula, fits, n_scenarios = 1000L, seed = NULL)
hm_simulate_copula(copula, fits, n_scenarios = 1000L, seed = NULL)

Arguments

copula

An hm_copula object from [hm_fit_copula()].

fits

data.frame from [hm_fit_marginals()] for the same land cells used to fit copula.

n_scenarios

Number of scenarios. Defaults to 1000.

seed

Optional integer random seed.

Details

Vine copulas are sampled via rvinecopulib::rvinecop(). The Gaussian copula uses MASS::mvrnorm() followed by the standard normal CDF. Both packages are listed in Suggests.

Value

A numeric matrix ( $S \times N$ ) of simulated hazard intensities. Attributes type, n_scenarios, and n_cells are attached.

References

Clavijo Mesa, M.V., Di Maio, F. & Zio, E. (2026). Reliability Engineering & System Safety, 275, 112830.

Examples

## Not run: 
cop       <- hm_fit_copula(pit$U, type = "cvine")
scenarios <- hm_simulate_copula(cop, fits, n_scenarios = 1000)
dim(scenarios)
range(scenarios, na.rm = TRUE)

## End(Not run)

## Not run: 
cop       <- hm_fit_copula(pit$U, type = "cvine")
scenarios <- hm_simulate_copula(cop, fits, n_scenarios = 1000)
dim(scenarios)
range(scenarios, na.rm = TRUE)

## End(Not run)

Simulate hazard scenarios via Karhunen-Loève Expansion

Description

Generates n_scenarios synthetic hazard fields from the KLE of the fitted covariance model, following Eq. 8–11 of Clavijo Mesa et al. (2026, SF paper): build $\bar{C}$ , eigen-decompose and truncate to var_retain variance, sample KLE coefficients, back-transform via $\Phi$ and the inverse marginal CDFs.

Usage

hm_simulate_sf_kle(
  corrmodel,
  D,
  fits,
  n_scenarios = 1000L,
  var_retain = 0.95,
  seed = NULL
)
hm_simulate_sf_kle(
  corrmodel,
  D,
  fits,
  n_scenarios = 1000L,
  var_retain = 0.95,
  seed = NULL
)

Arguments

corrmodel

An hm_corrmodel from [hm_fit_correlation_model()].

D

Symmetric distance matrix in km from [hm_distance_matrix()]. Must have nrow(fits) rows.

fits

data.frame from [hm_fit_marginals()] for the same land cells.

n_scenarios

Number of synthetic scenarios. Defaults to 1000.

var_retain

Variance fraction retained in KLE truncation. Defaults to 0.95.

seed

Optional integer random seed.

Value

A numeric matrix ( $S \times N$ ) of simulated hazard intensities. Attributes family, k_modes, var_retain, and var_explained are attached.

References

Clavijo Mesa, M.V., Broggi, M., Di Maio, F. & Zio, E. (2026). International Journal of Disaster Risk Reduction, 141, 106172.

Examples

## Not run: 
model     <- hm_fit_correlation_model(corg)
scenarios <- hm_simulate_sf_kle(model, D, fits,
                                 n_scenarios = 1000, seed = 42)
attr(scenarios, "k_modes")
attr(scenarios, "var_explained")

## End(Not run)

## Not run: 
model     <- hm_fit_correlation_model(corg)
scenarios <- hm_simulate_sf_kle(model, D, fits,
                                 n_scenarios = 1000, seed = 42)
attr(scenarios, "k_modes")
attr(scenarios, "var_explained")

## End(Not run)

Standardize spatial coordinates

Description

Converts raw NetCDF coordinates into a canonical data.frame with one row per grid cell.

Usage

hm_standardize_coords(x)
hm_standardize_coords(x)

Arguments

x

An hm_hazard object returned by [hm_read_netcdf()].

Details

Regular grids supply lat and lon as 1D vectors; all combinations are expanded with expand.grid(). Rotated or curvilinear grids supply lat and lon as 2D matrices, with rotated indices appended when available.

Value

The same object with x$coords replaced by a data.frame containing cell_id, lat, and lon.

Summarise retained extreme-event days

Description

Returns a data.frame with one row per time step: date, number of cells that met the threshold, and domain-wide maximum value.

Usage

hm_summarise_events(x, threshold = NULL)
hm_summarise_events(x, threshold = NULL)

Arguments

x

An hm_hazard object, typically from [hm_select_extreme_events()].

threshold

Threshold used to count exceeding cells. If NULL, read from x$meta$filter$threshold.

Value

A data.frame with columns date, n_cells_exceeded, and max_value.

Convert hazard array to a time-by-cell matrix

Description

Reshapes x$data into a $T \times N$ numeric matrix where rows are time steps and columns are grid cells.

Usage

hm_to_matrix(x)
hm_to_matrix(x)

Arguments

x

An hm_hazard object after [hm_standardize_coords()] and [hm_decode_time()].

Value

A numeric matrix with attributes time and coords.

Package 'HazardMaps'

Help Index

Compute spatial cluster sizes of extreme events

Description

Usage

Arguments

Value

References

See Also

Examples

Decode the NetCDF time axis

Description

Usage

Arguments

Value

See Also

Compute pairwise haversine distances between grid cells

Description

Usage

Arguments

Value

References

See Also

Examples

Compute the empirical spatial correlogram

Description

Usage

Arguments

Value

References

See Also

Examples

Compute the empirical pairwise Kendall correlation matrix

Description

Usage

Arguments

Details

Value

References

See Also

Examples

Remove sea and no-data cells from a hazard matrix

Description

Usage

Arguments

Value

See Also

Fit a spatial copula model to the uniform PIT data

Description

Usage

Arguments

Details

Value

References

See Also

Examples

Fit a parametric spatial correlation model to the empirical correlogram

Description

Usage

Arguments

Value

References

See Also

Examples

Fit marginal distributions to each grid cell

Description

Usage

Arguments

Value

See Also

Extract grid geometry

Description

Usage

Arguments

Value

See Also

Goodness-of-fit diagnostics for a single grid cell

Description

Usage

Arguments