--- title: "Workflow and counterfactual analysis" output: rmarkdown::html_vignette vignette: > %\VignetteIndexEntry{Workflow and counterfactual analysis} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- ```{r setup, include=FALSE} knitr::opts_chunk$set(collapse = TRUE, comment = "#>") ``` Suppose firms A and B propose a merger. How would prices change, and would a cost saving offset the increase? Fit the observed market once, then solve these scenarios under the same economic assumptions. This guide assumes basic R and an installed `antitrust` package; see the [installation instructions](https://github.com/luciu5/antitrust#installation). Start here, read the [economic models guide](Models.html) ([source](https://github.com/luciu5/antitrust/blob/master/vignettes/Models.Rmd)) to choose assumptions, and use the [architecture guide](Architecture.html) ([source](https://github.com/luciu5/antitrust/blob/master/vignettes/Architecture.Rmd)) when writing an extension. ## Fit a market and simulate the merger Each of three firms initially sells one product. Quantity shares total 80%, leaving 20% for the outside option. Prices are in a common monetary unit; gross margins are proportions of price. `insideSize = 100` sets total inside quantity. Under Logit demand and Bertrand pricing, `calibrate()` recovers demand parameters and marginal costs. A `counterfactual()` describes the proposed change; `simulate()` solves it. ```{r merger} library(antitrust) prices <- c(2, 2.2, 2.5) shares <- c(.35, .25, .20) margins <- c(.40, .35, .30) owners <- c("A", "B", "C") fit <- calibrate( "logit", "bertrand", prices = prices, shares = shares, margins = margins, ownerPre = owners, insideSize = 100 ) merger <- counterfactual(ownership = c("A", "A", "C")) merged <- simulate(fit, merger) data.frame(before = merged@pricePre, after = merged@pricePost, proportional_change = merged@pricePost / merged@pricePre - 1) ``` All three prices rise. The `proportional_change` column uses the original price as denominator: `.10` means a 10% increase, not an increase of .10 monetary units. A and B now internalize sales diverted between their products, which changes their pricing incentives; C also responds. ## Check what calibration matched The returned `AntitrustFit` stores observations, parameters and the fitted S4 model in `fit@model`. The merger result is a `Logit` object with the usual result methods. `summary(fit)` describes stored fitted state; it does not predict a new scenario. ```{r calibration-fit} data.frame(supplied_margin = margins, implied_margin = calcMargins(fit@model), difference = calcMargins(fit@model) - margins) ``` The common Logit price coefficient cannot match all three supplied margins exactly. The implied margins are approximately .426, .336 and .277. These moment discrepancies describe the fit to inputs; they are different from a solver's equilibrium residual and from sampling uncertainty. Calibration does not supply sampling standard errors. Check identifying moments before treating scenario results as evidence; `?calcDiagnostics` explains model-specific checks. ## Add a cost saving or change the products Each call below starts from the **original fitted market**. A proportional cost shock of `-.10` lowers product 2's marginal cost by 10%. ```{r efficiency} efficient_merger <- simulate(fit, counterfactual( ownership = c("A", "A", "C"), costs = c(0, -.10, 0) )) data.frame(merger = merged@pricePost, merger_with_efficiency = efficient_merger@pricePost) ``` The saving lowers product 2's price relative to the merger alone, but product 1's price rises slightly. A multiproduct firm's responses need not move every price in the same direction. Neither calculation changes `fit`. Exit and entry ask different questions about the active product set: ```{r products} exit_result <- simulate(fit, counterfactual(exit = "Prod3")) entrant_result <- simulate(fit, counterfactual( entry = entrant("New", meanval = 0, cost = 1, priceStart = 2) )) exit_result@pricePost entrant_result@pricePost ``` Exit leaves an `NA` in product 3's original price slot. The entrant supplies its own label, mean value, marginal cost and starting price, and shares the fitted Logit price coefficient. Entry requires a model with an entry implementation; `?entrant` describes its inputs. A named `quality = c(Prod1 = .05)` shock would raise product 1's choice weight by 5%, which is not a promise of 5% more sales. ## Separate simultaneous and staged changes Combining changes answers one equilibrium question. This gives the same result as the efficient merger above; conflicting values for the same field are rejected. ```{r combined} combined <- combine_counterfactuals( merger, counterfactual(costs = c(0, -.10, 0)) ) combined_result <- simulate(fit, combined) combined_result@pricePost ``` For a merger followed by a cost saving, `add_step()` requests a second solve starting from the first result. The `CounterfactualPath` retains both equilibria: ```{r staged} path <- simulate(fit, add_step(merger, costs = c(0, -.10, 0))) data.frame(after_merger = result_at(path, 1)@pricePost, after_efficiency = final_result(path)@pricePost) ``` Costs, ownership and product state carry forward according to the fitted model's rules. `simulate(path, counterfactual(...))` can continue a path; `?add_step` and `?simulate` describe that state persistence. ## Choose the correct lifecycle operation New observations call for recalibration. Proposed changes call for simulation. Known parameters and translations have their own routes: | Operation | Use it when… | Result | |:--|:--|:--| | `calibrate()` | You have observations and a model. | Recovers demand parameters and costs using its calibration equations. | | `specify()` | You already know the structural parameters. | Builds a fit without recalibrating demand. | | `simulate()` | You want the equilibrium under a proposed change. | Applies a scenario and solves under the fitted model. | | `update()` | An observed input or calibration option changed. | Calibrates again under the same model specification. | | `respecify()` | You want a registered model translation. | Retains and reconstructs only the information that transition permits. | ```{r calibration-routes} revised <- update(fit, margins = c(.38, .35, .30)) known <- specify("logit", "bertrand", prices = prices, ownerPre = owners, parameters = fit@parameters, insideSize = 100) c(revised_alpha = revised@parameters$alpha, supplied_alpha = known@parameters$alpha) ``` `update()` cannot change the fit's demand, conduct or variant. To identify a different model from observations, call `calibrate()` for that model. A supplied fit has no observed-data calibration call to repeat. A Logit-to-CES translation requires a target curvature `gamma`: ```{r translation} ces_fit <- respecify(fit, demand = "ces", gamma = 2) ces_fit@spec$id ``` This transition preserves baseline prices, shares or quantities, ownership and active products, while deriving CES mean values and recovering costs under the target model. It discards the Logit coefficient and costs. The comparison is local: demand curvature away from the baseline, and merger predictions, can differ. `ces_fit@diagnostics$translation` records the translation; the fit has no CES calibration call, so `update(ces_fit)` cannot silently recalibrate it from Logit margins. Inspect supported transitions with `?model_transition`. Construction or translation can warn that supplied shares are ignored by a non-BLP `specify()` route, or that scenario-neutral pre/post ownership is equal. Those messages describe construction, not failed estimation; inspect unexpected warnings and model-specific diagnostics before proceeding. ## Optional: explore an observed synthetic market When structural parameters are hard to choose, an observed synthetic experiment starts with shares, ownership, known costs and one reference margin. Here two inside firms own two products each; an **additional active reference firm** owns product 5. The five active-product shares sum to one. This is a separate intuition/calibration exercise, with a different price scale from our merger. ```{r synthetic-observed} intuition <- synthetic_market( demand = "logit", supply = "bertrand", n_firms = 2, n_products = 2, shares = c(.2, .1, .15, .25, .3), costs = c(40, 50, 60, 70, 80), reference_margin = .2, seed = 7 ) intuition@diagnostics$synthetic$solved_prices[5] intuition@diagnostics$synthetic[c("share_residual", "foc_residual")] ``` The reference price is `80/(1-.2) = 100`. Other prices satisfy the ownership-adjusted Bertrand first-order conditions. Small share and FOC residuals check this inversion, not empirical recovery or statistical coverage. `?synthetic_market` explains identification inputs and the separate passive outside option in ALM models. Not every model supports every scenario. Use `?counterfactual`, `?supportedModels` and the [models guide](Models.html) ([source](https://github.com/luciu5/antitrust/blob/master/vignettes/Models.Rmd)) for field-specific limits. Tariffs and quotas belong to the sibling `trade` package.