---
title: Getting started with SAFEPG
author: An introductory tutorial with examples
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{SAFEPG}
  %\VignetteEngine{knitr::rmarkdown}
---

```{r setup, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```
## Introduction

The `SAFEPG` package provides a frequency-severity model designed for predicting climate-related extreme losses. The model incorporates a sign-aligned regularization term that ensures consistent signs between the frequency and severity components. This enhancement improves both the interpretability and predictive performance of the model.

In this vignette, we will demonstrate how to use the core functions of the `SAFEPG` package to fit the model and make predictions.

## `safe()`: Fitting the Model

The `safe()` function is the core function of the package, used to fit the frequency-severity model. The main arguments to supply are:

- `x`: A numerical matrix representing the features (covariates).
- `y`: A numeric vector of loss values (severity), assumed to follow a Gamma distribution.
- `k`: A numeric vector representing the number of claims (frequency), assumed to follow a Poisson distribution.
- `lambda`: A user-supplied sequence of regularization parameters (`lambda`).
- `ind_p`: A belief vector indicating which features should share the same sign across frequency and severity components.

### Example: Fitting the Model

Below is an example of how to generate synthetic data and fit the model using the `safe()` function:

```{r}
library(SAFEPG)
set.seed(1)
n <- 100  # Number of observations
p <- 5    # Number of predictors

# Simulating data
x <- matrix(rnorm(n * p), nrow = n, ncol = p)
beta_true <- rep(0.1, 5)
gamma_true <- c(rep(1, 3), -1, -1)
mu <- x %*% beta_true
k <- rpois(n, lambda = exp(mu))
alpha_val <- 1
theta <- exp(x %*% gamma_true) / alpha_val
y <- rgamma(n, shape = alpha_val, scale = theta)

# Fit the model
lambda_val <- 1
fit <- safe(x, y, k, lambda = lambda_val, ind_p = c(1, 1, 1, 0, 0))
```

## `eccv.safe()`: Electoral College Cross-Validation

The `eccv.safe()` function performs electoral college cross-validation (EC-CV) to tune the regularization parameter (`lambda`). It takes the same arguments as `safe()`.

### Example: Performing Cross-Validation

```{r}
lambda_seq <- 10^seq(2, -8, length.out = 5)  # Lambda sequence
cv.fit <- eccv.safe(x, y, k, lambda = lambda_seq, ind_p = c(1, 1, 1, 0, 0))
```

## S3 Methods for `safe` Objects

Several S3 methods are provided for objects of class `safe`. These methods include:

- `coef()`: Returns a matrix of coefficients.
- `predict()`: Returns predictions of $\hat{y}$ given a new matrix `x`.

Both methods allow you to specify a particular value of $\lambda$ (not necessarily from the original sequence) via the `s` argument.

### Example: Using S3 Methods

```{r}
# Extract coefficients from the fitted model
coef(fit)

# Make predictions on new data
set.seed(234)
newx <- matrix(rnorm(n * p), nrow = n, ncol = p)
predictions <- predict(fit, newx)
```