cowmrp 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (231) hide show
  1. cowmrp-0.1.0/CITATION.cff +31 -0
  2. cowmrp-0.1.0/LICENSE +21 -0
  3. cowmrp-0.1.0/MANIFEST.in +10 -0
  4. cowmrp-0.1.0/PKG-INFO +277 -0
  5. cowmrp-0.1.0/README.md +230 -0
  6. cowmrp-0.1.0/examples/cow_comparison_example.py +18 -0
  7. cowmrp-0.1.0/examples/keep_cull_example.py +33 -0
  8. cowmrp-0.1.0/examples/whole_farm_example.py +39 -0
  9. cowmrp-0.1.0/examples/youngstock_example.py +25 -0
  10. cowmrp-0.1.0/guide/README.md +46 -0
  11. cowmrp-0.1.0/guide/assets/F01_milk_curves.png +0 -0
  12. cowmrp-0.1.0/guide/assets/F08_steady_state_herd.png +0 -0
  13. cowmrp-0.1.0/guide/assets/F11_rewards_per_day.png +0 -0
  14. cowmrp-0.1.0/guide/assets/fig_farm_lactation.png +0 -0
  15. cowmrp-0.1.0/guide/assets/fig_farm_origin.png +0 -0
  16. cowmrp-0.1.0/guide/assets/fig_farm_status.png +0 -0
  17. cowmrp-0.1.0/guide/assets/fig_perf_memory.png +0 -0
  18. cowmrp-0.1.0/guide/assets/fig_perf_per_cow.png +0 -0
  19. cowmrp-0.1.0/guide/assets/fig_perf_runtime.png +0 -0
  20. cowmrp-0.1.0/guide/assets/fig_perf_stages.png +0 -0
  21. cowmrp-0.1.0/guide/assets/fig_time_resolution.png +0 -0
  22. cowmrp-0.1.0/guide/build.py +337 -0
  23. cowmrp-0.1.0/guide/build_all.py +38 -0
  24. cowmrp-0.1.0/guide/check_links.py +20 -0
  25. cowmrp-0.1.0/guide/requirements-docs.txt +9 -0
  26. cowmrp-0.1.0/guide/resolution_worker.py +37 -0
  27. cowmrp-0.1.0/guide/sync.py +490 -0
  28. cowmrp-0.1.0/guide/tutorial.html +210 -0
  29. cowmrp-0.1.0/guide/web/README.md +23 -0
  30. cowmrp-0.1.0/guide/web/build_web.py +771 -0
  31. cowmrp-0.1.0/guide/web/check_methods.py +150 -0
  32. cowmrp-0.1.0/guide/web/content/defaults.html +43 -0
  33. cowmrp-0.1.0/guide/web/content/getting-started.html +44 -0
  34. cowmrp-0.1.0/guide/web/content/home.html +63 -0
  35. cowmrp-0.1.0/guide/web/content/keepcull-workbook.html +61 -0
  36. cowmrp-0.1.0/guide/web/content/notebooks.html +47 -0
  37. cowmrp-0.1.0/guide/web/content/performance.html +97 -0
  38. cowmrp-0.1.0/guide/web/content/quickstart.py +10 -0
  39. cowmrp-0.1.0/guide/web/content/science.html +54 -0
  40. cowmrp-0.1.0/guide/web/content/time_resolution.py +15 -0
  41. cowmrp-0.1.0/guide/web/performance_page.py +343 -0
  42. cowmrp-0.1.0/guide/web/theme/fonts/OFL.txt +103 -0
  43. cowmrp-0.1.0/guide/web/theme/fonts/cmu-serif-500-italic.woff2 +0 -0
  44. cowmrp-0.1.0/guide/web/theme/fonts/cmu-serif-500-roman.woff2 +0 -0
  45. cowmrp-0.1.0/guide/web/theme/fonts/cmu-serif-700-italic.woff2 +0 -0
  46. cowmrp-0.1.0/guide/web/theme/fonts/cmu-serif-700-roman.woff2 +0 -0
  47. cowmrp-0.1.0/guide/web/theme/fonts/cmu-typewriter-text-500-roman.woff2 +0 -0
  48. cowmrp-0.1.0/guide/web/theme/web.css +128 -0
  49. cowmrp-0.1.0/guide/web/theme/web.js +60 -0
  50. cowmrp-0.1.0/pyproject.toml +59 -0
  51. cowmrp-0.1.0/runners/README.md +63 -0
  52. cowmrp-0.1.0/runners/__init__.py +0 -0
  53. cowmrp-0.1.0/runners/_shared/__init__.py +0 -0
  54. cowmrp-0.1.0/runners/_shared/checks/__init__.py +0 -0
  55. cowmrp-0.1.0/runners/_shared/checks/check_documentation.py +266 -0
  56. cowmrp-0.1.0/runners/_shared/checks/validate_model_documentation.py +157 -0
  57. cowmrp-0.1.0/runners/_shared/checks/verify_baseline.py +80 -0
  58. cowmrp-0.1.0/runners/_shared/checks/verify_migration_parity.py +94 -0
  59. cowmrp-0.1.0/runners/_shared/checks/verify_mrp_boundary.py +39 -0
  60. cowmrp-0.1.0/runners/_shared/common.py +125 -0
  61. cowmrp-0.1.0/runners/_shared/engine_run.py +57 -0
  62. cowmrp-0.1.0/runners/_shared/new_domain.py +111 -0
  63. cowmrp-0.1.0/runners/_shared/notebook/mrp_engine.ipynb +519 -0
  64. cowmrp-0.1.0/runners/_shared/review.py +231 -0
  65. cowmrp-0.1.0/runners/_shared/run_notebook.py +46 -0
  66. cowmrp-0.1.0/runners/_shared/scale_benchmark.py +494 -0
  67. cowmrp-0.1.0/runners/_shared/scale_report.py +231 -0
  68. cowmrp-0.1.0/runners/_shared/views.py +509 -0
  69. cowmrp-0.1.0/runners/cow/__init__.py +0 -0
  70. cowmrp-0.1.0/runners/cow/checks/__init__.py +0 -0
  71. cowmrp-0.1.0/runners/cow/checks/audit_conception_sensitivity.py +108 -0
  72. cowmrp-0.1.0/runners/cow/checks/audit_exits.py +103 -0
  73. cowmrp-0.1.0/runners/cow/checks/audit_later_lactation_sensitivity.py +115 -0
  74. cowmrp-0.1.0/runners/cow/checks/audit_methods.py +80 -0
  75. cowmrp-0.1.0/runners/cow/checks/audit_metrics.py +226 -0
  76. cowmrp-0.1.0/runners/cow/checks/audit_milk.py +31 -0
  77. cowmrp-0.1.0/runners/cow/checks/audit_registry.py +10 -0
  78. cowmrp-0.1.0/runners/cow/checks/audit_repro.py +112 -0
  79. cowmrp-0.1.0/runners/cow/checks/audit_state_timing.py +118 -0
  80. cowmrp-0.1.0/runners/cow/checks/audit_tables.py +29 -0
  81. cowmrp-0.1.0/runners/cow/checks/compare_state_conventions.py +137 -0
  82. cowmrp-0.1.0/runners/cow/checks/verify_biological_consistency.py +227 -0
  83. cowmrp-0.1.0/runners/cow/checks/verify_farm.py +120 -0
  84. cowmrp-0.1.0/runners/cow/checks/verify_lactationcurve_milk_income_reward.py +273 -0
  85. cowmrp-0.1.0/runners/cow/checks/verify_lookup_export.py +231 -0
  86. cowmrp-0.1.0/runners/cow/checks/verify_reward_vector.py +258 -0
  87. cowmrp-0.1.0/runners/cow/checks/verify_state_semantics.py +227 -0
  88. cowmrp-0.1.0/runners/cow/checks/verify_state_space.py +261 -0
  89. cowmrp-0.1.0/runners/cow/checks/verify_state_sufficiency.py +109 -0
  90. cowmrp-0.1.0/runners/cow/checks/verify_time_discretization.py +144 -0
  91. cowmrp-0.1.0/runners/cow/checks/verify_value_comparisons.py +250 -0
  92. cowmrp-0.1.0/runners/cow/farm/__init__.py +0 -0
  93. cowmrp-0.1.0/runners/cow/farm/build.py +97 -0
  94. cowmrp-0.1.0/runners/cow/farm/generate.py +86 -0
  95. cowmrp-0.1.0/runners/cow/farm/keepcull.py +120 -0
  96. cowmrp-0.1.0/runners/cow/farm/simulate.py +103 -0
  97. cowmrp-0.1.0/runners/cow/plots/__init__.py +0 -0
  98. cowmrp-0.1.0/runners/cow/plots/_plot_data.py +186 -0
  99. cowmrp-0.1.0/runners/cow/plots/export_lookup_tables.py +356 -0
  100. cowmrp-0.1.0/runners/cow/plots/plot_validation.py +392 -0
  101. cowmrp-0.1.0/runners/cow/plots/plot_validation_plotly.py +460 -0
  102. cowmrp-0.1.0/runners/cow/profile_build.py +88 -0
  103. cowmrp-0.1.0/runners/cow/projection.py +135 -0
  104. cowmrp-0.1.0/runners/cow/run.py +104 -0
  105. cowmrp-0.1.0/runners/cow/scale_inputs.py +21 -0
  106. cowmrp-0.1.0/runners/run_all.py +50 -0
  107. cowmrp-0.1.0/runners/youngstock/__init__.py +0 -0
  108. cowmrp-0.1.0/runners/youngstock/checks/__init__.py +0 -0
  109. cowmrp-0.1.0/runners/youngstock/plots/__init__.py +0 -0
  110. cowmrp-0.1.0/runners/youngstock/run.py +121 -0
  111. cowmrp-0.1.0/runners/youngstock/scale_inputs.py +19 -0
  112. cowmrp-0.1.0/setup.cfg +4 -0
  113. cowmrp-0.1.0/src/cowmrp/__init__.py +14 -0
  114. cowmrp-0.1.0/src/cowmrp/data/__init__.py +18 -0
  115. cowmrp-0.1.0/src/cowmrp/data/example_herd.csv +201 -0
  116. cowmrp-0.1.0/src/cowmrp/data/example_herd.meta.json +10 -0
  117. cowmrp-0.1.0/src/cowmrp/data/example_herd_raw.csv +201 -0
  118. cowmrp-0.1.0/src/cowmrp/domain.py +123 -0
  119. cowmrp-0.1.0/src/cowmrp/domains/__init__.py +0 -0
  120. cowmrp-0.1.0/src/cowmrp/domains/cow/__init__.py +0 -0
  121. cowmrp-0.1.0/src/cowmrp/domains/cow/curves.py +52 -0
  122. cowmrp-0.1.0/src/cowmrp/domains/cow/data/README.md +24 -0
  123. cowmrp-0.1.0/src/cowmrp/domains/cow/economics.py +205 -0
  124. cowmrp-0.1.0/src/cowmrp/domains/cow/evidence/__init__.py +8 -0
  125. cowmrp-0.1.0/src/cowmrp/domains/cow/evidence/miller2008.py +22 -0
  126. cowmrp-0.1.0/src/cowmrp/domains/cow/evidence/pinedo2010.py +119 -0
  127. cowmrp-0.1.0/src/cowmrp/domains/cow/farm.py +538 -0
  128. cowmrp-0.1.0/src/cowmrp/domains/cow/flows.py +28 -0
  129. cowmrp-0.1.0/src/cowmrp/domains/cow/keepcull.py +104 -0
  130. cowmrp-0.1.0/src/cowmrp/domains/cow/keepcull_excel.py +217 -0
  131. cowmrp-0.1.0/src/cowmrp/domains/cow/lookup_tables.py +233 -0
  132. cowmrp-0.1.0/src/cowmrp/domains/cow/lookup_workbook.py +224 -0
  133. cowmrp-0.1.0/src/cowmrp/domains/cow/notebook_hooks.py +28 -0
  134. cowmrp-0.1.0/src/cowmrp/domains/cow/parameters.py +779 -0
  135. cowmrp-0.1.0/src/cowmrp/domains/cow/probabilities/__init__.py +123 -0
  136. cowmrp-0.1.0/src/cowmrp/domains/cow/probabilities/abortion.py +279 -0
  137. cowmrp-0.1.0/src/cowmrp/domains/cow/probabilities/base.py +117 -0
  138. cowmrp-0.1.0/src/cowmrp/domains/cow/probabilities/calving.py +150 -0
  139. cowmrp-0.1.0/src/cowmrp/domains/cow/probabilities/conception.py +234 -0
  140. cowmrp-0.1.0/src/cowmrp/domains/cow/probabilities/culling.py +205 -0
  141. cowmrp-0.1.0/src/cowmrp/domains/cow/probabilities/hazard_tables.py +108 -0
  142. cowmrp-0.1.0/src/cowmrp/domains/cow/probabilities/mortality.py +170 -0
  143. cowmrp-0.1.0/src/cowmrp/domains/cow/projection.py +197 -0
  144. cowmrp-0.1.0/src/cowmrp/domains/cow/registry.py +203 -0
  145. cowmrp-0.1.0/src/cowmrp/domains/cow/review.py +113 -0
  146. cowmrp-0.1.0/src/cowmrp/domains/cow/rewards/__init__.py +179 -0
  147. cowmrp-0.1.0/src/cowmrp/domains/cow/rewards/base.py +152 -0
  148. cowmrp-0.1.0/src/cowmrp/domains/cow/rewards/cull_reward.py +40 -0
  149. cowmrp-0.1.0/src/cowmrp/domains/cow/rewards/environment/__init__.py +213 -0
  150. cowmrp-0.1.0/src/cowmrp/domains/cow/rewards/environment/co2.py +123 -0
  151. cowmrp-0.1.0/src/cowmrp/domains/cow/rewards/environment/enteric_methane.py +134 -0
  152. cowmrp-0.1.0/src/cowmrp/domains/cow/rewards/environment/manure_methane.py +117 -0
  153. cowmrp-0.1.0/src/cowmrp/domains/cow/rewards/environment/n2o.py +167 -0
  154. cowmrp-0.1.0/src/cowmrp/domains/cow/rewards/environment/nitrogen.py +161 -0
  155. cowmrp-0.1.0/src/cowmrp/domains/cow/rewards/environment/reward_enteric_methane.py +26 -0
  156. cowmrp-0.1.0/src/cowmrp/domains/cow/rewards/environment/reward_manure_methane.py +33 -0
  157. cowmrp-0.1.0/src/cowmrp/domains/cow/rewards/environment/reward_n2o.py +33 -0
  158. cowmrp-0.1.0/src/cowmrp/domains/cow/rewards/environment/reward_nitrogen.py +37 -0
  159. cowmrp-0.1.0/src/cowmrp/domains/cow/rewards/feed_cost.py +49 -0
  160. cowmrp-0.1.0/src/cowmrp/domains/cow/rewards/lactationcurve_milk_income.py +330 -0
  161. cowmrp-0.1.0/src/cowmrp/domains/cow/rewards/milk_income.py +112 -0
  162. cowmrp-0.1.0/src/cowmrp/domains/cow/rewards/milk_produced.py +33 -0
  163. cowmrp-0.1.0/src/cowmrp/domains/cow/rewards/mortality_cost.py +16 -0
  164. cowmrp-0.1.0/src/cowmrp/domains/cow/rewards/pregnancy_reward.py +25 -0
  165. cowmrp-0.1.0/src/cowmrp/domains/cow/rewards/replacement_cost.py +61 -0
  166. cowmrp-0.1.0/src/cowmrp/domains/cow/rewards/reproduction_cost.py +57 -0
  167. cowmrp-0.1.0/src/cowmrp/domains/cow/state_checks.py +67 -0
  168. cowmrp-0.1.0/src/cowmrp/domains/cow/state_constraints.py +181 -0
  169. cowmrp-0.1.0/src/cowmrp/domains/cow/states.py +70 -0
  170. cowmrp-0.1.0/src/cowmrp/domains/cow/tables.py +209 -0
  171. cowmrp-0.1.0/src/cowmrp/domains/cow/transitions.py +110 -0
  172. cowmrp-0.1.0/src/cowmrp/domains/cow/value_comparisons.py +317 -0
  173. cowmrp-0.1.0/src/cowmrp/domains/youngstock/__init__.py +0 -0
  174. cowmrp-0.1.0/src/cowmrp/domains/youngstock/notebook_hooks.py +4 -0
  175. cowmrp-0.1.0/src/cowmrp/domains/youngstock/parameters.py +368 -0
  176. cowmrp-0.1.0/src/cowmrp/domains/youngstock/probabilities/__init__.py +61 -0
  177. cowmrp-0.1.0/src/cowmrp/domains/youngstock/probabilities/birth_outcomes.py +137 -0
  178. cowmrp-0.1.0/src/cowmrp/domains/youngstock/probabilities/heifer_repro.py +188 -0
  179. cowmrp-0.1.0/src/cowmrp/domains/youngstock/probabilities/mortality.py +109 -0
  180. cowmrp-0.1.0/src/cowmrp/domains/youngstock/review.py +129 -0
  181. cowmrp-0.1.0/src/cowmrp/domains/youngstock/states.py +69 -0
  182. cowmrp-0.1.0/src/cowmrp/domains/youngstock/transitions.py +93 -0
  183. cowmrp-0.1.0/src/cowmrp/io/__init__.py +4 -0
  184. cowmrp-0.1.0/src/cowmrp/io/export.py +36 -0
  185. cowmrp-0.1.0/src/cowmrp/model.py +173 -0
  186. cowmrp-0.1.0/src/cowmrp/mrp/__init__.py +1 -0
  187. cowmrp-0.1.0/src/cowmrp/mrp/core.py +520 -0
  188. cowmrp-0.1.0/src/cowmrp/mrp/engine.py +221 -0
  189. cowmrp-0.1.0/src/cowmrp/mrp/simulator.py +221 -0
  190. cowmrp-0.1.0/src/cowmrp/mrp/utils.py +36 -0
  191. cowmrp-0.1.0/src/cowmrp/runner.py +8 -0
  192. cowmrp-0.1.0/src/cowmrp/viz/__init__.py +1 -0
  193. cowmrp-0.1.0/src/cowmrp/viz/distribution.py +44 -0
  194. cowmrp-0.1.0/src/cowmrp/viz/farm.py +266 -0
  195. cowmrp-0.1.0/src/cowmrp/viz/projection.py +118 -0
  196. cowmrp-0.1.0/src/cowmrp.egg-info/PKG-INFO +277 -0
  197. cowmrp-0.1.0/src/cowmrp.egg-info/SOURCES.txt +229 -0
  198. cowmrp-0.1.0/src/cowmrp.egg-info/dependency_links.txt +1 -0
  199. cowmrp-0.1.0/src/cowmrp.egg-info/requires.txt +31 -0
  200. cowmrp-0.1.0/src/cowmrp.egg-info/top_level.txt +1 -0
  201. cowmrp-0.1.0/tests/README.md +40 -0
  202. cowmrp-0.1.0/tests/__init__.py +0 -0
  203. cowmrp-0.1.0/tests/baselines/farm_golden.json +1 -0
  204. cowmrp-0.1.0/tests/baselines/golden_month.json +21 -0
  205. cowmrp-0.1.0/tests/baselines/keepcull_golden.json +1 -0
  206. cowmrp-0.1.0/tests/baselines/projection_golden.json +593 -0
  207. cowmrp-0.1.0/tests/boundary/test_domain_independence.py +75 -0
  208. cowmrp-0.1.0/tests/conftest.py +47 -0
  209. cowmrp-0.1.0/tests/install/test_clean_install.py +125 -0
  210. cowmrp-0.1.0/tests/integration/test_cow_economics.py +290 -0
  211. cowmrp-0.1.0/tests/integration/test_cow_farm.py +260 -0
  212. cowmrp-0.1.0/tests/integration/test_cow_keepcull.py +144 -0
  213. cowmrp-0.1.0/tests/integration/test_cow_keepcull_excel.py +126 -0
  214. cowmrp-0.1.0/tests/integration/test_cow_projection.py +132 -0
  215. cowmrp-0.1.0/tests/integration/test_doc_sync.py +75 -0
  216. cowmrp-0.1.0/tests/integration/test_environment_outputs.py +21 -0
  217. cowmrp-0.1.0/tests/integration/test_group_probs.py +107 -0
  218. cowmrp-0.1.0/tests/integration/test_model.py +106 -0
  219. cowmrp-0.1.0/tests/integration/test_runners_use_package.py +36 -0
  220. cowmrp-0.1.0/tests/machine_domain/__init__.py +2 -0
  221. cowmrp-0.1.0/tests/machine_domain/notebook_hooks.py +7 -0
  222. cowmrp-0.1.0/tests/machine_domain/parameters.py +6 -0
  223. cowmrp-0.1.0/tests/machine_domain/probabilities/__init__.py +7 -0
  224. cowmrp-0.1.0/tests/machine_domain/rewards.py +5 -0
  225. cowmrp-0.1.0/tests/machine_domain/states.py +4 -0
  226. cowmrp-0.1.0/tests/machine_domain/transitions.py +13 -0
  227. cowmrp-0.1.0/tests/performance/test_performance.py +66 -0
  228. cowmrp-0.1.0/tests/regression/test_scientific_reference.py +45 -0
  229. cowmrp-0.1.0/tests/unit/test_core.py +95 -0
  230. cowmrp-0.1.0/tests/unit/test_domain.py +55 -0
  231. cowmrp-0.1.0/tests/unit/test_licence_consistency.py +34 -0
@@ -0,0 +1,31 @@
1
+ # Citation metadata. ORCIDs, funding, the release date and the DOI are added when available.
2
+ cff-version: 1.2.0
3
+ message: "If you use this software, please cite it using the metadata in this file."
4
+ title: "cowmrp: Markov reward process models of dairy cattle"
5
+ abstract: >-
6
+ A Python package of Markov reward process (MRP) models of dairy cattle: a domain-free MRP engine with a cow domain
7
+ (state: lactation, days in milk, days pregnant) and a youngstock domain. It values cows (keep or replace), projects a herd
8
+ forward with the expected distribution, stochastic paths or Monte Carlo, and reports environmental outputs beside economic ones.
9
+ type: software
10
+ version: 0.1.0
11
+ license: MIT
12
+ repository-code: "https://github.com/Bovi-analytics/cow-mrp"
13
+ url: "https://bovi-analytics.github.io/cow-mrp/"
14
+ keywords:
15
+ - markov reward process
16
+ - dairy cattle
17
+ - replacement
18
+ - simulation
19
+ - livestock
20
+ authors:
21
+ - family-names: Sharma
22
+ given-names: Sumit
23
+ affiliation: "Department of Animal Science, Cornell University, Ithaca, New York, USA"
24
+ # orcid: pending (not provided yet; add as "https://orcid.org/0000-0000-0000-0000")
25
+ - family-names: Hansen
26
+ given-names: Edward
27
+ # orcid: pending (not provided yet; add as "https://orcid.org/0000-0000-0000-0000")
28
+ - family-names: Hostens
29
+ given-names: Miel
30
+ affiliation: "Department of Animal Science, Cornell University, Ithaca, New York, USA"
31
+ # orcid: pending (not provided yet; add as "https://orcid.org/0000-0000-0000-0000")
cowmrp-0.1.0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Bovi-analytics Lab, Cornell University
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,10 @@
1
+ include LICENSE README.md CITATION.cff
2
+ recursive-include examples *.py
3
+ recursive-include tests *.py *.md *.json *.csv
4
+ recursive-include runners *.py *.md *.ipynb *.json *.csv
5
+ recursive-include guide *.py *.md *.txt *.html *.css *.js *.png *.woff2 OFL.txt
6
+ prune runners/*/outputs
7
+ prune guide/site
8
+ prune guide/web/site
9
+ prune guide/web/outputs
10
+ global-exclude __pycache__ *.py[cod]
cowmrp-0.1.0/PKG-INFO ADDED
@@ -0,0 +1,277 @@
1
+ Metadata-Version: 2.4
2
+ Name: cowmrp
3
+ Version: 0.1.0
4
+ Summary: Markov reward process (MRP) models of dairy cattle: a domain-free MRP engine with cow and youngstock domains
5
+ Author: Sumit Sharma, Edward Hansen, Miel Hostens
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/Bovi-analytics/cow-mrp
8
+ Project-URL: Source, https://github.com/Bovi-analytics/cow-mrp
9
+ Project-URL: Documentation, https://bovi-analytics.github.io/cow-mrp/
10
+ Project-URL: Issues, https://github.com/Bovi-analytics/cow-mrp/issues
11
+ Keywords: markov reward process,dairy cattle,replacement,simulation,livestock
12
+ Classifier: Development Status :: 3 - Alpha
13
+ Classifier: Intended Audience :: Science/Research
14
+ Classifier: Programming Language :: Python :: 3
15
+ Classifier: Programming Language :: Python :: 3.10
16
+ Classifier: Programming Language :: Python :: 3.11
17
+ Classifier: Programming Language :: Python :: 3.12
18
+ Classifier: Programming Language :: Python :: 3.13
19
+ Classifier: Topic :: Scientific/Engineering
20
+ Requires-Python: >=3.10
21
+ Description-Content-Type: text/markdown
22
+ License-File: LICENSE
23
+ Requires-Dist: numpy
24
+ Requires-Dist: pandas
25
+ Requires-Dist: scipy
26
+ Provides-Extra: plot
27
+ Requires-Dist: matplotlib; extra == "plot"
28
+ Requires-Dist: plotly; extra == "plot"
29
+ Provides-Extra: excel
30
+ Requires-Dist: openpyxl; extra == "excel"
31
+ Provides-Extra: parquet
32
+ Requires-Dist: pyarrow; extra == "parquet"
33
+ Provides-Extra: bench
34
+ Requires-Dist: psutil; extra == "bench"
35
+ Provides-Extra: notebook
36
+ Requires-Dist: jupyter; extra == "notebook"
37
+ Provides-Extra: milkbot
38
+ Requires-Dist: lactationcurve; extra == "milkbot"
39
+ Provides-Extra: dev
40
+ Requires-Dist: pytest; extra == "dev"
41
+ Requires-Dist: ruff; extra == "dev"
42
+ Requires-Dist: build; extra == "dev"
43
+ Requires-Dist: twine; extra == "dev"
44
+ Provides-Extra: all
45
+ Requires-Dist: cowmrp[bench,excel,notebook,parquet,plot]; extra == "all"
46
+ Dynamic: license-file
47
+
48
+ # CowMRP (`cowmrp`)
49
+
50
+ Markov reward process (MRP) models of dairy cattle, as a Python package. A **domain-free MRP engine** (`cowmrp.mrp`) plus two animal domains:
51
+ the **cow** (state `(lactation, dim, dp)`: lactation number, days in milk, days pregnant, in model-step units) and the **youngstock** chain
52
+ (calf, heifer, first calving). The engine knows no animal, so you can write your own domain.
53
+
54
+ It is for researchers and farm advisers who want to value cows (keep or replace), project a herd forward, and look at environmental outputs
55
+ beside economic ones. The scientific model is the reference implementation; the package changes how it is reached, not what it computes.
56
+
57
+ ## Install
58
+
59
+ ```
60
+ pip install cowmrp # engine + domains (numpy, pandas, scipy)
61
+ pip install "cowmrp[plot]" # + matplotlib, plotly: dashboards and projection figures
62
+ pip install -e ".[dev,plot,parquet]" # from a clone of this repository (Python 3.10 or newer)
63
+ ```
64
+
65
+ The installed package contains the engine, the domains, the plotting helpers and the 200-cow tutorial herd. The runner scripts (`runners/`), `examples/`,
66
+ `user_examples/` (the example notebooks), the tests and the documentation sources are in the source repository, https://github.com/Bovi-analytics/cow-mrp; the commands in
67
+ "Running the scripts" and "Tests" below are for a clone.
68
+
69
+ ## Quick start: a whole farm in a few lines
70
+
71
+ ```python
72
+ from cowmrp.data import example_herd_path # 200 synthetic cows shipped with the package
73
+ from cowmrp.model import build_model
74
+ from cowmrp.domains.cow.farm import load_herd, project_herd
75
+ from cowmrp.viz.farm import write_farm_outputs
76
+
77
+ model = build_model("cow") # month resolution (see "Time resolution")
78
+ herd = load_herd(example_herd_path(), model) # or your own CSV / DataFrame
79
+ result = project_herd(herd, model, mode="expected", steps=24)
80
+ write_farm_outputs(result, "farm_results") # CSV tables + dashboard.html + dashboard_plotly.html
81
+ ```
82
+
83
+ **Example notebooks.** The folder [`user_examples/`](user_examples/) holds five Jupyter notebooks that start with `pip install "cowmrp[plot,excel]"`, import only from the installed package and run on a CSV that you replace with your own: cows from a CSV with keep/cull, a farm projection with the interactive Plotly dashboard, individual rewards, a youngstock farm, and a domain of your own on the generic engine. They are not part of the installed package; get them with `git clone https://github.com/Bovi-analytics/cow-mrp.git` (or Download ZIP on GitHub) and see `user_examples/README.md` and the Examples page of the documentation site.
84
+
85
+ A complete script is `examples/whole_farm_example.py`; the same steps are walked through in the [tutorial](https://bovi-analytics.github.io/cow-mrp/tutorial.html) of the documentation site (online once the repository is public; the source is `guide/tutorial.html`).
86
+
87
+ ## What the package does
88
+
89
+ | Task | Entry point | Notes |
90
+ |---|---|---|
91
+ | Build and solve a model | `cowmrp.model.build_model("cow" \| "youngstock")`, `evaluate`, `evolve_distribution` | Any domain that follows the interface in `cowmrp.domain` |
92
+ | **One cow, or cow A against cow B** | `cowmrp.domains.cow.projection.compare_cows(scenarios, years=2)` | Rewards and distributions over time for cows given as `lactation`, `dim_days`, `dp_days`; figures in `cowmrp.viz.projection` |
93
+ | **Keep or cull** | `cowmrp.domains.cow.keepcull.keep_cull_table(herd, model, years=(1,3,5), offer=900)` | Break-even sale value of every cow = value of keeping her minus value of replacing her now; a KEEP/CULL call only when you give an `offer`. Salvage is not credited in the model's own comparison (a documented limitation). `cowmrp.domains.cow.keepcull_excel.write_keepcull_workbook` (`--excel`, needs `cowmrp[excel]`) writes an Excel workbook that shows the sale of the cow now as its own column; see below |
94
+ | **Whole-farm projection** | `cowmrp.domains.cow.farm.project_herd(herd, model, mode, steps)` | Open / pregnant / dry, lactation, DIM stage; cows never replaced versus replaced; per-cow values |
95
+ | **Load farm records** | `cowmrp.domains.cow.farm.load_herd(csv_or_dataframe, model)` | Raw records or already-mapped `state_id`; every problem reported with row and `cow_id` |
96
+ | Environmental outputs | `cowmrp.domains.cow.rewards.environment` | The physical quantities (enteric and manure methane, N2O, nitrogen, CO2) are always computed by `compute_environment()` and do not depend on any price; the monetary environmental rewards are off by default and enter the economic total only if you enable them |
97
+ | Synthetic herd | `cowmrp.domains.cow.farm.generate_herd(model, mode, n_cows, seed)` | `equilibrium` (the model's steady-state herd), `mix`, `exact` |
98
+
99
+ ### Farm data
100
+
101
+ One row per cow, described in **real days** (never health or DNB flags, which are not state variables):
102
+
103
+ | Column | Meaning |
104
+ |---|---|
105
+ | `cow_id` | optional, unique (1..n when absent) |
106
+ | `lactation` | 1 to 10 |
107
+ | `dim_days` | days in milk, 0 or more |
108
+ | `dp_days` | days pregnant, 0 for an open cow (default 0) |
109
+ | `state_id` | alternative: the model state of the cow, as written by `generate_herd` (if given together with the days they must agree) |
110
+ | `uim`, `up` | alternative to the days columns: the model's step indices |
111
+
112
+ A cow is mapped to a state exactly as the original runner `runners/cow/farm/generate.py` always did. `load_herd` adds checks only: missing columns, non-numeric
113
+ values, out-of-range lactation, negative days, duplicate `cow_id`, a combination the model has no state for (the message lists the nearest valid states), and a herd
114
+ file made under another time resolution. A DataFrame is accepted wherever a CSV path is.
115
+
116
+ ### Tutorial dataset
117
+
118
+ `cowmrp.data.example_herd_path()` is a 200-cow **synthetic** herd (cows drawn from the model's own steady-state herd, seed 42, month resolution) in the model's schema;
119
+ `example_raw_herd_path()` is the same cows as a farmer would export them (`cow_id, lactation, dim_days, dp_days`). No real farm records are included.
120
+
121
+ ### Time resolution
122
+
123
+ The model steps in `month` (30 d, default), `week` (7 d) or `day` (1 d). Set it **before Python starts**: `COW_TIME_UNIT=week python my_script.py`.
124
+ The resolution is not a display setting: it rebuilds the state space, the transition probabilities (rescaled to the step), the reward of every state (the rate integrated over the days
125
+ one step spans) and so the expected values. `dim` and `dp` are step indices of the chosen resolution, not calendar days; durations such as gestation stay in real days.
126
+ One process holds one resolution (the cow domain reads it once, when imported); `compare_cows` runs scenarios of another resolution in worker processes for you.
127
+ A herd file made at one resolution is refused at another; regenerate it. The day resolution is large: use it deliberately.
128
+
129
+ <!-- GEN:resolution_table -->
130
+ | Resolution | Step | States | Transitions | Example cow as `(dim, dp)` |
131
+ |---|---:|---:|---:|---:|
132
+ | month | 30 d | 2,970 | 9,040 | (4, 2) |
133
+ | week | 7 d | 42,290 | 131,197 | (20, 9) |
134
+ | day | 1 d | 1,952,060 | 6,109,989 | (149, 60) |
135
+
136
+ The example cow is in her second lactation, 150 days in milk and 60 days pregnant; `dim` and `dp` count model steps, so the same cow has different state coordinates at each resolution.
137
+ <!-- /GEN -->
138
+
139
+ <!-- GEN:state_counts -->
140
+ State counts (month resolution): 2,970 states, of which 1,210 are reachable from the replacement state (the default is the full table), 9,040 transitions.
141
+ <!-- /GEN -->
142
+
143
+ ### Expected versus stochastic and Monte Carlo
144
+
145
+ `project_herd(..., mode=...)`:
146
+
147
+ | Mode | What it computes | When to use |
148
+ |---|---|---|
149
+ | `expected` (default) | The exact distribution of the herd after each step, split into cows never replaced and cows replaced at least once. Deterministic, fast | Almost always: planning, comparing scenarios, dashboards |
150
+ | `stochastic` | One sampled path per cow (`seed`) | To see a single plausible herd history |
151
+ | `monte_carlo` | Many sampled herds (`sims`), reported as mean, standard deviation, 5th and 95th percentile | When the spread, not only the mean, matters (small herds) |
152
+
153
+ For a large herd the three agree on the mean; Monte Carlo is the slow one, so it is never run unless you select it.
154
+
155
+ ## Repository layout
156
+
157
+ | Folder | Purpose |
158
+ |---|---|
159
+ | `src/cowmrp/mrp/` | Domain-free MRP engine: `core.py` (math), `engine.py` (spec orchestration and validation), `simulator.py`, `utils.py` |
160
+ | `src/cowmrp/domain.py`, `model.py` | The domain interface (`load_domain`, `validate_domain`) and the generic build/solve API |
161
+ | `src/cowmrp/domains/` | One folder per domain: `cow/` (parameters, states, probabilities, transitions, rewards, lookup tables, evidence, `farm.py`, `keepcull.py`, `projection.py`) and `youngstock/` |
162
+ | `src/cowmrp/viz/`, `io/`, `data/` | Figures and dashboards, model-file export, the shipped example herd |
163
+ | `runners/` | Scripts that use the package: one module per domain (`cow/`, `youngstock/`) with `run.py`, `checks/`, `plots/`, `outputs/<kind>/`; `_shared/` common code |
164
+ | `examples/` | Four runnable scripts (`whole_farm_example.py`, ...) |
165
+ | `user_examples/` | Five example notebooks with their synthetic CSV files, a custom-domain folder and the installed-wheel test (`check_installed.py`); obtained from GitHub, not in the package |
166
+ | `tests/` | Fast default suite plus opt-in `slow` and `install` tests (see `tests/README.md`) |
167
+ | `guide/` | Documentation: the tutorial, a file guide and API reference built by `guide/build.py`, and the website in `guide/web/` |
168
+
169
+ Dependency direction is one-way: `cowmrp.mrp` <- `cowmrp.domain` <- `cowmrp.model` <- `cowmrp.domains` <- `runners`
170
+ (check: `python runners/_shared/checks/verify_mrp_boundary.py`). `runners/README.md` explains the runner modules.
171
+
172
+ **Add a domain:** write a package with `parameters`, `states`, `probabilities`, `transitions` (and optional `rewards`) following `cowmrp.domain`, then
173
+ `cowmrp.domain.load_domain("your_package")`. `python runners/_shared/new_domain.py <name>` creates the stubs and the runner module.
174
+
175
+ ## Running the scripts (research workflows)
176
+
177
+ All scripts run from any directory. They are kept and call the package.
178
+
179
+ ```
180
+ python runners/run_all.py # every module -> runners/<module>/outputs/
181
+ python runners/cow/run.py --review # review pages for a domain expert
182
+ python runners/cow/projection.py # edit SCENARIOS at the top first (cow A vs cow B)
183
+ python runners/cow/farm/generate.py # a synthetic herd -> runners/cow/outputs/farm/farm_data.csv
184
+ python runners/cow/farm/simulate.py --mode expected --steps 24 # herd projection and dashboards
185
+ python runners/cow/farm/keepcull.py --years 1,3,5 --offer 900 # keep/cull table
186
+ python runners/cow/farm/keepcull.py --excel # + keepcull_accounting.xlsx: KEEP, REPLACE, salvage, break-even per cow (needs cowmrp[excel])
187
+ python runners/cow/farm/keepcull.py --set REARING_COST=2800 # scenario run: override an economic setting for this run only (see below)
188
+ python runners/cow/checks/verify_farm.py # and the other verify_* scripts in runners/*/checks/
189
+ python runners/_shared/scale_benchmark.py --quick # cost and accuracy against herd size
190
+ ```
191
+
192
+ ### Keeping the documentation in step with the code
193
+
194
+ Numbers and tables that the documents repeat (state counts, reward components, overridable economic settings) are read from the package, not typed:
195
+
196
+ ```
197
+ python guide/build_all.py # rewrite the generated blocks, build both sites, then check that nothing is stale
198
+ python guide/sync.py check # exit 1 if a block, token, number or built site is out of date
199
+ python guide/sync.py impact <file> # which documents and outputs depend on a source file
200
+ ```
201
+
202
+ Generated blocks sit between `<!-- GEN:name -->` and `<!-- /GEN -->` in this file; do not edit inside them. `{{NAME}}` tokens in the tutorial and site pages are expanded at build time.
203
+
204
+ ### Keep/cull accounting workbook
205
+
206
+ `python runners/cow/farm/keepcull.py --excel` also writes `keepcull_accounting.xlsx`: for every cow and horizon, the KEEP value, the REPLACE value, the immediate salvage (an indicative estimate, or the net offer you type for that cow), the break-even offer, ΔQ and the decision, as Excel formulas. It is a reporting output; the model, the reward vector and `keep_cull_table` are unchanged. The estimate is indicative (state-based body weight; the model's dressing percentage, beef price and culling fee) and a typed offer is the net cash received. The `Checks` sheet shows that the break-even column reproduces `keep_cull_table`. Terms, every column and formula, the treatment of future salvage and replacement costs, and the limitations are on the documentation site page *Keep/cull workbook* (`guide/web/content/keepcull-workbook.html`). The column table below is generated from the package:
207
+
208
+ <!-- GEN:excel_columns -->
209
+ | Col | Header | Kind | Formula (row r) | Meaning |
210
+ |---|---|---|---|---|
211
+ | A | cow_id | from the herd file | | Cow identifier from the herd file (row number if the herd has none). |
212
+ | B | state_id | from the herd file | | Model state of the cow (index into the state table of the current time resolution). |
213
+ | C | lactation | from the herd file | | Lactation number (copied when the herd has it). |
214
+ | D | dim_days | from the herd file | | Days in milk (copied when the herd has it). |
215
+ | E | dp_days | from the herd file | | Days pregnant (copied when the herd has it). |
216
+ | F | body_weight_kg (model, state-based) | model value (pasted) | | Body weight of the state in kg, computed as cull_reward computes it for the salvage value. A model estimate, not the weight on the day of sale. |
217
+ | G | V_total(s) | model value (pasted) | | V_total(s): expected discounted total reward of the cow over the horizon (milk, pregnancy, cull, mortality, feed, reproduction), future cull salvage included. |
218
+ | H | PV future replacement costs (s) | model value (pasted) | | PV_rc(s): expected discounted cost of the future replacements of this cow and of her replacements over the horizon. |
219
+ | I | KEEP = V_total - PV_rc | Excel formula | `=Gr-Hr` | KEEP: expected future value of keeping the cow, every future replacement cost paid. |
220
+ | J | estimated salvage S_est | Excel formula | `=Fr*Inputs!$B$3*Inputs!$B$2-Inputs!$B$4` | Estimated salvage now: body weight x dressing percentage x beef price - culling fee (Inputs B3, B2, B4). |
221
+ | K | actual net offer (type here, optional) | input (yellow) | | Actual net offer for this cow, typed by the user (optional). Net cash received: the culling fee is not subtracted again. |
222
+ | L | S used | Excel formula | `=IF(Kr="",Jr,Kr)` | Salvage used: the typed offer if there is one, otherwise the estimate. |
223
+ | M | V_keep(heifer) | Excel formula | `=Inputs!$E$<horizon row>` | V_keep(h): value of a fresh replacement heifer (state (1, 0, 0)) over the same horizon (Inputs sheet). |
224
+ | N | rearing cost C | Excel formula | `=Inputs!$B$<horizon row>` | C: rearing cost of one replacement, charged once, now (Inputs sheet). |
225
+ | O | REPLACE = S + V_keep(h) - C | Excel formula | `=Lr+Mr-Nr` | REPLACE: salvage used + value of the replacement heifer - rearing cost. |
226
+ | P | Delta Q = KEEP - REPLACE | Excel formula | `=Ir-Or` | Delta Q = KEEP - REPLACE. Positive: keeping is better; negative: replacing is better. |
227
+ | Q | break-even offer | Excel formula | `=Ir-Mr+Nr` | Break-even offer: the salvage at which KEEP and REPLACE are equal. |
228
+ | R | decision | Excel formula | `=IF(Lr>Qr,"CULL","KEEP")` | Decision: CULL when the salvage used is above the break-even offer, otherwise KEEP. |
229
+ | S | S source | Excel formula | `=IF(Kr="","estimate","offer")` | Which salvage was used: the estimate or a typed offer. |
230
+ | T | value from keep_cull_table (check) | check | | value_<N>y from keep_cull_table for the same cow and horizon (pasted from the model). |
231
+ | U | difference to check | check | `=Qr-Tr` | Break-even offer minus the reference value; must be 0 (to rounding). |
232
+ <!-- /GEN -->
233
+
234
+ ### Economic scenarios
235
+
236
+ Prices and costs of the cow rewards (milk, feed, beef, calf, rearing, culling fee and the service costs) can be overridden for one run, without touching the model's defaults:
237
+
238
+ ```python
239
+ from cowmrp.model import build_model
240
+ from cowmrp.domains.cow.economics import economic_overrides, reprice_model
241
+ from cowmrp.domains.cow.keepcull import keep_cull_table
242
+
243
+ model = build_model("cow")
244
+ with economic_overrides(MILK_PRICE_PER_KG=0.52, REARING_COST=2800):
245
+ scenario = reprice_model(model) # rewards recomputed; states, probabilities and the transition matrix are the same objects
246
+ table = keep_cull_table(herd, scenario) # keep/cull inside the block, so REARING_COST applies
247
+ ```
248
+
249
+ Settings not named keep their defaults, and every value is restored when the block ends. The discount rate and the sale offer are already arguments of the keep/cull functions.
250
+ The override replaces module-level values, so it is **not thread-safe**: use it in sequential scripts and notebooks. The supported settings, with unit, currency and the source recorded in the repository, are in `cowmrp.domains.cow.economics.ECONOMIC_SETTINGS`. Biological and management values are not overridable.
251
+
252
+ ## Tests
253
+
254
+ ```
255
+ pytest # fast set, about 1 minute: expected-distribution checks, month and week
256
+ pytest -m slow # day resolution and weekly Monte Carlo parity, about 13 minutes
257
+ pytest -m install # builds the wheel and installs it in a clean virtual environment (needs network)
258
+ ```
259
+
260
+ ## Documentation
261
+
262
+ The site is built from the code by `python guide/build.py` and published to GitHub Pages by `.github/workflows/guide.yml` when `src/`, `guide/`,
263
+ `examples/`, `user_examples/`, `README.md` or `pyproject.toml` change on `main`.
264
+
265
+ ## License and citation
266
+
267
+ Authors: Sumit Sharma (first author, primary developer), Edward Hansen and Miel Hostens (supervisor), Department of Animal Science, Cornell University, Ithaca, New York, USA.
268
+ CowMRP is released under the MIT licence (SPDX `MIT`), see `LICENSE`. Copyright (c) 2026 Bovi-analytics Lab, Cornell University. How to cite: see `CITATION.cff` (a Zenodo DOI will be added after the first public release).
269
+
270
+ Third-party material keeps its own licence: the Computer Modern (CMU) web fonts bundled with the documentation theme (`guide/web/theme/fonts/`, not in the installed package) are under the SIL Open Font License 1.1, whose text (`OFL.txt`) is kept with them; the interactive dashboards embed plotly.js (MIT), which keeps its own notice in the generated files. Dependencies such as numpy, pandas, scipy, matplotlib, plotly and openpyxl are installed from PyPI under their own licences and are not redistributed here.
271
+
272
+ ## Notes
273
+
274
+ - The state reward vector does not contain `replacement_cost`; it is charged in the cow-versus-heifer comparison
275
+ (`replacement_comparison`, used by the keep/cull table), see the module docstring of `cowmrp.domains.cow.rewards`.
276
+ - Lookup tables can be overridden by CSV files (`src/cowmrp/domains/cow/data/README.md`).
277
+ - All generated files are written to `runners/<module>/outputs/`, which is not tracked.
cowmrp-0.1.0/README.md ADDED
@@ -0,0 +1,230 @@
1
+ # CowMRP (`cowmrp`)
2
+
3
+ Markov reward process (MRP) models of dairy cattle, as a Python package. A **domain-free MRP engine** (`cowmrp.mrp`) plus two animal domains:
4
+ the **cow** (state `(lactation, dim, dp)`: lactation number, days in milk, days pregnant, in model-step units) and the **youngstock** chain
5
+ (calf, heifer, first calving). The engine knows no animal, so you can write your own domain.
6
+
7
+ It is for researchers and farm advisers who want to value cows (keep or replace), project a herd forward, and look at environmental outputs
8
+ beside economic ones. The scientific model is the reference implementation; the package changes how it is reached, not what it computes.
9
+
10
+ ## Install
11
+
12
+ ```
13
+ pip install cowmrp # engine + domains (numpy, pandas, scipy)
14
+ pip install "cowmrp[plot]" # + matplotlib, plotly: dashboards and projection figures
15
+ pip install -e ".[dev,plot,parquet]" # from a clone of this repository (Python 3.10 or newer)
16
+ ```
17
+
18
+ The installed package contains the engine, the domains, the plotting helpers and the 200-cow tutorial herd. The runner scripts (`runners/`), `examples/`,
19
+ `user_examples/` (the example notebooks), the tests and the documentation sources are in the source repository, https://github.com/Bovi-analytics/cow-mrp; the commands in
20
+ "Running the scripts" and "Tests" below are for a clone.
21
+
22
+ ## Quick start: a whole farm in a few lines
23
+
24
+ ```python
25
+ from cowmrp.data import example_herd_path # 200 synthetic cows shipped with the package
26
+ from cowmrp.model import build_model
27
+ from cowmrp.domains.cow.farm import load_herd, project_herd
28
+ from cowmrp.viz.farm import write_farm_outputs
29
+
30
+ model = build_model("cow") # month resolution (see "Time resolution")
31
+ herd = load_herd(example_herd_path(), model) # or your own CSV / DataFrame
32
+ result = project_herd(herd, model, mode="expected", steps=24)
33
+ write_farm_outputs(result, "farm_results") # CSV tables + dashboard.html + dashboard_plotly.html
34
+ ```
35
+
36
+ **Example notebooks.** The folder [`user_examples/`](user_examples/) holds five Jupyter notebooks that start with `pip install "cowmrp[plot,excel]"`, import only from the installed package and run on a CSV that you replace with your own: cows from a CSV with keep/cull, a farm projection with the interactive Plotly dashboard, individual rewards, a youngstock farm, and a domain of your own on the generic engine. They are not part of the installed package; get them with `git clone https://github.com/Bovi-analytics/cow-mrp.git` (or Download ZIP on GitHub) and see `user_examples/README.md` and the Examples page of the documentation site.
37
+
38
+ A complete script is `examples/whole_farm_example.py`; the same steps are walked through in the [tutorial](https://bovi-analytics.github.io/cow-mrp/tutorial.html) of the documentation site (online once the repository is public; the source is `guide/tutorial.html`).
39
+
40
+ ## What the package does
41
+
42
+ | Task | Entry point | Notes |
43
+ |---|---|---|
44
+ | Build and solve a model | `cowmrp.model.build_model("cow" \| "youngstock")`, `evaluate`, `evolve_distribution` | Any domain that follows the interface in `cowmrp.domain` |
45
+ | **One cow, or cow A against cow B** | `cowmrp.domains.cow.projection.compare_cows(scenarios, years=2)` | Rewards and distributions over time for cows given as `lactation`, `dim_days`, `dp_days`; figures in `cowmrp.viz.projection` |
46
+ | **Keep or cull** | `cowmrp.domains.cow.keepcull.keep_cull_table(herd, model, years=(1,3,5), offer=900)` | Break-even sale value of every cow = value of keeping her minus value of replacing her now; a KEEP/CULL call only when you give an `offer`. Salvage is not credited in the model's own comparison (a documented limitation). `cowmrp.domains.cow.keepcull_excel.write_keepcull_workbook` (`--excel`, needs `cowmrp[excel]`) writes an Excel workbook that shows the sale of the cow now as its own column; see below |
47
+ | **Whole-farm projection** | `cowmrp.domains.cow.farm.project_herd(herd, model, mode, steps)` | Open / pregnant / dry, lactation, DIM stage; cows never replaced versus replaced; per-cow values |
48
+ | **Load farm records** | `cowmrp.domains.cow.farm.load_herd(csv_or_dataframe, model)` | Raw records or already-mapped `state_id`; every problem reported with row and `cow_id` |
49
+ | Environmental outputs | `cowmrp.domains.cow.rewards.environment` | The physical quantities (enteric and manure methane, N2O, nitrogen, CO2) are always computed by `compute_environment()` and do not depend on any price; the monetary environmental rewards are off by default and enter the economic total only if you enable them |
50
+ | Synthetic herd | `cowmrp.domains.cow.farm.generate_herd(model, mode, n_cows, seed)` | `equilibrium` (the model's steady-state herd), `mix`, `exact` |
51
+
52
+ ### Farm data
53
+
54
+ One row per cow, described in **real days** (never health or DNB flags, which are not state variables):
55
+
56
+ | Column | Meaning |
57
+ |---|---|
58
+ | `cow_id` | optional, unique (1..n when absent) |
59
+ | `lactation` | 1 to 10 |
60
+ | `dim_days` | days in milk, 0 or more |
61
+ | `dp_days` | days pregnant, 0 for an open cow (default 0) |
62
+ | `state_id` | alternative: the model state of the cow, as written by `generate_herd` (if given together with the days they must agree) |
63
+ | `uim`, `up` | alternative to the days columns: the model's step indices |
64
+
65
+ A cow is mapped to a state exactly as the original runner `runners/cow/farm/generate.py` always did. `load_herd` adds checks only: missing columns, non-numeric
66
+ values, out-of-range lactation, negative days, duplicate `cow_id`, a combination the model has no state for (the message lists the nearest valid states), and a herd
67
+ file made under another time resolution. A DataFrame is accepted wherever a CSV path is.
68
+
69
+ ### Tutorial dataset
70
+
71
+ `cowmrp.data.example_herd_path()` is a 200-cow **synthetic** herd (cows drawn from the model's own steady-state herd, seed 42, month resolution) in the model's schema;
72
+ `example_raw_herd_path()` is the same cows as a farmer would export them (`cow_id, lactation, dim_days, dp_days`). No real farm records are included.
73
+
74
+ ### Time resolution
75
+
76
+ The model steps in `month` (30 d, default), `week` (7 d) or `day` (1 d). Set it **before Python starts**: `COW_TIME_UNIT=week python my_script.py`.
77
+ The resolution is not a display setting: it rebuilds the state space, the transition probabilities (rescaled to the step), the reward of every state (the rate integrated over the days
78
+ one step spans) and so the expected values. `dim` and `dp` are step indices of the chosen resolution, not calendar days; durations such as gestation stay in real days.
79
+ One process holds one resolution (the cow domain reads it once, when imported); `compare_cows` runs scenarios of another resolution in worker processes for you.
80
+ A herd file made at one resolution is refused at another; regenerate it. The day resolution is large: use it deliberately.
81
+
82
+ <!-- GEN:resolution_table -->
83
+ | Resolution | Step | States | Transitions | Example cow as `(dim, dp)` |
84
+ |---|---:|---:|---:|---:|
85
+ | month | 30 d | 2,970 | 9,040 | (4, 2) |
86
+ | week | 7 d | 42,290 | 131,197 | (20, 9) |
87
+ | day | 1 d | 1,952,060 | 6,109,989 | (149, 60) |
88
+
89
+ The example cow is in her second lactation, 150 days in milk and 60 days pregnant; `dim` and `dp` count model steps, so the same cow has different state coordinates at each resolution.
90
+ <!-- /GEN -->
91
+
92
+ <!-- GEN:state_counts -->
93
+ State counts (month resolution): 2,970 states, of which 1,210 are reachable from the replacement state (the default is the full table), 9,040 transitions.
94
+ <!-- /GEN -->
95
+
96
+ ### Expected versus stochastic and Monte Carlo
97
+
98
+ `project_herd(..., mode=...)`:
99
+
100
+ | Mode | What it computes | When to use |
101
+ |---|---|---|
102
+ | `expected` (default) | The exact distribution of the herd after each step, split into cows never replaced and cows replaced at least once. Deterministic, fast | Almost always: planning, comparing scenarios, dashboards |
103
+ | `stochastic` | One sampled path per cow (`seed`) | To see a single plausible herd history |
104
+ | `monte_carlo` | Many sampled herds (`sims`), reported as mean, standard deviation, 5th and 95th percentile | When the spread, not only the mean, matters (small herds) |
105
+
106
+ For a large herd the three agree on the mean; Monte Carlo is the slow one, so it is never run unless you select it.
107
+
108
+ ## Repository layout
109
+
110
+ | Folder | Purpose |
111
+ |---|---|
112
+ | `src/cowmrp/mrp/` | Domain-free MRP engine: `core.py` (math), `engine.py` (spec orchestration and validation), `simulator.py`, `utils.py` |
113
+ | `src/cowmrp/domain.py`, `model.py` | The domain interface (`load_domain`, `validate_domain`) and the generic build/solve API |
114
+ | `src/cowmrp/domains/` | One folder per domain: `cow/` (parameters, states, probabilities, transitions, rewards, lookup tables, evidence, `farm.py`, `keepcull.py`, `projection.py`) and `youngstock/` |
115
+ | `src/cowmrp/viz/`, `io/`, `data/` | Figures and dashboards, model-file export, the shipped example herd |
116
+ | `runners/` | Scripts that use the package: one module per domain (`cow/`, `youngstock/`) with `run.py`, `checks/`, `plots/`, `outputs/<kind>/`; `_shared/` common code |
117
+ | `examples/` | Four runnable scripts (`whole_farm_example.py`, ...) |
118
+ | `user_examples/` | Five example notebooks with their synthetic CSV files, a custom-domain folder and the installed-wheel test (`check_installed.py`); obtained from GitHub, not in the package |
119
+ | `tests/` | Fast default suite plus opt-in `slow` and `install` tests (see `tests/README.md`) |
120
+ | `guide/` | Documentation: the tutorial, a file guide and API reference built by `guide/build.py`, and the website in `guide/web/` |
121
+
122
+ Dependency direction is one-way: `cowmrp.mrp` <- `cowmrp.domain` <- `cowmrp.model` <- `cowmrp.domains` <- `runners`
123
+ (check: `python runners/_shared/checks/verify_mrp_boundary.py`). `runners/README.md` explains the runner modules.
124
+
125
+ **Add a domain:** write a package with `parameters`, `states`, `probabilities`, `transitions` (and optional `rewards`) following `cowmrp.domain`, then
126
+ `cowmrp.domain.load_domain("your_package")`. `python runners/_shared/new_domain.py <name>` creates the stubs and the runner module.
127
+
128
+ ## Running the scripts (research workflows)
129
+
130
+ All scripts run from any directory. They are kept and call the package.
131
+
132
+ ```
133
+ python runners/run_all.py # every module -> runners/<module>/outputs/
134
+ python runners/cow/run.py --review # review pages for a domain expert
135
+ python runners/cow/projection.py # edit SCENARIOS at the top first (cow A vs cow B)
136
+ python runners/cow/farm/generate.py # a synthetic herd -> runners/cow/outputs/farm/farm_data.csv
137
+ python runners/cow/farm/simulate.py --mode expected --steps 24 # herd projection and dashboards
138
+ python runners/cow/farm/keepcull.py --years 1,3,5 --offer 900 # keep/cull table
139
+ python runners/cow/farm/keepcull.py --excel # + keepcull_accounting.xlsx: KEEP, REPLACE, salvage, break-even per cow (needs cowmrp[excel])
140
+ python runners/cow/farm/keepcull.py --set REARING_COST=2800 # scenario run: override an economic setting for this run only (see below)
141
+ python runners/cow/checks/verify_farm.py # and the other verify_* scripts in runners/*/checks/
142
+ python runners/_shared/scale_benchmark.py --quick # cost and accuracy against herd size
143
+ ```
144
+
145
+ ### Keeping the documentation in step with the code
146
+
147
+ Numbers and tables that the documents repeat (state counts, reward components, overridable economic settings) are read from the package, not typed:
148
+
149
+ ```
150
+ python guide/build_all.py # rewrite the generated blocks, build both sites, then check that nothing is stale
151
+ python guide/sync.py check # exit 1 if a block, token, number or built site is out of date
152
+ python guide/sync.py impact <file> # which documents and outputs depend on a source file
153
+ ```
154
+
155
+ Generated blocks sit between `<!-- GEN:name -->` and `<!-- /GEN -->` in this file; do not edit inside them. `{{NAME}}` tokens in the tutorial and site pages are expanded at build time.
156
+
157
+ ### Keep/cull accounting workbook
158
+
159
+ `python runners/cow/farm/keepcull.py --excel` also writes `keepcull_accounting.xlsx`: for every cow and horizon, the KEEP value, the REPLACE value, the immediate salvage (an indicative estimate, or the net offer you type for that cow), the break-even offer, ΔQ and the decision, as Excel formulas. It is a reporting output; the model, the reward vector and `keep_cull_table` are unchanged. The estimate is indicative (state-based body weight; the model's dressing percentage, beef price and culling fee) and a typed offer is the net cash received. The `Checks` sheet shows that the break-even column reproduces `keep_cull_table`. Terms, every column and formula, the treatment of future salvage and replacement costs, and the limitations are on the documentation site page *Keep/cull workbook* (`guide/web/content/keepcull-workbook.html`). The column table below is generated from the package:
160
+
161
+ <!-- GEN:excel_columns -->
162
+ | Col | Header | Kind | Formula (row r) | Meaning |
163
+ |---|---|---|---|---|
164
+ | A | cow_id | from the herd file | | Cow identifier from the herd file (row number if the herd has none). |
165
+ | B | state_id | from the herd file | | Model state of the cow (index into the state table of the current time resolution). |
166
+ | C | lactation | from the herd file | | Lactation number (copied when the herd has it). |
167
+ | D | dim_days | from the herd file | | Days in milk (copied when the herd has it). |
168
+ | E | dp_days | from the herd file | | Days pregnant (copied when the herd has it). |
169
+ | F | body_weight_kg (model, state-based) | model value (pasted) | | Body weight of the state in kg, computed as cull_reward computes it for the salvage value. A model estimate, not the weight on the day of sale. |
170
+ | G | V_total(s) | model value (pasted) | | V_total(s): expected discounted total reward of the cow over the horizon (milk, pregnancy, cull, mortality, feed, reproduction), future cull salvage included. |
171
+ | H | PV future replacement costs (s) | model value (pasted) | | PV_rc(s): expected discounted cost of the future replacements of this cow and of her replacements over the horizon. |
172
+ | I | KEEP = V_total - PV_rc | Excel formula | `=Gr-Hr` | KEEP: expected future value of keeping the cow, every future replacement cost paid. |
173
+ | J | estimated salvage S_est | Excel formula | `=Fr*Inputs!$B$3*Inputs!$B$2-Inputs!$B$4` | Estimated salvage now: body weight x dressing percentage x beef price - culling fee (Inputs B3, B2, B4). |
174
+ | K | actual net offer (type here, optional) | input (yellow) | | Actual net offer for this cow, typed by the user (optional). Net cash received: the culling fee is not subtracted again. |
175
+ | L | S used | Excel formula | `=IF(Kr="",Jr,Kr)` | Salvage used: the typed offer if there is one, otherwise the estimate. |
176
+ | M | V_keep(heifer) | Excel formula | `=Inputs!$E$<horizon row>` | V_keep(h): value of a fresh replacement heifer (state (1, 0, 0)) over the same horizon (Inputs sheet). |
177
+ | N | rearing cost C | Excel formula | `=Inputs!$B$<horizon row>` | C: rearing cost of one replacement, charged once, now (Inputs sheet). |
178
+ | O | REPLACE = S + V_keep(h) - C | Excel formula | `=Lr+Mr-Nr` | REPLACE: salvage used + value of the replacement heifer - rearing cost. |
179
+ | P | Delta Q = KEEP - REPLACE | Excel formula | `=Ir-Or` | Delta Q = KEEP - REPLACE. Positive: keeping is better; negative: replacing is better. |
180
+ | Q | break-even offer | Excel formula | `=Ir-Mr+Nr` | Break-even offer: the salvage at which KEEP and REPLACE are equal. |
181
+ | R | decision | Excel formula | `=IF(Lr>Qr,"CULL","KEEP")` | Decision: CULL when the salvage used is above the break-even offer, otherwise KEEP. |
182
+ | S | S source | Excel formula | `=IF(Kr="","estimate","offer")` | Which salvage was used: the estimate or a typed offer. |
183
+ | T | value from keep_cull_table (check) | check | | value_<N>y from keep_cull_table for the same cow and horizon (pasted from the model). |
184
+ | U | difference to check | check | `=Qr-Tr` | Break-even offer minus the reference value; must be 0 (to rounding). |
185
+ <!-- /GEN -->
186
+
187
+ ### Economic scenarios
188
+
189
+ Prices and costs of the cow rewards (milk, feed, beef, calf, rearing, culling fee and the service costs) can be overridden for one run, without touching the model's defaults:
190
+
191
+ ```python
192
+ from cowmrp.model import build_model
193
+ from cowmrp.domains.cow.economics import economic_overrides, reprice_model
194
+ from cowmrp.domains.cow.keepcull import keep_cull_table
195
+
196
+ model = build_model("cow")
197
+ with economic_overrides(MILK_PRICE_PER_KG=0.52, REARING_COST=2800):
198
+ scenario = reprice_model(model) # rewards recomputed; states, probabilities and the transition matrix are the same objects
199
+ table = keep_cull_table(herd, scenario) # keep/cull inside the block, so REARING_COST applies
200
+ ```
201
+
202
+ Settings not named keep their defaults, and every value is restored when the block ends. The discount rate and the sale offer are already arguments of the keep/cull functions.
203
+ The override replaces module-level values, so it is **not thread-safe**: use it in sequential scripts and notebooks. The supported settings, with unit, currency and the source recorded in the repository, are in `cowmrp.domains.cow.economics.ECONOMIC_SETTINGS`. Biological and management values are not overridable.
204
+
205
+ ## Tests
206
+
207
+ ```
208
+ pytest # fast set, about 1 minute: expected-distribution checks, month and week
209
+ pytest -m slow # day resolution and weekly Monte Carlo parity, about 13 minutes
210
+ pytest -m install # builds the wheel and installs it in a clean virtual environment (needs network)
211
+ ```
212
+
213
+ ## Documentation
214
+
215
+ The site is built from the code by `python guide/build.py` and published to GitHub Pages by `.github/workflows/guide.yml` when `src/`, `guide/`,
216
+ `examples/`, `user_examples/`, `README.md` or `pyproject.toml` change on `main`.
217
+
218
+ ## License and citation
219
+
220
+ Authors: Sumit Sharma (first author, primary developer), Edward Hansen and Miel Hostens (supervisor), Department of Animal Science, Cornell University, Ithaca, New York, USA.
221
+ CowMRP is released under the MIT licence (SPDX `MIT`), see `LICENSE`. Copyright (c) 2026 Bovi-analytics Lab, Cornell University. How to cite: see `CITATION.cff` (a Zenodo DOI will be added after the first public release).
222
+
223
+ Third-party material keeps its own licence: the Computer Modern (CMU) web fonts bundled with the documentation theme (`guide/web/theme/fonts/`, not in the installed package) are under the SIL Open Font License 1.1, whose text (`OFL.txt`) is kept with them; the interactive dashboards embed plotly.js (MIT), which keeps its own notice in the generated files. Dependencies such as numpy, pandas, scipy, matplotlib, plotly and openpyxl are installed from PyPI under their own licences and are not redistributed here.
224
+
225
+ ## Notes
226
+
227
+ - The state reward vector does not contain `replacement_cost`; it is charged in the cow-versus-heifer comparison
228
+ (`replacement_comparison`, used by the keep/cull table), see the module docstring of `cowmrp.domains.cow.rewards`.
229
+ - Lookup tables can be overridden by CSV files (`src/cowmrp/domains/cow/data/README.md`).
230
+ - All generated files are written to `runners/<module>/outputs/`, which is not tracked.
@@ -0,0 +1,18 @@
1
+ """One cow, or cow A against cow B -- expected value over two years, and where each cow is likely to be.
2
+
3
+ python examples/cow_comparison_example.py
4
+
5
+ Two second-lactation cows 150 days in milk, one open and one already 60 days pregnant, are projected forward with the model's own
6
+ transition matrix and rewards. Change the scenarios (lactation, dim_days, dp_days, time_unit) to compare other cows.
7
+ """
8
+ from cowmrp.domains.cow.projection import compare_cows
9
+
10
+ scenarios = [
11
+ dict(label="open", time_unit="month", lactation=2, dim_days=150, dp_days=0),
12
+ dict(label="pregnant", time_unit="month", lactation=2, dim_days=150, dp_days=60),
13
+ ]
14
+ results = compare_cows(scenarios, years=2) # {scenario index: result}; n_trajectories=100 adds Monte Carlo bands
15
+
16
+ print("Expected value over the next 2 years (USD, discounted):")
17
+ for i, sc in enumerate(scenarios):
18
+ print(f" {sc['label']:9s} {results[i]['finite_horizon_value']:8.0f}")
@@ -0,0 +1,33 @@
1
+ """Keep or cull -- the break-even sale value of every cow in the example herd.
2
+
3
+ python examples/keep_cull_example.py
4
+
5
+ keep = expected future value of the cow, her future replacement costs included; replace = value of a heifer bought now, after one replacement
6
+ cost; value = keep - replace = the sale value above which culling and replacing her beats keeping her. No sale price is built into the model:
7
+ the offer below is an input you choose. The salvage value of a sale is not credited in the model's own comparison (documented limitation).
8
+ The last part repeats the table under a different rearing cost to show how a default is overridden for one block of code and then restored.
9
+ """
10
+ from cowmrp.data import example_herd_path
11
+ from cowmrp.domains.cow.economics import ECONOMIC_SETTINGS, economic_overrides, reprice_model
12
+ from cowmrp.domains.cow.farm import load_herd
13
+ from cowmrp.domains.cow.keepcull import keep_cull_summary, keep_cull_table
14
+ from cowmrp.model import build_model
15
+
16
+ model = build_model("cow")
17
+ herd = load_herd(example_herd_path(), model)
18
+ table = keep_cull_table(herd, model, years=(1, 3, 5), offer=900) # offer = USD per cow
19
+
20
+ print("Weakest five cows at the 3-year horizon (value_3y = break-even sale value, USD):")
21
+ print(table.nsmallest(5, "value_3y")[["cow_id", "lactation", "dim_days", "value_3y", "decision_3y", "stable"]].round(0).to_string(index=False))
22
+ print("\nSummary at an offer of 900 USD:")
23
+ summary = keep_cull_summary(table, (1, 3, 5))
24
+ print(summary[summary["lactation"] == "all"].round(0).to_string(index=False))
25
+
26
+ # Scenario: the defaults are untouched outside the block. Anything not named keeps its default. 2,800 USD is an illustrative value, not a recommendation.
27
+ default_cost = ECONOMIC_SETTINGS["REARING_COST"]["default"]
28
+ with economic_overrides(REARING_COST=2800):
29
+ scenario = reprice_model(model) # same states and transition matrix; rewards recomputed
30
+ table_s = keep_cull_table(herd, scenario, years=(1, 3, 5), offer=900) # the keep/cull layer reads REARING_COST inside the block
31
+ n_default, n_scenario = int((table["decision_3y"] == "CULL").sum()), int((table_s["decision_3y"] == "CULL").sum())
32
+ print(f"\nCows to cull at 900 USD, 3-year horizon: {n_default} with the default rearing cost ({default_cost:,.0f} USD), {n_scenario} with 2,800 USD")
33
+ print(f"Median break-even value (3-year): {table['value_3y'].median():,.0f} -> {table_s['value_3y'].median():,.0f} USD")