---
title: "Indian Farm Cost Concepts with IndFarmCost"
author: "Chiranjit Mazumder, Mrinmoy Ray, and Utkarsh Tiwari"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Indian Farm Cost Concepts with IndFarmCost}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

## Purpose

`IndFarmCost` provides a reproducible implementation of the principal Indian
farm cost concepts used in farm management and cost-of-cultivation analysis.
The package focuses on transparent formulas and uses base R for all core
calculations.

## Cost-concept structure

The package implements the following identities:

* **A1**: sum of the selected A1 cost components.
* **A2**: A1 + rent paid for leased-in land.
* **B1**: A1 + interest on owned fixed capital excluding land.
* **B2**: B1 + rental value of owned land + rent paid for leased-in land.
* **C1**: B1 + imputed value of family labour.
* **C2**: B2 + imputed value of family labour.
* **C3**: C2 plus a managerial charge; the package default is 10 percent.

The exact valuation of individual inputs can vary with the survey/manual and
reference period. Therefore, the package separates *valuation of components*
from *aggregation into cost concepts*.

## Basic calculation

```{r basic}
library(IndFarmCost)

dat <- farm_cost_example()
fc <- farm_costs(dat)
fc[1:4, c("farm_id", "crop", "A1", "A2", "B1", "B2", "C1", "C2", "C3")]
```

## A2 plus family labour

```{r a2fl}
a2_plus_fl(fc)[1:4]
```

## Group-level analysis

```{r aggregate}
farm_costs_aggregate(fc, by = "crop")
farm_costs_aggregate(fc, by = c("state", "farm_size"), method = "median")
```

## Descriptive statistics

```{r summary}
summarize_costs(fc)
```

## Returns and benefit-cost ratios

```{r returns}
ret <- farm_returns(
  fc,
  main_output = "main_output_q",
  main_price = "main_price_rs_q",
  byproduct_output = "byproduct_output_q",
  byproduct_price = "byproduct_price_rs_q"
)
head(ret[, c("gross_return", "net_C2", "net_C3", "bcr_C2", "bcr_C3")])
```

## Cost of production and break-even price

```{r cop}
byproduct_value <- dat$byproduct_output_q * dat$byproduct_price_rs_q
cost_of_production(fc, "main_output_q", concept = "C2",
                   byproduct_value = byproduct_value)[1:4]
break_even_price(fc, "main_output_q", concept = "C3",
                 byproduct_value = byproduct_value)[1:4]
```

## Cost shares

```{r shares}
shares <- cost_shares(fc, "C3")
head(shares)
```

For every observation, the additive C3 component shares sum to 100 percent,
subject only to floating-point rounding.

## Sensitivity analysis

```{r sensitivity}
cost_sensitivity(dat, "fertilizer", changes = c(-0.20, -0.10, 0, 0.10, 0.20))
```

## Plotting

```{r plot, fig.width=6, fig.height=4}
plot(fc, row = 1)
```

## Custom A1 definitions

If a particular survey uses a different set of items in A1, pass the required
column names explicitly:

```{r custom}
my_a1 <- setdiff(standard_a1_components(), "insurance")
fc_custom <- farm_costs(dat, a1_cols = my_a1)
fc_custom[1:3, c("A1", "C2", "C3")]
```

Alternatively, a pre-computed A1 column can be supplied through `a1_col`.
This design makes the package adaptable while preserving the algebra linking
A1, A2, B1, B2, C1, C2, and C3.