Generating Variable-Rate Nitrogen Prescription Maps

Problem statement

Nitrogen is the input where a variable-rate prescription earns or loses its keep. Apply too little on a high-yield zone and the crop leaves yield in the field; apply too much anywhere and the surplus leaches, runs off, and turns up as a reportable over-application against the product label. A nitrogen rate is not a single agronomic number either — it is the reconciliation of three methods that rarely agree: a yield-goal requirement, a soil-test nitrate credit that subtracts what is already plant-available, and the MRTN (Maximum Return To Nitrogen) economic optimum that caps spending where the marginal kilogram stops paying. This guide builds the per-zone nitrogen rate from those three inputs and hands it to the clamp that the variable-rate prescription pipeline applies before anything is written to a file.

The specific failure this module prevents is a zone rate that is agronomically reasonable but regulatorily illegal. The yield-goal method, run on a zone with an ambitious yield target and a low nitrate credit, can easily propose a rate above the label maximum. If that value is serialized, every hectare of the zone carries the excess. So the rate is computed as the lower of the agronomic requirement and the MRTN cap, the soil-test credit is subtracted, and the result is clamped to the regulated ceiling as the final, non-negotiable step. The regulated maximum itself comes from the EPA/USDA rule mapping threshold set, never from a literal in this code.

Parameter reference table

Every value below changes the nitrogen rate a zone receives. Recommended values assume a corn nitrogen program in a US Midwest context and per-zone soil sampling.

The n_factor, the ppm-to-lb/ac conversion, and the MRTN cap are stamped into a version-controlled agronomic profile rather than passed ad hoc, so a single profile change re-derives every zone the same way and the derivation is auditable a season later.

Runnable implementation

The module below computes a nitrogen rate for each management zone and returns it in kg/ha, clamped to the regulated maximum. It targets Python 3.10+, is fully typed, uses Decimal throughout, and depends only on the standard library plus numpy and shapely (the geometry travels with each zone so the rate stays attached to its polygon).

from __future__ import annotations

import logging
from dataclasses import dataclass
from decimal import Decimal, ROUND_HALF_UP

import numpy as np
from shapely.geometry import base

logger = logging.getLogger("vra.nitrogen")

LB_PER_AC_TO_KG_PER_HA = Decimal("1.120851")  # exact unit bridge for the export
QUANTIZE = Decimal("0.1")
# Regulated ceiling (kg/ha) resolved from the EPA/USDA rule-mapping registry.
REGULATED_MAX_KG_HA: dict[str, Decimal] = {"nitrogen": Decimal("246.0")}
# ppm nitrate-N to lb/ac depends on sample depth; 8 in-lb per ppm-foot is standard.
PPM_TO_LB_PER_FOOT = Decimal("8.0")


@dataclass(frozen=True)
class NitrogenProfile:
    n_factor: Decimal          # lb N per bu of yield goal
    mrtn_cap_lb: Decimal       # economic-optimum ceiling, lb/ac
    sampling_depth_in: Decimal  # nitrate sample depth, inches


@dataclass(frozen=True)
class ZoneInput:
    zone_id: int
    yield_goal_bu: Decimal
    soil_nitrate_ppm: Decimal | None  # None => no test => zero credit (conservative)
    legume_credit_lb: Decimal
    geometry: base.BaseGeometry


@dataclass(frozen=True)
class NitrogenRate:
    zone_id: int
    rate_kg_ha: Decimal
    clamped: bool
    credited_lb: Decimal
    geometry: base.BaseGeometry


def _nitrate_credit_lb(nitrate_ppm: Decimal | None, depth_in: Decimal) -> Decimal:
    """Convert a soil-test nitrate reading to a lb/ac credit for the sampled depth."""
    if nitrate_ppm is None:
        return Decimal("0")  # no test: credit nothing rather than assume a value
    depth_ft = depth_in / Decimal("12")
    return (nitrate_ppm * PPM_TO_LB_PER_FOOT * depth_ft).quantize(QUANTIZE)


def nitrogen_rate_for_zone(zone: ZoneInput, profile: NitrogenProfile) -> NitrogenRate:
    """Yield goal minus credits, capped at MRTN, then clamped to the regulated max."""
    # 1. Yield-goal requirement in lb/ac.
    requirement_lb = (zone.yield_goal_bu * profile.n_factor).quantize(QUANTIZE)
    # 2. Subtract soil-test and previous-crop credits (never let the rate go < 0).
    credit_lb = _nitrate_credit_lb(zone.soil_nitrate_ppm, profile.sampling_depth_in)
    credit_lb += zone.legume_credit_lb
    net_lb = max(Decimal("0"), requirement_lb - credit_lb)
    # 3. Cap at the MRTN economic optimum BEFORE unit conversion.
    agronomic_lb = min(net_lb, profile.mrtn_cap_lb)
    # 4. Convert lb/ac -> kg/ha for the export, quantized to controller resolution.
    rate_kg_ha = (agronomic_lb * LB_PER_AC_TO_KG_PER_HA).quantize(
        QUANTIZE, rounding=ROUND_HALF_UP
    )
    # 5. CLAMP to the regulated ceiling: the final, non-negotiable gate.
    ceiling = REGULATED_MAX_KG_HA["nitrogen"]
    clamped = rate_kg_ha > ceiling
    if clamped:
        logger.warning(
            '{"event":"n_rate_clamped","zone_id":%d,"requested":"%s","ceiling":"%s"}',
            zone.zone_id, rate_kg_ha, ceiling,
        )
        rate_kg_ha = ceiling
    logger.info(
        '{"event":"n_rate_built","zone_id":%d,"rate_kg_ha":"%s","credit_lb":"%s"}',
        zone.zone_id, rate_kg_ha, credit_lb,
    )
    return NitrogenRate(zone.zone_id, rate_kg_ha, clamped, credit_lb, zone.geometry)


def build_nitrogen_plan(
    zones: list[ZoneInput], profile: NitrogenProfile
) -> list[NitrogenRate]:
    """Compute clamped nitrogen rates for every zone and report the spread."""
    plan = [nitrogen_rate_for_zone(z, profile) for z in zones]
    rates = np.array([float(r.rate_kg_ha) for r in plan])
    logger.info(
        '{"event":"n_plan_built","zones":%d,"clamped":%d,"min":%.1f,"max":%.1f}',
        len(plan), sum(r.clamped for r in plan),
        float(rates.min()) if rates.size else 0.0,
        float(rates.max()) if rates.size else 0.0,
    )
    return plan

The order of operations is the whole point. Credits are subtracted before the MRTN cap so the economic optimum applies to the net requirement, and the regulatory clamp runs last, after the unit conversion, because rounding into the export resolution is exactly the step that can push a value a tenth of a unit past the ceiling. Computing the clamp before conversion would leave that gap open.

Log patterns and observable signals

Every zone emits structured JSON so a rate can be traced back to the yield goal and credits that produced it.

Normal build with a soil-test credit applied:

{"event": "n_rate_built", "zone_id": 3, "rate_kg_ha": "198.7", "credit_lb": "48.0"}

A high-yield zone whose net requirement exceeds the regulated ceiling and is clamped:

{"event": "n_rate_clamped", "zone_id": 4, "requested": "258.3", "ceiling": "246.0"}

Plan summary across all zones (watch the clamped count and the min/max spread):

{"event": "n_plan_built", "zones": 4, "clamped": 1, "min": 121.4, "max": 246.0}

A rising clamped count across fields is the signal to investigate: it usually means the n_factor or a yield goal in the agronomic profile is set too high, not that the crop genuinely needs the extra nitrogen. Alert when the clamped fraction exceeds a small threshold, because a clamp is a rate the agronomist asked for and could not have.

Safe override protocol

Occasionally a zone legitimately needs a rate the standard derivation would not produce — a replant situation, a documented tissue-test deficiency, or a research strip. The override supplies a different agronomic requirement; it never bypasses the regulatory clamp.

Guard conditions, all mandatory:

1. Explicit rate, with a reason. The agronomist supplies a concrete lb/ac figure and a coded justification; the module never infers an override from a threshold being crossed.
2. Still clamped. The override value flows through the same min(..., mrtn_cap) and regulatory clamp as any other rate — an override can lower a rate freely but can never raise it above the ceiling.
3. Dry-run diff. The override runs with persistence disabled and prints the per-zone delta against the standard plan for review before it is allowed to write.
4. Immutable audit trail. The original derived rate, the override rate, the approver, and the justification code are written to an append-only ledger, consistent with USDA NRCS Code 590 nutrient-management recordkeeping.

def override_zone_rate(
    zone: ZoneInput,
    profile: NitrogenProfile,
    override_lb: Decimal,
    approver: str,
    reason_code: str,
) -> NitrogenRate:
    """Substitute an explicit agronomic requirement; the regulatory clamp still runs."""
    capped_lb = min(override_lb, profile.mrtn_cap_lb)  # override cannot beat MRTN
    rate_kg_ha = (capped_lb * LB_PER_AC_TO_KG_PER_HA).quantize(
        QUANTIZE, rounding=ROUND_HALF_UP
    )
    ceiling = REGULATED_MAX_KG_HA["nitrogen"]
    clamped = rate_kg_ha > ceiling
    if clamped:
        rate_kg_ha = ceiling  # the ceiling wins over any override
    logger.warning(
        '{"event":"n_rate_override","zone_id":%d,"override_lb":"%s","approver":"%s",'
        '"reason":"%s","clamped":%s}',
        zone.zone_id, override_lb, approver, reason_code, str(clamped).lower(),
    )
    return NitrogenRate(zone.zone_id, rate_kg_ha, clamped, Decimal("0"), zone.geometry)

Troubleshooting

• Every zone comes back clamped at the ceiling. Root cause: the n_factor or the zone yield goals are set too high, so the net requirement exceeds the label maximum everywhere. Remediation: recalibrate the agronomic profile against realistic stabilized yields; a uniformly clamped plan is a flat-rate plan wearing a variable-rate costume.
• Nitrogen credit looks doubled or halved. Root cause: a mismatch between sampling_depth_in and the depth the lab reported the nitrate for, so the ppm-to-lb/ac conversion is mis-scaled. Remediation: pin the depth to the lab method and verify the PPM_TO_LB_PER_FOOT factor for the sampled profile.
• A zone with no soil test gets an unexpectedly high rate. Root cause: soil_nitrate_ppm is None, so no credit is subtracted — the conservative default. Remediation: this is intended, but flag missing-test zones for sampling rather than assuming a credit, which would under-apply.
• Rate is a hair above the ceiling after conversion. Root cause: the clamp was applied in lb/ac before the kg/ha conversion, letting rounding reopen the gap. Remediation: keep the clamp as the last step, after LB_PER_AC_TO_KG_PER_HA and the quantization, exactly as in the reference module.
• Negative net requirement on a high-credit zone. Root cause: soil-test plus legume credit exceeds the yield-goal requirement. Remediation: the max(Decimal("0"), ...) floor already handles this by emitting a zero rate; do not let it go negative and subtract from neighboring zones.

Frequently asked questions

Why cap at the MRTN optimum and also clamp to the regulated maximum? They guard different failures. MRTN is an economic ceiling on net requirement; the regulatory clamp is a legal ceiling from the label that no rate may exceed. A zone can sit under MRTN and still need clamping, so both run, with the regulatory clamp last.

What rate does a zone get when its soil-test nitrate is missing? Zero credit — the conservative path. The full yield-goal requirement stands and the zone is flagged for sampling, rather than assuming a credit that could under-apply on a genuinely deficient zone.

Why clamp after the unit conversion? Because the conversion and the export rounding are the steps that can push a value past the ceiling. Keeping the clamp last, after conversion and quantization, guarantees the exported number never exceeds the regulated maximum.

Related

• Variable-Rate Prescription Maps — the zone → rate → clamp → reconcile → export pipeline this nitrogen rate feeds.
• Exporting Prescription Maps to ISOXML for Task Controllers — serializing the clamped nitrogen rates to ISO 11783-10 TASKDATA.
• EPA/USDA Rule Mapping — the source of the regulated nitrogen ceiling the final clamp enforces.

Up: Variable-Rate Prescription Maps · Season Planning & Crop Rotation Optimization