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

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

## Purpose

A Policy Analysis Matrix (PAM) compares two enterprise budgets for the same
production system. The private budget uses observed market prices and measures
incentives faced by producers. The social budget uses efficiency prices and
measures the value of outputs and inputs to the economy. Their difference
captures policy and market-failure transfers.

```{r}
library(agriPAM)
```

## The PAM accounting identities

The conventional structure is:

| Valuation | Revenue | Tradable inputs | Domestic factors | Profit |
|---|---:|---:|---:|---:|
| Private | $A$ | $B$ | $C$ | $D=A-B-C$ |
| Social | $E$ | $F$ | $G$ | $H=E-F-G$ |
| Transfer | $I=A-E$ | $J=B-F$ | $K=C-G$ | $L=D-H=I-J-K$ |

`agriPAM` retains the six additive accounts and derives every profit, transfer,
and ratio from them. This design prevents contradictory totals after grouping
or scenario analysis.

## Constructing a PAM directly

```{r}
paddy <- pam(
  private_revenue = 150000,
  private_tradable_inputs = 42000,
  private_domestic_factors = 61000,
  social_revenue = 140000,
  social_tradable_inputs = 46000,
  social_domestic_factors = 55000,
  id = "Paddy",
  unit = "ha",
  currency = "INR"
)

pam_matrix(paddy)
pam_indicators(paddy)
```

All revenue and cost components must be finite and non-negative. Profits and
transfers can be negative. When a ratio denominator is zero, the corresponding
ratio is reported as `NA` rather than as an infinite value.

## Starting with an itemised farm budget

`pam_from_budget()` accepts one row per budget item. Each row must identify the
quantity, private price, social price, and one of three account categories:
`output`, `tradable_input`, or `domestic_factor`.

```{r}
budget <- agri_pam_example("budget")
head(budget)

crops <- pam_from_budget(
  budget,
  quantity = "quantity",
  private_price = "private_price",
  social_price = "social_price",
  category = "category",
  id = "crop",
  unit = "ha",
  currency = "INR"
)

pam_values(crops)
```

The included values are synthetic and are intended only to demonstrate the
workflow.

## Interpreting the indicators

```{r}
pam_indicators(crops)
pam_classify(crops)
```

The main interpretation rules, conditional on economically meaningful positive
value-added denominators, are:

| Indicator | Common decision rule | Interpretation |
|---|---:|---|
| DRC | below 1 | comparative advantage in domestic resources |
| PCR | below 1 | private value added covers domestic-factor cost |
| NPCO | above 1 | private output price exceeds social output price |
| NPCI | below 1 | private tradable-input cost is below its social cost |
| EPC | above 1 | positive net protection of value added |
| PC | above 1 | policies raise private relative to social profit |
| SRP | above 0 | positive net transfer relative to social revenue |
| SCB | below 1 | social benefits exceed social costs |

These thresholds are diagnostics, not substitutes for inspecting the underlying
budgets, price construction, and institutional setting.

## Parity prices

The social output or input price can begin with a border price. Import parity
adds domestic transfer costs; export parity subtracts them.

```{r}
parity_price(
  border_price = 300,
  exchange_rate = 83,
  transport = 1200,
  handling = 300,
  direction = "import"
)
```

Any conversion from border to farm-gate prices should document units, location,
quality adjustment, exchange-rate convention, transport, processing, and
marketing margins. Taxes and subsidies are excluded from an undistorted social
price.

## Aggregating production systems

Ratios should not ordinarily be averaged across systems. `pam_aggregate()`
first sums the six accounts and then recalculates each ratio.

```{r}
groups <- c("Cereal", "Cereal", "Pulse", "Oilseed")
regional <- pam_aggregate(crops, groups)
pam_indicators(regional)
```

## Reporting checklist

A defensible empirical application should report:

1. The activity unit and reference period.
2. Output, tradable-input, and domestic-factor classification rules.
3. Private price sources and sampling design.
4. Social price construction, parity-price assumptions, and exchange rate.
5. Treatment of land, labour, capital, by-products, taxes, and subsidies.
6. PAM accounts alongside ratios, not ratios alone.
7. Sensitivity or uncertainty results for influential assumptions.

The companion vignette, `vignette("uncertainty", package = "agriPAM")`,
develops the last point.