Technical Reference: Files & Parameters

herdr operates on a data-driven approach. To ensure the model works correctly, files are divided into two categories: User Inputs (files you fill in user_data/) and Reference Libraries (internal files you consult).

---

I. User Input Files (user_data/)

These are the templates you must complete to run your specific analysis. Follow the Workflow Guide for step-by-step instructions.

🐄 Population & Metrics

• livestock_census.csv: Defines the animal_tag, location (region), and the number of heads (population).
• weights.csv: Defines the physical scale of the animals, including adult_weight, initial_weight, final_weight and productive_period.
• livestock_definitions.csv: The bridge file. It links each animal_tag to a diet_tag and an IPCC Description.

🍚 Nutrition & Diets

• diet_profiles.csv: Sets the high-level balance between Forage, Concentrate, Milk, and Milk Replacer.
• diet_ingredients.csv: The micro-breakdown of exactly which ingredients (from the library) make up the macro categories.

💩 Manure Management

• manure_management.csv: Defines how waste is handled, specifying the system, the climate, and the allocation (0 to 1).

---

II. Reference Libraries (Consult Only)

These files are the “brain” of the package. You should not edit them unless you are an advanced user, but you must consult them to copy the exact names for your inputs.

🧪 feed_characteristics.csv — Nutritional Values

Consult this to find the correct names for your ingredients to use in diet_ingredients.csv.

• Key Columns: ingredient, ingredient_type, cp (Crude Protein %), de (Digestible Energy %), ndf (Neutral detergent fiber) % and ge (Gross energy MJ/kg).
• Why it matters: de (Digestible Energy) is the main driver for the Methane Conversion Factor ($Y_m$).

🧬 ipcc_coefficients.csv — Metabolic Constants

Consult this to find the description you need to copy into your livestock_definitions.csv.

• Key Columns: description, coefficient ($C_a$, $C_{fi}$, etc.), and value.
• Why it matters: It contains the Tier 2 constants that define energy needs for maintenance, pregnancy, and lactation.

💩 ipcc_mm.csv — Manure Reference

The master list for Phase 4. It contains every valid combination of manure systems.

• Key Columns: system_base, system_variant, climate_zone, and management_months.
• Why it matters: Your entry in manure_management.csv must match a row here exactly, or the model will return zero emissions.

🗺️ mapping.csv — Database Connector

The “bridge” that links your diet names to the agricultural yield databases.

• Key Columns: ingredient, yield_name,allocation (0-1 factor).

• Why it matters: Tells the model which crop productivity to use and how much of that land footprint is attributed to the animal (e.g., grain vs. straw allocation).

🌾 forage_yields.csv — Grass & Silage Data (BC3)

Provisional database for forages supplemented by BC3 researchers.

• Key Columns: Area (Country), Item (Crop name), Value (kg DM/ha).
• Why it matters: Provides essential yield data for grazing and forage-based systems where official FAOSTAT records are often incomplete or missing.

📈 fao_crop_yields.csv — Official Statutory Yields

Direct yield data for grains and pulses from the FAOSTAT (2024) database.

• Key Columns: Area, Item, Year, Value (kg DM/ha).
• Why it matters: Sets the international standard for calculating the land footprint ($m^2$) of concentrate feeds and commercial crops.

---

III. Quick Reference Table

Use this table to know where to look when filling out your data:

If you want to…	Consult this library:	To fill this input file:
Identify an animal type	ipcc_coefficients.csv	livestock_definitions.csv
Pick a feed ingredient	feed_characteristics.csv	diet_ingredients.csv
Choose a manure system	ipcc_mm.csv	manure_management.csv
Add a custom crop		feed_characteristics, forage_yields.csv, mapping.csv & fao_crop_yields.csv

---

💡 Tip

The model is case-sensitive and does not like spaces. Always use lowercase and underscores (e.g., maize_silage instead of Maize Silage).