{
  "category": "Database functions",
  "display_name": "DVARP",
  "entry_kind": "built_in_function",
  "eval_api": {
    "method": "POST",
    "url": "https://handbook.dnacalc.com/api/eval"
  },
  "function_id": "FUNC.DVARP",
  "implementation_state": {
    "answer_bank": null,
    "detail": "Recorded: 3 workbook cells.",
    "dnacalc_commit": "9e1884369a678158dd82d3d74188daf986995e87",
    "in_catalogue": true,
    "state": "matches",
    "state_label": "Matches every recorded Excel answer",
    "summary": "Matches all 3 recorded answers",
    "workbook_corpus": {
      "cells": 3,
      "matched": 3
    }
  },
  "implementations": [
    {
      "commit": "9e1884369a678158dd82d3d74188daf986995e87",
      "flavour": "excel-compatibility-candidate",
      "language": "Rust",
      "name": "CalcFunc",
      "own_code": [
        "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/catalogue/database.rs#L275-L275"
      ],
      "repository": "https://github.com/DnaCalc/DnaCalc",
      "shared_code": [
        "catalogue/aggregate::reader",
        "catalogue/aggregate::read_reference",
        "catalogue/comparison::numbers",
        "catalogue/comparison::in_band",
        "catalogue/comparison::Rounded::up",
        "catalogue/comparison::Roundings::of",
        "catalogue/comparison::Roundings::disjoint",
        "catalogue/comparison::texts",
        "catalogue/comparison/collation::compare",
        "catalogue/comparison/collation::weighed",
        "catalogue/comparison/collation::measured_iteration_extension",
        "catalogue/comparison/sort_key::table",
        "catalogue/comparison/sort_key::decode64",
        "catalogue/comparison/sort_key::Reader::byte",
        "catalogue/comparison/sort_key::Reader::varint",
        "catalogue/comparison/sort_key::Reader::done",
        "catalogue/comparison/sort_key::in_ranges",
        "catalogue/comparison/sort_key::build",
        "catalogue/comparison/sort_key::han_base",
        "catalogue/comparison/sort_key::derive",
        "catalogue/comparison/sort_key::shared_jamo_tails",
        "catalogue/comparison/sort_key::ordinary_jamo_prefix",
        "catalogue/comparison/sort_key::independent_jamo_suffix",
        "catalogue/comparison/sort_key::jamo_leading_primary",
        "catalogue/comparison/sort_key::leading_order",
        "catalogue/comparison/sort_key::Before::separate_special",
        "catalogue/comparison/sort_key::Gathered::kana",
        "catalogue/comparison/sort_key::Gathered::unit",
        "catalogue/comparison/sort_key::parts",
        "catalogue/comparison/sort_key::diacritic_order",
        "catalogue/comparison/sort_key::diacritics",
        "catalogue/conditional::range",
        "catalogue/conditional::row",
        "catalogue/conditional::offset",
        "catalogue/conditional::read_range",
        "catalogue/conditional::verdicts",
        "catalogue/conditional::used",
        "catalogue/conditional::Match::of",
        "catalogue/conditional::Match::negated",
        "catalogue/conditional::Op::holds",
        "catalogue/conditional::Op::is_equality",
        "catalogue/conditional::spells",
        "catalogue/conditional::criterion",
        "catalogue/conditional::database_criterion",
        "catalogue/conditional::rank",
        "catalogue/conditional::criterion_text",
        "catalogue/conditional::decided",
        "catalogue/conditional::Criterion::verdict",
        "catalogue/conditional::equality",
        "catalogue/conditional::is_surrogate",
        "catalogue/conditional::wildcard",
        "catalogue/database::label",
        "catalogue/database::same_label",
        "catalogue/database::field",
        "catalogue/database::matching",
        "catalogue/database::criterion_verdict",
        "catalogue/database::database",
        "catalogue/database::published",
        "decimal::low32",
        "decimal::Natural::from_u64",
        "decimal::Natural::pow10",
        "decimal::Natural::normalize",
        "decimal::Natural::is_zero",
        "decimal::Natural::mul_add_small",
        "decimal::Natural::times_pow10",
        "decimal::Natural::times_pow5",
        "decimal::Natural::times_pow2",
        "decimal::ExactDecimal::binary",
        "ported/excel_numeric::excel_sqrt_staged",
        "ported/text_kernels::text",
        "ported/text_kernels::text_from_str",
        "ported/text_kernels::fold_unit",
        "ported/text_kernels::push_singleton_or_original",
        "ported/text_kernels::push_lower",
        "ported/text_kernels::lower",
        "ported/variance_common::variance_from_values",
        "ported/variance_common::stdev_from_values"
      ],
      "source": "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/catalogue/database.rs#L275-L275",
      "state": "matches",
      "suite": null,
      "summary": "Matches all 3 recorded answers"
    }
  ],
  "json_url": "https://handbook.dnacalc.com/api/functions/FUNC.DVARP.json",
  "name": "DVARP",
  "notes": [],
  "schema": "efh.function-reference/v1",
  "section_order": [
    "what-it-does",
    "try-it",
    "quirks",
    "how-to-implement",
    "version-differences",
    "alternatives"
  ],
  "sections": {
    "alternatives": "\n### Relationships\n\n\n- **[DVAR](FUNC.DVAR.md)** is the sample form. `DVARP × n = DVAR × (n − 1)` whenever both are\n  defined.\n- **[DSTDEVP](FUNC.DSTDEVP.md)** is `SQRT(DVARP)`.\n- **Nearest modern equivalent**: `VAR.P` over a filtered array. Excel's compatibility rename\n  pass produced the `VARP` / `VAR.P` pair; the database family was left alone, so `DVARP` is not\n  a deprecated name and has no `.P`-suffixed replacement.\n- **Confused with**: `DVAR` (the divisor and the one-value boundary) and `VARPA`, which counts\n  logicals and text as values.\n\n\n",
    "how-to-implement": "\n### Notes for implementers\n\n\n1. **Guard on n = 0 only.** The sample and population members differ in exactly this predicate;\n   sharing the code path and switching only the divisor, without also switching the minimum\n   count, is the natural bug here.\n2. **Use the two-pass form** — see [DVAR](FUNC.DVAR.md#why-the-formula-not-just-the-definition).\n3. **The n = 1 answer should be exactly `+0`**, not a denormal residual. The two-pass form gives\n   that for free; a sum-of-squares form may not.\n4. **Skip, do not coerce.** Admit only cells whose value kind is Number.\n5. **Numeric criteria comparison is not exact double comparison** — see the note in\n   [the shared mechanism](FUNC.DAVERAGE.md#numeric-comparison-is-not-exact-double-comparison).\n   A tolerant match changes n, and here n is the divisor.\n\n\n",
    "quirks": "\n### Result and edge cases\n\n\nReturns a Number, always non-negative under the two-pass form.\n\n- **No numeric value selected**: `#DIV/0!`. Unlike the count and sum members, the statistical\n  members do error on an empty selection.\n- **Exactly one numeric value selected**: `0`, not an error. This is the sharpest observable\n  difference from [DVAR](FUNC.DVAR.md), which returns `#DIV/0!` on the same input.\n- **All selected values equal**: `0`, exactly, under the two-pass form.\n- **Text that looks numeric in the field column** is skipped, per the range-scan side of the\n  asymmetry in\n  [coercion and lifting](../model/02-coercion-and-lifting.md#direct-arguments-versus-range-scans).\n- **Logicals in the field column** are skipped.\n- **Arrays**: inline array literals resolve to grids and are accepted; `DVARP` is not a lift\n  kernel.\n\n\n\n### Errors\n\n\n| Error | Condition |\n|---|---|\n| `#DIV/0!` | No numeric value was collected from the field column of the matching records |\n| `#VALUE!` | *database* or *criteria* is not a grid or is empty; a database header cell is blank; a criteria header names no database field; *field* matches no header, or is a non-integer or out-of-range column index |\n| propagated | An error value in a header cell, a criteria cell, or a scanned field cell surfaces as that error |\n\n",
    "sources": "- Microsoft, \"DVARP function\" —\n  <https://support.microsoft.com/en-us/office/dvarp-function-eb0ba387-9cb7-45c8-81e9-0394912502fc>\n- Handbook `CHARTER.md` sections 1, 3 and 7; `content/model/06-claim-language.md`.\n- Handbook call-model chapters 02 and 03 (range-scan coercion, error folding).\n- [DAVERAGE](FUNC.DAVERAGE.md) — the family's shared criteria-range mechanism;\n  [DVAR](FUNC.DVAR.md) — the shared numerical account of the variance formula.\n- `data/functions/FUNC.DVARP.json`, `data/presence/FUNC.DVARP.json`.\n\n",
    "version-differences": "No comparison between specific Excel builds is recorded here yet. This does not establish that all builds behave alike.",
    "what-it-does": "\n`DVARP(database, field, criteria)` selects the records of *database* that satisfy *criteria*,\nreads the column named by *field*, and returns the **population** variance of the numeric values\nfound there.\n\nWith V = [ v₁ … vₙ ] the Numbers collected from the field column of the matching records, in\nrecord order, and n = |V|:\n\n    x̄  = (Σ vᵢ) / n\n    σ² = ( Σ (vᵢ − x̄)² ) / n\n\nThe only difference from [DVAR](FUNC.DVAR.md) is the divisor: n rather than n − 1. That single\nchange has two consequences worth stating separately, because readers usually notice the first\nand are caught by the second:\n\n1. `DVARP` is always the smaller of the two, by the factor (n − 1)/n.\n2. `DVARP` is **defined for n = 1** — the variance of a one-element population is exactly zero —\n   whereas `DVAR` requires two values. The two functions therefore disagree about whether a\n   given selection is an error at all, not merely about the number.\n\nChoosing between them is a modelling question, not a numerical one: divide by n when the\nselected records *are* the whole population you are describing, and by n − 1 when they are a\nsample drawn from a larger one. A criteria-filtered subset of a spreadsheet is very often the\nwhole population of interest, which is why `DVARP` is less exotic here than `VAR.P` is in\ngeneral statistics.\n\nNon-numeric cells in the field column — text, logicals, blanks — are skipped, so n counts\nnumbers, not records.\n\nThe selection stage — header matching, AND across a criteria row, OR down the rows, blank\ncriteria cells, and criteria-expression parsing — is identical for all twelve database functions\nand is explained once in\n[the criteria-range mechanism](FUNC.DAVERAGE.md#the-criteria-range-mechanism).\n\n\n### Arguments\n\n\nThree arguments, all required at the call site; the reference implementation declares an arity\nof exactly 3.\n\n- **`database`** — the header-plus-records range or array.\n- **`field`** — the column selector, as header text or as a 1-based column index within the\n  database range. Required.\n- **`criteria`** — the header-plus-conditions range or array.\n\n\n"
  },
  "signature": {
    "display": "DVARP(database, field, criteria)",
    "parameters": [
      {
        "description": null,
        "name": "database",
        "optional": false,
        "repeats": false
      },
      {
        "description": null,
        "name": "field",
        "optional": false,
        "repeats": false
      },
      {
        "description": null,
        "name": "criteria",
        "optional": false,
        "repeats": false
      }
    ],
    "trailing_repeats": false
  },
  "sources": {
    "metadata": {
      "admission": {
        "label": "implemented",
        "reason": null
      },
      "arity": {
        "max": 3,
        "min": 3
      },
      "category": "Database functions",
      "classification": {
        "arg_preparation_profile": "RefsVisibleInAdapter",
        "coercion_lift_profile": "Custom",
        "determinism_class": "Deterministic",
        "error_collapse_profile": "ReductionFold",
        "fec_dependency_profile": "RefOnly",
        "host_interaction_class": "None",
        "kernel_signature_class": "Custom",
        "rich_value_usage": "RichBlind",
        "surface_fec_dependency_profile": "RefOnly",
        "thread_safety_class": "SafePure",
        "volatility_class": "NonVolatile"
      },
      "descriptions": {
        "long": null,
        "short": "Population variance of a database column over the matching records",
        "short_source": "dna-calc-own"
      },
      "docs": {
        "english_description": "Calculates variance based on the entire population of selected database entries",
        "microsoft_url": "https://support.microsoft.com/en-us/office/dvarp-function-eb0ba387-9cb7-45c8-81e9-0394912502fc"
      },
      "entry_kind": "built_in_function",
      "localized_family_names": null,
      "localized_names": [
        {
          "locale": "ar-SA",
          "name": "DVARP"
        },
        {
          "locale": "bg-BG",
          "name": "DVARP"
        },
        {
          "locale": "cs-CZ",
          "name": "DVAR"
        },
        {
          "locale": "da-DK",
          "name": "DVARP"
        },
        {
          "locale": "de-DE",
          "name": "DVARP"
        },
        {
          "locale": "el-GR",
          "name": "DVARP"
        },
        {
          "locale": "en-AU",
          "name": "DVARP"
        },
        {
          "locale": "en-GB",
          "name": "DVARP"
        },
        {
          "locale": "en-US",
          "name": "DVARP"
        },
        {
          "locale": "es-ES",
          "name": "BDVARP"
        },
        {
          "locale": "et-EE",
          "name": "DVARP"
        },
        {
          "locale": "fi-FI",
          "name": "TVARIANSSIP"
        },
        {
          "locale": "fr-FR",
          "name": "BDVARP*"
        },
        {
          "locale": "he-IL",
          "name": "DVARP"
        },
        {
          "locale": "hr-HR",
          "name": "DVARP"
        },
        {
          "locale": "hu-HU",
          "name": "AB.VAR2"
        },
        {
          "locale": "id-ID",
          "name": "DVARP"
        },
        {
          "locale": "it-IT",
          "name": "DVARP"
        },
        {
          "locale": "ja-JP",
          "name": "DVARP"
        },
        {
          "locale": "ko-KR",
          "name": "DVARP"
        },
        {
          "locale": "lt-LT",
          "name": "DVARP"
        },
        {
          "locale": "lv-LV",
          "name": "DVARP"
        },
        {
          "locale": "nb-NO",
          "name": "DVARP"
        },
        {
          "locale": "nl-NL",
          "name": "DBVARP"
        },
        {
          "locale": "pl-PL",
          "name": "BD.WARIANCJA.POPUL"
        },
        {
          "locale": "pt-BR",
          "name": "DVARP"
        },
        {
          "locale": "pt-PT",
          "name": "BDVARP"
        },
        {
          "locale": "ro-RO",
          "name": "DVARP"
        },
        {
          "locale": "ru-RU",
          "name": "БДДИСПП"
        },
        {
          "locale": "sk-SK",
          "name": "DVARP"
        },
        {
          "locale": "sl-SI",
          "name": "DVARP"
        },
        {
          "locale": "sr-Latn-RS",
          "name": "DVARP"
        },
        {
          "locale": "sv-SE",
          "name": "DVARIANSP"
        },
        {
          "locale": "th-TH",
          "name": "DVARP"
        },
        {
          "locale": "tr-TR",
          "name": "VSEÇVARS işlevi"
        },
        {
          "locale": "uk-UA",
          "name": "DVARP"
        },
        {
          "locale": "vi-VN",
          "name": "DVARP"
        },
        {
          "locale": "zh-CN",
          "name": "DVARP"
        },
        {
          "locale": "zh-HK",
          "name": "DVARP"
        },
        {
          "locale": "zh-TW",
          "name": "DVARP"
        }
      ],
      "signature": {
        "display": "DVARP(database, field, criteria)",
        "parameters": [
          {
            "description": null,
            "name": "database",
            "optional": false,
            "repeats": false
          },
          {
            "description": null,
            "name": "field",
            "optional": false,
            "repeats": false
          },
          {
            "description": null,
            "name": "criteria",
            "optional": false,
            "repeats": false
          }
        ],
        "trailing_repeats": false
      },
      "surface_name": "DVARP",
      "version_marker": null,
      "xlcall": {
        "code": "196",
        "symbol": "xlfDvarp"
      }
    },
    "microsoft": "https://support.microsoft.com/en-us/office/dvarp-function-eb0ba387-9cb7-45c8-81e9-0394912502fc"
  },
  "try_it": {
    "formula": "=DVARP(B2:D6,\"Amount\",F2:F3)",
    "inputs": {
      "B2": "Name",
      "B3": "A",
      "B4": "B",
      "B5": "C",
      "B6": "D",
      "C2": "Group",
      "C3": "East",
      "C4": "East",
      "C5": "West",
      "C6": "East",
      "D2": "Amount",
      "D3": 10,
      "D4": 20,
      "D5": 30,
      "D6": 40,
      "F2": "Group",
      "F3": "East"
    }
  },
  "url": "https://handbook.dnacalc.com/functions/DVARP.html",
  "variants": [],
  "versions": []
}