pyRVtest 0.3.2__tar.gz → 0.4.0b2__tar.gz

pyrvtest-0.4.0b2/PKG-INFO

@@ -0,0 +1,243 @@
+Metadata-Version: 2.4
+Name: pyRVtest
+Version: 0.4.0b2
+Summary: Code to perform econometric test of firm conduct
+Home-page: https://github.com/anyatarascina/pyRVtest
+Author: Marco Duarte, Lorenzo Magnolfi, Mikkel Solvsten, Christopher Sullivan, Anya Tarascina
+Author-email: chris.sullivan.econ@gmail.com
+License: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/x-rst
+License-File: LICENSE.txt
+Requires-Dist: numpy>=1.17.0
+Requires-Dist: patsy>=0.5.1
+Requires-Dist: scipy>=1.2.0
+Requires-Dist: sympy>=1.1.0
+Requires-Dist: statsmodels>=0.12.2
+Requires-Dist: pyblp>=1.0.0
+Requires-Dist: jinja2>=3.0
+Requires-Dist: typing_extensions>=4.0
+Provides-Extra: docs
+Requires-Dist: sphinx==5.0.2; extra == "docs"
+Requires-Dist: pandas; extra == "docs"
+Requires-Dist: ipython; extra == "docs"
+Requires-Dist: astunparse; extra == "docs"
+Requires-Dist: sphinx-rtd-theme==1.1.1; extra == "docs"
+Requires-Dist: nbsphinx==0.8.11; extra == "docs"
+Requires-Dist: jinja2==3.0.3; extra == "docs"
+Requires-Dist: docutils==0.17.1; extra == "docs"
+Requires-Dist: numpydoc; extra == "docs"
+Dynamic: author
+Dynamic: author-email
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license
+Dynamic: license-file
+Dynamic: provides-extra
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+This code was written to perform the procedure for testing firm conduct developed in `"Testing Firm Conduct" <https://onlinelibrary.wiley.com/doi/10.3982/QE2319>`_ by Marco Duarte, Lorenzo Magnolfi, Mikkel Sølvsten, and Christopher Sullivan (*Quantitative Economics* 15(3), 2024). It builds on the PyBLP source code (see `Conlon and Gortmaker (2020) <https://onlinelibrary.wiley.com/doi/full/10.1111/1756-2171.12352>`_) - to do so.
+
+The code implements the following features:
+
+* Computes `Rivers and Vuong (2002) <https://onlinelibrary.wiley.com/doi/full/10.1111/1368-423X.t01-1-00071>`_ (RV) test statistics to test a menu of two or more models of firm conduct allowing for the possibility that firms or consumers face per-unit or ad-valorem taxes.
+* Implements the RV test using the variance estimator of `Duarte, Magnolfi, Sølvsten, and Sullivan (2024) <https://onlinelibrary.wiley.com/doi/10.3982/QE2319>`_, including options to adjust for demand estimation error and clustering.
+* Computes the effective F-statistic proposed in `Duarte, Magnolfi, Sølvsten, and Sullivan (2024) <https://onlinelibrary.wiley.com/doi/10.3982/QE2319>`_ to diagnose instrument strength with respect to worst-case size and best-case power of the test, and reports appropriate critical values.
+* Reports `Hansen, Lunde, and Nason (2011) <https://www.jstor.org/stable/41057463?seq=1#metadata_info_tab_contents>`_ MCS p-values for testing more than two models.
+* Ships a class-based ``ConductModel`` API: standard oligopoly (``Bertrand``, ``Cournot``, ``Monopoly``, ``PerfectCompetition``, ``MixCournotBertrand``), generalizations (``PartialCollusion``, ``Vertical``), Dearing, Magnolfi, Quint, Sullivan, and Waldfogel (2024) simple-markup models (``RuleOfThumb(phi)``, ``ConstantMarkup(markup)``), and customization escape hatches (``UserSuppliedMarkups`` for precomputed markup columns, ``CustomConductModel`` for arbitrary markup callables).
+* Ships the full Dearing, Magnolfi, Quint, Sullivan, and Waldfogel (2024) pass-through framework as a diagnostic suite on ``Problem`` and ``ProblemResults``: ``passthrough_summary`` (pre-solve γ-free pair-by-pair structural-feature distances against four DMQSW-keyed metrics), ``passthrough_matrix`` (raw per-candidate pass-through matrix, computed numerically for every conduct class with analytical fast paths for ``Vertical`` and trivial conducts), and ``instrument_channels`` (post-solve channel decomposition for one chosen IV column). Under non-constant marginal cost (``endogenous_cost_component`` set), ``instrument_channels`` automatically applies DMQSS Appendix B's z^e residualization, producing a single unified diagnostic that collapses the Dearing condition and the DMQSS Appendix A.4 distinctness check.
+* Supports ``endogenous_cost_component`` as either a single column name (single endogenous cost variable, the original v0.4 case) or a list of column names (multi-endogenous variables — quadratic cost ``['q', 'q_sq']``, scale + scope ``['log_q', 'log_Q_minus']``, etc., per DMQSS Appendix A.4). Combinable with ``demand_adjustment=True`` and ``costs_type='log'``.
+* **Experimental** — Supports labor-side conduct testing via ``Problem(market_side='labor')`` with ``Monopsony``, ``BertrandWages``, and ``CournotEmployment`` model classes. The labor API is considered experimental in v0.4: the sign convention, column-name defaults, and validation behavior may adjust based on coauthor review (``pyRVtest/models/labor.py`` is flagged for a labor-market-conduct-manuscript sign check). ``NashBargaining`` raises ``NotImplementedError`` and the full ``LaborSupplyBackend`` math (Jacobian, Hessian, demand-adjustment participation) is deferred to v0.5.
+* Provides instrument construction helpers (``pyRVtest.instruments.product``: BLP, differentiation IVs, rival sums; ``pyRVtest.instruments.labor``: Hausman, Bartik).
+* Compatible with PyBLP `Conlon and Gortmaker (2020) <https://onlinelibrary.wiley.com/doi/full/10.1111/1756-2171.12352>`_, so that demand can be estimated with PyBLP, and the estimates are an input to the test for conduct. A ``DemandBackend`` protocol also supports user-supplied demand systems; see ``docs/custom_demand.rst``.
+
+For a full list of references, see the references in `Duarte, Magnolfi, Sølvsten, and Sullivan (2024) <https://onlinelibrary.wiley.com/doi/10.3982/QE2319>`_.
+
+
+Install
+_______
+
+First, you will need to download and install python, which you can do from this `link <https://www.python.org/>`_.
+pyRVtest v0.4 requires Python ``>=3.9``.
+
+You will also need to make sure that you have all package dependencies installed.
+
+**Release candidate (v0.4):** PyPI still serves the older v0.3 line; the v0.4 release candidate is installed from the GitHub tag:
+
+.. code-block::
+
+    pip install git+https://github.com/anyatarascina/pyRVtest@v0.4.0rc15
+
+The v0.4 series will be uploaded to PyPI once it leaves release-candidate status.
+
+**Older v0.3 release:** still available from PyPI for users on the
+prior public API:
+
+.. code-block::
+
+    pip install pyRVtest
+
+To update to a newer version of the package use:
+
+
+.. code-block::
+
+    pip install --upgrade pyRVtest
+
+Dependencies (auto-installed): ``numpy``, ``pandas``, ``statsmodels``,
+``pyblp``, ``patsy``, ``scipy``, ``sympy``, ``jinja2``. Note: ``numpy
+>= 2`` requires ``pyblp >= 1.2``; pyRVtest enforces this at import
+time with a clean ``ImportError`` if the resolved combination is
+inconsistent.
+
+
+Quick start
+___________
+
+A complete pyRVtest run on a synthetic dataset shipped with the package
+(2 single-product firms × 3000 markets, simulated under perfect
+competition with logit demand). Tests four candidate conduct models
+(Bertrand, Cournot, Monopoly, Perfect Competition) using rival cost
+shifters as testing instruments per Dearing, Magnolfi, Quint, Sullivan, and Waldfogel (2024).
+
+.. code-block:: python
+
+    import pyRVtest
+
+    data = pyRVtest.data.load_example()
+    results = pyRVtest.Problem(
+        cost_formulation=pyRVtest.Formulation('1 + z1 + z2'),
+        instrument_formulation=pyRVtest.Formulation('0 + rival_z1 + rival_z2'),
+        models=[
+            pyRVtest.Bertrand(ownership='firm_ids'),
+            pyRVtest.Cournot(ownership='firm_ids'),
+            pyRVtest.Monopoly(),
+            pyRVtest.PerfectCompetition(),
+        ],
+        product_data=data,
+        demand_params={'estimate': 'logit',
+                       'formulation_X': pyRVtest.Formulation('1 + x1'),
+                       'formulation_Z': pyRVtest.Formulation('0 + z1')},
+    ).solve(demand_adjustment=False)
+    print(results)
+
+Output::
+
+    Testing Results - Instruments z0:
+    ===============================================================================================================
+      TRV:                                 |   F-stats:                                   |    MCS:
+    --------  ---  -----  -------  ------  |  ----------  ---  -------  -------  -------  |  --------  ------------
+     models    0     1       2       3     |    models     0      1        2        3     |   models   MCS p-values
+    --------  ---  -----  -------  ------  |  ----------  ---  -------  -------  -------  |  --------  ------------
+       0      nan  6.894  -9.103   6.771   |      0       nan   92.8     170.2    2.6     |     0          0.0
+                    ***     ***     ***    |                   ††† ^^^  ††† ^^^  ††† ^^^  |
+       1      nan   nan   -10.555  0.419   |      1       nan    nan     178.4    0.0     |     1         0.675
+                            ***            |                            ††† ^^^   †††     |
+       2      nan   nan     nan    10.593  |      2       nan    nan      nan      1.4    |     2          0.0
+                                    ***    |                                     ††† ^^^  |
+       3      nan   nan     nan     nan    |      3       nan    nan      nan      nan    |     3          1.0
+    ===============================================================================================================
+
+Models 0/1/2/3 correspond to Bertrand / Cournot / Monopoly / Perfect
+Competition (in the order passed to ``models=``). Each block has rows
+and columns indexed by model number; cell ``[i, j]`` shows the pairwise
+statistic for model ``i`` vs. model ``j``. The diagonal is ``nan`` (a
+model is not compared to itself); off-diagonals carry significance
+markers (``*`` 10%, ``**`` 5%, ``***`` 1% for TRV; ``†``/``^`` for
+F-stat size/power thresholds). The MCS column is per-model.
+
+The truth in this dataset is Perfect Competition. Reading the output:
+
+* **Bertrand** (model 0) and **Monopoly** (model 2) are cleanly
+  rejected: their MCS p-values are both 0.0, and every pairwise TRV
+  involving them is significant at 1% (``***``).
+* **Perfect Competition** (model 3) has the highest MCS p-value (1.0).
+* **Cournot** (model 1) has MCS p-value 0.675 — surviving the
+  confidence set despite not being the truth. The TRV(Cournot, PC) cell
+  is the only insignificant comparison (0.419), and its F-stat is
+  effectively zero. This is the Dearing et al. (2024) degeneracy
+  result: under logit demand, both Cournot and PC have diagonal
+  pass-through matrices (zero off-diagonal pass-through of rival
+  costs), so rival cost shifters cannot distinguish them. To falsify
+  Cournot in favor of PC here, the researcher would need a different
+  instrument such as own or rival product characteristics.
+
+Reader's guide
+______________
+
+Where to go next, by audience:
+
+* **End users** running the test on their own data — `Tutorial <https://pyrvtest.readthedocs.io/en/stable/tutorial.html>`_ (worked notebooks).
+* **Migrating from v0.3** — ``docs/migrating_to_v0.4.rst``. The class-based ``ConductModel`` API, ``demand_params=dict(rho=...)``, and Problem-level ``unit_tax`` / ``advalorem_tax`` kwargs are all new in v0.4; the legacy per-model ``ModelFormulation``, ``sigma`` alias, and per-model tax kwargs continue to work for one or two releases with ``DeprecationWarning``.
+* **Custom demand backend** — ``docs/custom_demand.rst`` covers the ``DemandBackend`` protocol.
+* **AI coding assistants and contributors** — ``AGENTS.md`` at the repo root is the living contract for code state, layout, and conventions. ``docs/agent_guide.rst`` is the longer architecture walkthrough (also surfaced via ``pyRVtest.show_agent_guide()``). ``CONTRIBUTING.md`` covers dev environment setup, running tests / lint / docs locally, and the conventions for adding new conduct models or demand backends.
+
+
+Citing the package
+__________________
+
+When using ``pyRVtest`` in research, please cite the package itself plus the methodology papers your usage exercises.
+
+**Package:**
+
+Duarte, M., L. Magnolfi, M. Sølvsten, C. Sullivan, and A. Tarascina (2023): “pyRVtest: A Python package for testing firm conduct,” https://github.com/anyatarascina/pyRVtest.
+
+**Methodology papers:**
+
+* For the Rivers-Vuong test, F-statistic, MCS p-values, and demand-adjustment correction:
+
+  Duarte, M., L. Magnolfi, M. Sølvsten, and C. Sullivan (2024): `“Testing Firm Conduct,” <https://onlinelibrary.wiley.com/doi/10.3982/QE2319>`_ *Quantitative Economics*, 15(3), 571-606.
+
+* For pass-through diagnostics, simple-markup models (``RuleOfThumb``, ``ConstantMarkup``), and the instrument-relevance / falsification framework:
+
+  Dearing, A., L. Magnolfi, D. Quint, C. Sullivan, and S. Waldfogel (2024): `“Learning Firm Conduct: Pass-Through as a Foundation for Instrument Relevance,” <https://www.nber.org/papers/w32863>`_ NBER Working Paper No. 32863, August 2024.
+
+* For the endogenous-cost-component first-stage correction (non-linear cost):
+
+  Duarte, M., L. Magnolfi, D. Quint, M. Sølvsten, and C. Sullivan (2026): “Conduct and Scale Economies: Evaluating Tariffs in the US Automobile Market,” Working paper.
+
+BibTeX:
+
+.. code-block:: bibtex
+
+    @misc{pyrvtest,
+        author={Marco Duarte and Lorenzo Magnolfi and Mikkel S{\o}lvsten and Christopher Sullivan and Anya Tarascina},
+        title={\texttt{pyRVtest}: A Python package for testing firm conduct},
+        howpublished={\url{https://github.com/anyatarascina/pyRVtest}},
+        year={2023}
+    }
+
+    @article{dmss2024,
+        author={Marco Duarte and Lorenzo Magnolfi and Mikkel S{\o}lvsten and Christopher Sullivan},
+        title={Testing Firm Conduct},
+        journal={Quantitative Economics},
+        volume={15},
+        number={3},
+        pages={571--606},
+        year={2024},
+        doi={10.3982/QE2319}
+    }
+
+    @techreport{dmqsw2024,
+        author={Adam Dearing and Lorenzo Magnolfi and Daniel Quint and Christopher Sullivan and Sarah Waldfogel},
+        title={Learning Firm Conduct: Pass-Through as a Foundation for Instrument Relevance},
+        institution={National Bureau of Economic Research},
+        type={NBER Working Paper},
+        number={32863},
+        month={August},
+        year={2024}
+    }
+
+    @article{dmqss2026,
+        author={Marco Duarte and Lorenzo Magnolfi and Daniel Quint and Mikkel S{\o}lvsten and Christopher Sullivan},
+        title={Conduct and Scale Economies: Evaluating Tariffs in the US Automobile Market},
+        year={2026}
+    }
+
+Bugs and Requests
+_________________
+
+Please use the `GitHub issue tracker <https://github.com/anyatarascina/pyRVtest/issues>`_ to submit bugs or to request features.

pyrvtest-0.4.0b2/README.rst

@@ -0,0 +1,207 @@
+pyRVtest
+========
+
+.. docs-start
+
+This code was written to perform the procedure for testing firm conduct developed in `"Testing Firm Conduct" <https://onlinelibrary.wiley.com/doi/10.3982/QE2319>`_ by Marco Duarte, Lorenzo Magnolfi, Mikkel Sølvsten, and Christopher Sullivan (*Quantitative Economics* 15(3), 2024). It builds on the PyBLP source code (see `Conlon and Gortmaker (2020) <https://onlinelibrary.wiley.com/doi/full/10.1111/1756-2171.12352>`_) - to do so.
+
+The code implements the following features:
+
+* Computes `Rivers and Vuong (2002) <https://onlinelibrary.wiley.com/doi/full/10.1111/1368-423X.t01-1-00071>`_ (RV) test statistics to test a menu of two or more models of firm conduct allowing for the possibility that firms or consumers face per-unit or ad-valorem taxes.
+* Implements the RV test using the variance estimator of `Duarte, Magnolfi, Sølvsten, and Sullivan (2024) <https://onlinelibrary.wiley.com/doi/10.3982/QE2319>`_, including options to adjust for demand estimation error and clustering.
+* Computes the effective F-statistic proposed in `Duarte, Magnolfi, Sølvsten, and Sullivan (2024) <https://onlinelibrary.wiley.com/doi/10.3982/QE2319>`_ to diagnose instrument strength with respect to worst-case size and best-case power of the test, and reports appropriate critical values.
+* Reports `Hansen, Lunde, and Nason (2011) <https://www.jstor.org/stable/41057463?seq=1#metadata_info_tab_contents>`_ MCS p-values for testing more than two models.
+* Ships a class-based ``ConductModel`` API: standard oligopoly (``Bertrand``, ``Cournot``, ``Monopoly``, ``PerfectCompetition``, ``MixCournotBertrand``), generalizations (``PartialCollusion``, ``Vertical``), Dearing, Magnolfi, Quint, Sullivan, and Waldfogel (2024) simple-markup models (``RuleOfThumb(phi)``, ``ConstantMarkup(markup)``), and customization escape hatches (``UserSuppliedMarkups`` for precomputed markup columns, ``CustomConductModel`` for arbitrary markup callables).
+* Ships the full Dearing, Magnolfi, Quint, Sullivan, and Waldfogel (2024) pass-through framework as a diagnostic suite on ``Problem`` and ``ProblemResults``: ``passthrough_summary`` (pre-solve γ-free pair-by-pair structural-feature distances against four DMQSW-keyed metrics), ``passthrough_matrix`` (raw per-candidate pass-through matrix, computed numerically for every conduct class with analytical fast paths for ``Vertical`` and trivial conducts), and ``instrument_channels`` (post-solve channel decomposition for one chosen IV column). Under non-constant marginal cost (``endogenous_cost_component`` set), ``instrument_channels`` automatically applies DMQSS Appendix B's z^e residualization, producing a single unified diagnostic that collapses the Dearing condition and the DMQSS Appendix A.4 distinctness check.
+* Supports ``endogenous_cost_component`` as either a single column name (single endogenous cost variable, the original v0.4 case) or a list of column names (multi-endogenous variables — quadratic cost ``['q', 'q_sq']``, scale + scope ``['log_q', 'log_Q_minus']``, etc., per DMQSS Appendix A.4). Combinable with ``demand_adjustment=True`` and ``costs_type='log'``.
+* **Experimental** — Supports labor-side conduct testing via ``Problem(market_side='labor')`` with ``Monopsony``, ``BertrandWages``, and ``CournotEmployment`` model classes. The labor API is considered experimental in v0.4: the sign convention, column-name defaults, and validation behavior may adjust based on coauthor review (``pyRVtest/models/labor.py`` is flagged for a labor-market-conduct-manuscript sign check). ``NashBargaining`` raises ``NotImplementedError`` and the full ``LaborSupplyBackend`` math (Jacobian, Hessian, demand-adjustment participation) is deferred to v0.5.
+* Provides instrument construction helpers (``pyRVtest.instruments.product``: BLP, differentiation IVs, rival sums; ``pyRVtest.instruments.labor``: Hausman, Bartik).
+* Compatible with PyBLP `Conlon and Gortmaker (2020) <https://onlinelibrary.wiley.com/doi/full/10.1111/1756-2171.12352>`_, so that demand can be estimated with PyBLP, and the estimates are an input to the test for conduct. A ``DemandBackend`` protocol also supports user-supplied demand systems; see ``docs/custom_demand.rst``.
+
+For a full list of references, see the references in `Duarte, Magnolfi, Sølvsten, and Sullivan (2024) <https://onlinelibrary.wiley.com/doi/10.3982/QE2319>`_.
+
+
+Install
+_______
+
+First, you will need to download and install python, which you can do from this `link <https://www.python.org/>`_.
+pyRVtest v0.4 requires Python ``>=3.9``.
+
+You will also need to make sure that you have all package dependencies installed.
+
+**Release candidate (v0.4):** PyPI still serves the older v0.3 line; the v0.4 release candidate is installed from the GitHub tag:
+
+.. code-block::
+
+    pip install git+https://github.com/anyatarascina/pyRVtest@v0.4.0rc15
+
+The v0.4 series will be uploaded to PyPI once it leaves release-candidate status.
+
+**Older v0.3 release:** still available from PyPI for users on the
+prior public API:
+
+.. code-block::
+
+    pip install pyRVtest
+
+To update to a newer version of the package use:
+
+
+.. code-block::
+
+    pip install --upgrade pyRVtest
+
+Dependencies (auto-installed): ``numpy``, ``pandas``, ``statsmodels``,
+``pyblp``, ``patsy``, ``scipy``, ``sympy``, ``jinja2``. Note: ``numpy
+>= 2`` requires ``pyblp >= 1.2``; pyRVtest enforces this at import
+time with a clean ``ImportError`` if the resolved combination is
+inconsistent.
+
+
+Quick start
+___________
+
+A complete pyRVtest run on a synthetic dataset shipped with the package
+(2 single-product firms × 3000 markets, simulated under perfect
+competition with logit demand). Tests four candidate conduct models
+(Bertrand, Cournot, Monopoly, Perfect Competition) using rival cost
+shifters as testing instruments per Dearing, Magnolfi, Quint, Sullivan, and Waldfogel (2024).
+
+.. code-block:: python
+
+    import pyRVtest
+
+    data = pyRVtest.data.load_example()
+    results = pyRVtest.Problem(
+        cost_formulation=pyRVtest.Formulation('1 + z1 + z2'),
+        instrument_formulation=pyRVtest.Formulation('0 + rival_z1 + rival_z2'),
+        models=[
+            pyRVtest.Bertrand(ownership='firm_ids'),
+            pyRVtest.Cournot(ownership='firm_ids'),
+            pyRVtest.Monopoly(),
+            pyRVtest.PerfectCompetition(),
+        ],
+        product_data=data,
+        demand_params={'estimate': 'logit',
+                       'formulation_X': pyRVtest.Formulation('1 + x1'),
+                       'formulation_Z': pyRVtest.Formulation('0 + z1')},
+    ).solve(demand_adjustment=False)
+    print(results)
+
+Output::
+
+    Testing Results - Instruments z0:
+    ===============================================================================================================
+      TRV:                                 |   F-stats:                                   |    MCS:
+    --------  ---  -----  -------  ------  |  ----------  ---  -------  -------  -------  |  --------  ------------
+     models    0     1       2       3     |    models     0      1        2        3     |   models   MCS p-values
+    --------  ---  -----  -------  ------  |  ----------  ---  -------  -------  -------  |  --------  ------------
+       0      nan  6.894  -9.103   6.771   |      0       nan   92.8     170.2    2.6     |     0          0.0
+                    ***     ***     ***    |                   ††† ^^^  ††† ^^^  ††† ^^^  |
+       1      nan   nan   -10.555  0.419   |      1       nan    nan     178.4    0.0     |     1         0.675
+                            ***            |                            ††† ^^^   †††     |
+       2      nan   nan     nan    10.593  |      2       nan    nan      nan      1.4    |     2          0.0
+                                    ***    |                                     ††† ^^^  |
+       3      nan   nan     nan     nan    |      3       nan    nan      nan      nan    |     3          1.0
+    ===============================================================================================================
+
+Models 0/1/2/3 correspond to Bertrand / Cournot / Monopoly / Perfect
+Competition (in the order passed to ``models=``). Each block has rows
+and columns indexed by model number; cell ``[i, j]`` shows the pairwise
+statistic for model ``i`` vs. model ``j``. The diagonal is ``nan`` (a
+model is not compared to itself); off-diagonals carry significance
+markers (``*`` 10%, ``**`` 5%, ``***`` 1% for TRV; ``†``/``^`` for
+F-stat size/power thresholds). The MCS column is per-model.
+
+The truth in this dataset is Perfect Competition. Reading the output:
+
+* **Bertrand** (model 0) and **Monopoly** (model 2) are cleanly
+  rejected: their MCS p-values are both 0.0, and every pairwise TRV
+  involving them is significant at 1% (``***``).
+* **Perfect Competition** (model 3) has the highest MCS p-value (1.0).
+* **Cournot** (model 1) has MCS p-value 0.675 — surviving the
+  confidence set despite not being the truth. The TRV(Cournot, PC) cell
+  is the only insignificant comparison (0.419), and its F-stat is
+  effectively zero. This is the Dearing et al. (2024) degeneracy
+  result: under logit demand, both Cournot and PC have diagonal
+  pass-through matrices (zero off-diagonal pass-through of rival
+  costs), so rival cost shifters cannot distinguish them. To falsify
+  Cournot in favor of PC here, the researcher would need a different
+  instrument such as own or rival product characteristics.
+
+Reader's guide
+______________
+
+Where to go next, by audience:
+
+* **End users** running the test on their own data — `Tutorial <https://pyrvtest.readthedocs.io/en/stable/tutorial.html>`_ (worked notebooks).
+* **Migrating from v0.3** — ``docs/migrating_to_v0.4.rst``. The class-based ``ConductModel`` API, ``demand_params=dict(rho=...)``, and Problem-level ``unit_tax`` / ``advalorem_tax`` kwargs are all new in v0.4; the legacy per-model ``ModelFormulation``, ``sigma`` alias, and per-model tax kwargs continue to work for one or two releases with ``DeprecationWarning``.
+* **Custom demand backend** — ``docs/custom_demand.rst`` covers the ``DemandBackend`` protocol.
+* **AI coding assistants and contributors** — ``AGENTS.md`` at the repo root is the living contract for code state, layout, and conventions. ``docs/agent_guide.rst`` is the longer architecture walkthrough (also surfaced via ``pyRVtest.show_agent_guide()``). ``CONTRIBUTING.md`` covers dev environment setup, running tests / lint / docs locally, and the conventions for adding new conduct models or demand backends.
+
+
+Citing the package
+__________________
+
+When using ``pyRVtest`` in research, please cite the package itself plus the methodology papers your usage exercises.
+
+**Package:**
+
+Duarte, M., L. Magnolfi, M. Sølvsten, C. Sullivan, and A. Tarascina (2023): “pyRVtest: A Python package for testing firm conduct,” https://github.com/anyatarascina/pyRVtest.
+
+**Methodology papers:**
+
+* For the Rivers-Vuong test, F-statistic, MCS p-values, and demand-adjustment correction:
+
+  Duarte, M., L. Magnolfi, M. Sølvsten, and C. Sullivan (2024): `“Testing Firm Conduct,” <https://onlinelibrary.wiley.com/doi/10.3982/QE2319>`_ *Quantitative Economics*, 15(3), 571-606.
+
+* For pass-through diagnostics, simple-markup models (``RuleOfThumb``, ``ConstantMarkup``), and the instrument-relevance / falsification framework:
+
+  Dearing, A., L. Magnolfi, D. Quint, C. Sullivan, and S. Waldfogel (2024): `“Learning Firm Conduct: Pass-Through as a Foundation for Instrument Relevance,” <https://www.nber.org/papers/w32863>`_ NBER Working Paper No. 32863, August 2024.
+
+* For the endogenous-cost-component first-stage correction (non-linear cost):
+
+  Duarte, M., L. Magnolfi, D. Quint, M. Sølvsten, and C. Sullivan (2026): “Conduct and Scale Economies: Evaluating Tariffs in the US Automobile Market,” Working paper.
+
+BibTeX:
+
+.. code-block:: bibtex
+
+    @misc{pyrvtest,
+        author={Marco Duarte and Lorenzo Magnolfi and Mikkel S{\o}lvsten and Christopher Sullivan and Anya Tarascina},
+        title={\texttt{pyRVtest}: A Python package for testing firm conduct},
+        howpublished={\url{https://github.com/anyatarascina/pyRVtest}},
+        year={2023}
+    }
+
+    @article{dmss2024,
+        author={Marco Duarte and Lorenzo Magnolfi and Mikkel S{\o}lvsten and Christopher Sullivan},
+        title={Testing Firm Conduct},
+        journal={Quantitative Economics},
+        volume={15},
+        number={3},
+        pages={571--606},
+        year={2024},
+        doi={10.3982/QE2319}
+    }
+
+    @techreport{dmqsw2024,
+        author={Adam Dearing and Lorenzo Magnolfi and Daniel Quint and Christopher Sullivan and Sarah Waldfogel},
+        title={Learning Firm Conduct: Pass-Through as a Foundation for Instrument Relevance},
+        institution={National Bureau of Economic Research},
+        type={NBER Working Paper},
+        number={32863},
+        month={August},
+        year={2024}
+    }
+
+    @article{dmqss2026,
+        author={Marco Duarte and Lorenzo Magnolfi and Daniel Quint and Mikkel S{\o}lvsten and Christopher Sullivan},
+        title={Conduct and Scale Economies: Evaluating Tariffs in the US Automobile Market},
+        year={2026}
+    }
+
+Bugs and Requests
+_________________
+
+Please use the `GitHub issue tracker <https://github.com/anyatarascina/pyRVtest/issues>`_ to submit bugs or to request features.