# Value of information: template guide (prototype)

The downloadable template is an Excel workbook. The Data sheet is filled with a small working example (valid values, intensity probabilities summing to 1) so the file runs as soon as it is uploaded. Replace those example values with your own. Column descriptions and the rules for intensity probabilities and harm-level fields are on the Instructions sheet. A CSV file with the same columns is also accepted.

One file describes both scenarios. Each row has a `record_type`:

| record_type | One row per | Purpose |
|---|---|---|
| `scenario`  | scenario (exactly 2 in this prototype) | mortality, productivity, product unit, lifespan |
| `life_fate` | life fate in each scenario | share of the scenario's animals in that life fate |
| `segment`   | segment of each Pain-Track or Pleasure-Track | harm-level fields + segment duration and intensity probabilities |

The first scenario in the file is the reference. Differences are reported as second scenario minus first.

Fill in the Data sheet. Columns can be in any order. Columns that a row does not use can be left blank. A CSV file with the same columns is also accepted. Comma-separated files are expected; semicolon-separated files with decimal commas (as saved by Excel in some European locales) are also accepted.

## Ranges

Every uncertain value is entered as a range with two columns, `<name>_min` and `<name>_max`.

- Use the same value in both if the value is fixed.
- By default the value is drawn uniformly between min and max.
- Optional: add a `<name>_mode` column (e.g. `prevalence_mode`) with a most-likely value. That input is then drawn from a PERT distribution on [min, max]. Leave the cell blank to keep the uniform distribution for a particular row.
- Proportions (mortality, share, prevalence) are between 0 and 1. A value with a % sign (e.g. `35%`) is also accepted.

## Intensity probabilities

Each intensity has one column: `annoying`, `hurtful`, `disabling`, `excruciating`, `satisfaction`, `joy`, `euphoria`, `bliss`. Enter one proportion from 0 to 1. Blank means 0. The probabilities in a segment must sum to 1. If they differ from 1 by 0.01 or less, they are scaled to 1 and the page shows a warning. A difference greater than 0.01 is rejected. These values stay the same on every simulation draw. Do not use `_min`, `_max`, or `_mode` for them.

## Columns

| Column | Used in | Meaning |
|---|---|---|
| `record_type` | all rows | `scenario`, `life_fate` or `segment` |
| `scenario` | all rows | Short scenario name, e.g. `Baseline`, `Intervention`. Must match across rows. |
| `life_fate` | life_fate, segment | Life fate name, e.g. `Market animals`, `Breeders`. Segment rows must refer to a life fate defined by a `life_fate` row of the same scenario. |
| `harm` | segment | Name of the negative or positive affective experience. All segment rows with the same scenario + life fate + harm form one Pain-Track (or Pleasure-Track). |
| `valence` | segment | `negative` (Pain-Track) or `positive` (Pleasure-Track). |
| `segment` | segment | Segment number within the track: 1, 2, 3 … |
| `mortality_min`, `mortality_max` | scenario | Proportion (0–1) of placed animals that do not produce product. Must be below 1. Used directly when every life fate produces product. When a life fate has `produces_product` = no, mortality is the share of those fates and this range is only a check. |
| `productivity_min`, `productivity_max` | scenario | Product per surviving animal: units of product per animal that produces product, not per animal placed. Product per placed animal is (1 − mortality) × productivity. |
| `product_unit` | scenario | Label for the unit of product, e.g. `kg`, `egg`. Use the same unit in both scenarios. |
| `lifespan_days_min`, `lifespan_days_max` | scenario | Lifespan in days, entered as a range. Use the same value in both columns if it is fixed. Only used by harms with `scales_with_lifespan` = yes (otherwise optional and informative only). |
| `share_min`, `share_max` | life_fate | Proportion (0–1) of the scenario's animals in this life fate. Leave blank if the scenario has a single life fate (share = 1). With several life fates the ranges must be able to sum to 1. All but the last life fate are drawn from their ranges; the last is the remainder, kept only when it lies inside its range, so the shares sum to 1 and stay inside the entered ranges. |
| `produces_product` | life_fate | `yes` or `no` (blank = yes). No means this life fate produces no product. Mortality is then the share of all such fates. |
| `prevalence_min`, `prevalence_max` | segment (harm level) | Proportion (0–1) of animals in the life fate that experience the harm. |
| `occurrences_min`, `occurrences_max` | segment (harm level) | Number of times an affected animal experiences it. If `scales_with_lifespan` = yes, this is the number of occurrences per day of life. |
| `scales_with_lifespan` | segment (harm level) | `yes` or `no` (blank = no). If yes, occurrences = lifespan_days × the occurrences value. Use this for chronic harms that last all of life, so that a longer lifespan automatically means more days of the harm. |
| `shared` | segment | `yes` or `no` (blank = automatic). Blank, and the harm is identical in both scenarios (same life fate and harm name, prevalence, occurrences, durations, and intensity probabilities): one draw is used in both, and the page says so. `yes` requires the rows to match. `no` draws the two scenarios independently. A shared input moves both scenarios together, so it ranks near zero. |
| `duration_min`, `duration_max` | segment | Duration of one occurrence, entered as a range. Use the same value in both columns if it is fixed. |
| `duration_unit` | segment | `seconds`, `minutes`, `hours` or `days`. Everything is converted to hours; results are reported in hours. |
| `annoying`, `hurtful`, `disabling`, `excruciating` | segment (negative) | Fixed probability (0–1) of each pain intensity during the segment. Blank = 0. The four values must sum to 1. |
| `satisfaction`, `joy`, `euphoria`, `bliss` | segment (positive) | Fixed probability (0–1) of each pleasure intensity during the segment. Blank = 0. The four values must sum to 1. |
| `<any range>_mode` | optional | Most-likely value; switches that range to a PERT distribution. Not used for intensity probabilities. |
| `notes` | optional | Free text, ignored by the calculation. |

**Harm-level fields** (`valence`, `prevalence_*`, `occurrences_*`, `scales_with_lifespan`) belong to the harm, not the segment. Prevalence and occurrences are read from the first segment row of the harm. On the following segment rows of that harm you can repeat them or leave them blank, but any value you repeat must be identical. Otherwise the upload reports an error. The `shared` flag is also one value for the whole harm.

## Checks done on upload

The page lists every problem with its row number on the Data sheet, including the header. It checks for:

- missing columns
- unknown `record_type`, scenario or life fate
- an empty or non-numeric value, min greater than max, or a mode outside [min, max]
- proportions outside 0–1, and mortality of 1 or more
- productivity of 0 or less
- intensity probabilities that are not one fixed value per intensity, or that sum further than 0.01 from 1
- life-fate shares that cannot sum to 1
- inconsistent harm-level fields across the segment rows of a harm
- duplicate segment numbers
- pain intensities filled for a positive experience (or the reverse)
- `scales_with_lifespan` = yes without a scenario lifespan
- a number of scenarios other than two

## Minimal example

These rows use the same columns as the Data sheet.

```
record_type,scenario,life_fate,harm,valence,segment,mortality_min,mortality_max,productivity_min,productivity_max,product_unit,...,prevalence_min,prevalence_max,occurrences_min,occurrences_max,scales_with_lifespan,duration_min,duration_max,duration_unit,annoying,hurtful,disabling,excruciating
scenario,Baseline,,,,,0.04,0.06,2.3,2.6,kg,...
scenario,Intervention,,,,,0.04,0.06,2.3,2.6,kg,...
life_fate,Baseline,Market animals,...
life_fate,Intervention,Market animals,...
segment,Baseline,Market animals,Example harm A,negative,1,...,0.3,0.5,1,1,no,2,4,hours,0.050,0.300,0.500,0.150
segment,Baseline,Market animals,Example harm A,negative,2,...,,,,,,2,5,days,0.571,0.381,0.048,0.000
...
```

See the `examples/` folder for complete files. All example files contain made-up numbers (EXAMPLE DATA) and are not Welfare Footprint Institute estimates.