%\VignetteIndexEntry{Agricultural Marketing Efficiency and Price Spread with agriME}
%\VignetteEngine{utils::Sweave}
%\VignetteEncoding{UTF-8}
\documentclass[a4paper,11pt]{article}
\usepackage[margin=1in]{geometry}
\usepackage{booktabs}
\usepackage{longtable}
\usepackage{Sweave}

\title{Agricultural Marketing Efficiency and Price Spread with \texttt{agriME}}
\author{Chiranjit Mazumder, Bikramjeet Ghose, and Pramit Pandit}
\date{Package version 0.1.0}

\begin{document}
\maketitle

\section{Purpose}

The \texttt{agriME} package provides a consistent accounting workflow for
agricultural price-spread and marketing-efficiency studies. It can calculate
indicators directly from channel totals or reconstruct them from producer,
wholesaler, retailer, processor, and other intermediary stages. The package
also checks whether the recorded prices, costs, and margins reconcile.

All compared values must refer to the same commodity quality, product form,
place, period, and quantity. A difference caused by grading, processing,
storage duration, or quantity loss is not automatically an inefficiency.

\section{Core equations}

Let $P_f$ be the net producer price, $P_c$ the consumer price, $MC$ total
marketing cost, and $MM$ total net intermediary margin. The package reports:

\begin{longtable}{p{0.31\textwidth}p{0.23\textwidth}p{0.36\textwidth}}
\toprule
Indicator & Equation & Interpretation \\
\midrule
Price spread & $P_c-P_f$ & Monetary gap between consumer and producer \\
Producer's share & $100P_f/P_c$ & Percentage of consumer expenditure reaching the producer \\
Acharya efficiency & $P_f/(MC+MM)$ & Producer return relative to channel cost and net margin \\
Shepherd ratio & $P_c/MC$ & Consumer value per unit of marketing cost \\
Conventional efficiency & $(P_c-P_f)/MC$ & Marketing value added per unit of marketing cost \\
\bottomrule
\end{longtable}

When $P_c=P_f+MC+MM$, Acharya efficiency is also
$P_c/(MC+MM)-1$. The package retains any failure of this identity as an
\texttt{accounting\_gap} rather than silently reallocating it.

\section{Direct calculation from channel totals}

<<totals>>=
library(agriME)

marketing_metrics(
  producer_price = 1900,
  consumer_price = 3150,
  marketing_cost = 510,
  marketing_margin = 740,
  channel = "Producer-Wholesaler-Retailer"
)
@

\section{Audited stage-level accounts}

The example data contain four illustrative tomato channels. They are synthetic
and should not be cited as market evidence.

<<channels>>=
data(tomato_channels)
fit <- analyse_channels(tomato_channels)
summary(fit)[, c(
  "channel", "producer_price", "consumer_price", "price_spread",
  "producer_share_percent", "acharya_efficiency"
)]
@

The direct channel has only a producer stage. In that case the producer's sale
price is the consumer price, while producer-borne marketing cost explains the
difference between gross and net producer price.

<<decomposition, fig=TRUE, width=7, height=5>>=
plot(fit, type = "decomposition", las = 2, cex.names = 0.75)
@

\section{Consumer-price decomposition and ranking}

<<rupee-ranking>>=
consumer_rupee(fit)
rank_channels(fit)
@

The default ranking gives equal weights to Acharya efficiency, producer share,
and the inverse of price-spread percentage. Analysts should report alternative
weighting schemes because rankings necessarily reflect the chosen criteria.

\section{Bootstrap uncertainty}

Repeated price observations allow sampling uncertainty to be shown instead of
reporting each efficiency ratio as if it were known without error.

<<bootstrap>>=
data(market_observations)
boot <- bootstrap_marketing_metrics(
  market_observations,
  marketing_margin = "marketing_margin",
  channel = "channel",
  weight = "volume_qtl",
  R = 199,
  seed = 2026
)
subset(boot$summary, metric == "acharya_efficiency")
@

<<bootstrap-figure, fig=TRUE, width=7, height=5>>=
plot(boot, metric = "acharya_efficiency")
@

Percentile intervals describe empirical resampling variability within the
observed channel records. They do not correct a non-random survey design,
measurement error, omitted quality differences, or selection into channels.

\section{Sensitivity and efficiency targets}

<<sensitivity>>=
sens <- marketing_sensitivity(
  producer_price = 1900,
  consumer_price = 3150,
  marketing_cost = 510,
  marketing_margin = 740,
  producer_change = c(-0.05, 0, 0.05),
  cost_change = c(-0.10, 0, 0.10)
)
head(sens[, c(
  "producer_change", "cost_change", "price_spread",
  "producer_share_percent", "acharya_efficiency"
)])

efficiency_target(
  target = 2,
  method = "acharya",
  solve_for = "marketing_cost",
  producer_price = 1900,
  marketing_margin = 740
)
@

\section{Physical loss}

If 100 kg are purchased but only 92 kg are sold, the acquisition cost per sold
kilogram is higher than the quoted purchase price. The loss-adjusted function
makes that conversion explicit.

<<loss>>=
loss_adjusted_margin(
  purchase_price = 20,
  sale_price = 28,
  quantity_purchased = 100,
  quantity_sold = 92,
  marketing_cost = 180,
  cost_basis = "lot"
)
@

\section{Responsible interpretation}

These ratios are descriptive measures of channel accounts. A channel with a
higher ratio is not automatically more competitive, equitable, resilient, or
socially desirable. Interpretation should incorporate services added, risk
bearing, market power, seasonal storage, product losses, credit, quality, and
transaction volume. Causal statements require a separate research design.

\end{document}