# Water Rights Toolkit: what the three views mean

These definitions travel with the data. They appear at the top of every page that shows eWRIMS figures, in the
provenance block of every fact sheet, and in the data catalog entry for the `water.ewrims_*` datasets. They are
written so that a reader who wants the most probably correct number can find it and can see what was set aside to
get there. Version 1.2, 2026-09-18.

## As filed

Every number exactly as the right holder reported it to the State Water Resources Control Board through eWRIMS,
in acre-feet, for the report year and month filed. Nothing is removed, converted, or scaled. This view is the
default and is always one click away from the other two. It includes filings that are physically impossible, and
it shows them as such.

## Screened

The "as filed" view with individual reports set aside when they fail one of five tests. Every test compares a
filing to the right holder's own record or to the filing itself. No test compares a filing to a model, to a
neighbor, or to an expectation of how much water should have been used.

1. Exceeds the right's own maximum by more than two times. The maximum is the largest annual amount the right's
   record allows: its face value, or its maximum diversion rate run every day of the year, or its maximum annual
   direct diversion, whichever is largest. Two times that figure has no physical reading. (Flag: `exceeds_cap`
   from 2x to 100x; `implausible_vs_cap` above 100x. Both are set aside.)
2. Gallons entered as acre-feet. The right has no recorded maximum, the filed diversion is more than one hundred
   times the filed use, and the filed diversion divided by 325,851 (gallons in an acre-foot) matches the filed use.
   (Flag: `unit_mismatch_suspected`.)
3. Implausible with no recorded maximum. The right has no recorded maximum and the filing exceeds 50,000 acre-feet
   for an individual or unrecorded holder, or 2,000,000 acre-feet for any holder. Fifty thousand acre-feet is
   roughly the supply for 15,000 irrigated acres; no individually held statement without a recorded diversion rate
   credibly moves that. (Flag: `implausible_no_cap`.)
4. Outlier against the right's own history. The right has no recorded maximum, the filing exceeds 1,000 acre-feet,
   and it exceeds ten times the median of that right's other non-zero filings. (Flag: `outlier_vs_own_history`.)
5. No test possible. The right has no recorded maximum and the filing passed tests 2 through 4. These filings are
   kept and marked `unscreened_no_cap` so the reader knows they were not checked against a cap.

Rules that hold in every screened figure:

- Screening sets aside a report, never a right. The right remains in every count, and its filing remains visible
  on the chart, hatched, with the filed value printed and the failed test named.
- Screening never corrects. No value is converted from gallons, scaled, or replaced. A reader who wants to read a
  flagged filing as gallons can do so on the page; the choice is labeled and travels in the page link.
- A report that passes screening is unrefuted by the record. It is not verified. Errors smaller than two times the
  right's maximum pass. Water reported under several rights as it moves downstream is counted each time.
- Reported use and reported diversion are screened separately. A year can have a credible diversion and an
  exempted use, or the reverse.

## Best available

One number per right per year, chosen in a fixed order, with the tier shown beside it:

1. Reported use, if it passed screening. eWRIMS "use" is the amount the holder reports as beneficially used. It is
   the nearest figure in the record to water consumed. It is not a measurement of evapotranspiration, and most
   holders report use equal to diversion.
2. Reported diversion, if it passed screening and no credible use was filed.
3. Face value, if the right is exercisable (a permit, license, certificate, registration, or claimed statement;
   not a state filing, and not cancelled, revoked, rejected, closed, inactive, or pending) and no credible report
   exists for that year.
4. Nothing, with the reason stated.

Face value is a ceiling written on paper, not a measurement. In "best available" it enters only when no credible
report exists, and every total that includes it shows the paper share separately.

## Share of water rights volume affected

In any yearly figure, when reports are set aside, the page states the share of the area's water rights volume
those reports belong to, measured by face value, not by the reported amounts:

> Reports set aside this year: N. Those rights hold X acre-feet of face value, Y% of the Z acre-feet of exercisable
> face value located in this watershed. K of the set-aside reports belong to rights with no face value (statements
> of diversion and use), whose volume the record does not state.

The denominator is the face value of all exercisable rights located in the area, whether or not they filed that
year, so the percentage does not move when reporting rates change. A companion figure gives the same share against
only the rights that filed that year.

## What the record cannot tell you

eWRIMS holds self-reported amounts with no metering requirement for most rights before 2016. It records no
consumptive use. It records a priority date on fewer than one right in twenty; the toolkit's seniority figures use
the application acceptance date for most post-1914 rights and say so. Statewide and watershed totals count water
more than once as it is re-diverted. Compare rights to rights and watersheds to watersheds; do not compare a
total here to runoff or to a water budget.

## Purpose classes (added 2026-09-18, definitions version 1.1)

Each right is placed in one purpose class from the beneficial use eWRIMS lists first for it: agriculture (irrigation,
stockwatering, frost protection, dust control), urban (domestic, municipal), hydropower (power, incidental power),
environmental (fish and wildlife, water quality), industrial (industrial, mining, milling, heat control, snow making),
other (recreation, aesthetic, fire protection, aquaculture, other), or not recorded. A right that lists two or more
uses is placed in mixed, not under its first-listed use, because eWRIMS's public POD file names only the first use
and the record does not say which use carries the water. Every CVP and SWP permit is mixed. Hydropower and most
environmental use is pass-through: the water is reported as used and returns to the river. A page that shows
purpose classes says so beside the hydropower figure and never adds hydropower to a consumptive total.

## Who can see what (added 2026-09-18, definitions version 1.2)

Public pages and the public data API show watersheds, counties, purpose classes, seniority ladders, and statewide
series. Figures for an individual water right, including its holder, its filings, and its flags, are available to
the site administrator and to authorized users with an access key. Aggregates are built from the same right-level
rows, so a public total and an authorized drill-down always agree.