---
title: "Sensitivity, Switching Values, and Monte Carlo PAM Analysis"
author: "Chiranjit Mazumder, Himadri Sekhar Roy, Utkarsh Tiwari, Pramit Pandit, and Bikramjeet Ghose"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Sensitivity, Switching Values, and Monte Carlo PAM Analysis}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

```{r}
library(agriPAM)
crops <- agri_pam_example()
```

## Why uncertainty matters

PAM results depend on yields, observed and border prices, conversion factors,
exchange rates, transport margins, and shadow prices for domestic factors.
Reporting only a point estimate can conceal whether the policy conclusion is
stable or rests on a narrow assumption.

`agriPAM` offers three complementary tools:

1. a deterministic path for one component;
2. a switching value for a specified decision threshold; and
3. Monte Carlo simulation for joint uncertainty.

## Deterministic sensitivity paths

`changes` are proportional. Thus `-0.15` reduces a component by 15 percent and
`0.10` increases it by 10 percent.

```{r}
s <- pam_sensitivity(
  crops,
  parameter = "social_revenue",
  changes = seq(-0.20, 0.20, by = 0.05),
  index = "Paddy"
)
s$results[, c("percent_change", "social_profit", "drc", "scb")]
```

The complete `results` data frame also contains the six scenario components,
all policy transfers, and every standard indicator. This makes a sensitivity
table reproducible without manually recomputing selected ratios.

## Switching values

A switching value answers a sharper question: how far must one assumption move
before a conclusion changes? Profit metrics default to a target of zero and
ratio metrics default to a target of one.

```{r}
switching_value(
  crops,
  parameter = "social_revenue",
  metric = "drc",
  index = "Paddy"
)

switching_value(
  crops,
  parameter = "private_revenue",
  metric = "private_profit",
  index = "Paddy"
)
```

The reported `percent_change` is relative to the base component. A result with
`found = FALSE` means the target was not reached inside the requested search
interval; it does not prove that no switching value exists outside it.

## Monte Carlo analysis

For a positive component with arithmetic mean $m$ and coefficient of variation
$c$, the lognormal option uses

$$
\sigma_{\log} = \sqrt{\log(1+c^2)}, \qquad
\mu_{\log} = \log(m) - \frac{1}{2}\sigma_{\log}^2.
$$

This parameterisation preserves the supplied PAM component as the arithmetic
mean. Zero means or zero coefficients of variation remain fixed. The normal
option uses mean $m$ and standard deviation $mc$ and truncates negative draws
at zero.

```{r}
cv <- c(
  private_revenue = 0.08,
  private_tradable_inputs = 0.10,
  private_domestic_factors = 0.07,
  social_revenue = 0.15,
  social_tradable_inputs = 0.10,
  social_domestic_factors = 0.08
)

mc <- pam_monte_carlo(
  crops,
  cv = cv,
  n = 2000,
  seed = 2026,
  index = "Paddy"
)

mc$summary
mc$probabilities
```

The decision probabilities include private and social profit above zero and DRC
and PCR below one. They are simulation probabilities under the supplied model,
not frequentist significance levels.

## Correlated shocks

Independent shocks can be unrealistic when private and social revenues share a
yield shock or several costs share an exchange-rate shock. A positive
semidefinite correlation matrix can be supplied for the six latent normal
shocks.

```{r}
components <- c(
  "private_revenue", "private_tradable_inputs", "private_domestic_factors",
  "social_revenue", "social_tradable_inputs", "social_domestic_factors"
)
correlation <- diag(6)
dimnames(correlation) <- list(components, components)
correlation["private_revenue", "social_revenue"] <- 0.70
correlation["social_revenue", "private_revenue"] <- 0.70

mc_correlated <- pam_monte_carlo(
  crops,
  cv = cv,
  n = 1000,
  correlation = correlation,
  seed = 2026,
  index = "Paddy"
)
mc_correlated$probabilities
```

Correlation values should come from data, a defensible elicitation procedure,
or transparent scenarios. They should not be tuned to obtain a preferred
policy conclusion.

## Reproducibility and reporting

When `seed` is supplied, `pam_monte_carlo()` restores the caller's random-number
state on exit. A report should retain the seed, number of draws, distribution,
component-specific coefficients of variation, correlations, quantiles, and
decision thresholds. It should also compare the simulated means with the base
PAM and explain any material difference caused by truncation or non-linearity.