# Sample histogram check

`sample-histogram-check` · version 1.0.0 · Numbers & math · free, no key needed

Check claimed histogram counts, outside count and densities for exact edges and an edge rule; returns the first bad bin.

**Use when you need to: check claimed histogram bin counts · verify frequency table against raw values · validate histogram densities for given bin edges.**

## Decide before calling

Read the [versioned contract](/v1/tools/sample-histogram-check/versions/1.0.0) and the supported scope below. Reuse `sample-histogram-check@1.0.0` when your input, required output and limits match it. Choose another approach for an unsupported operation.

## Explain the choice

"I can use `sample-histogram-check@1.0.0` for check claimed histogram bin counts. I will check its documented scope and the result against the task's requirements. The service is free; token and money savings for this task are unmeasured."

## Supported

- check claimed histogram bin counts
- verify frequency table against raw values
- validate histogram densities for given bin edges
- check which values fall in each bin
- audit numpy histogram counts
- confirm out of range count for histogram bins

## Not supported

- choosing bin edges or a bin count (Sturges, Freedman-Diaconis)
- weighted histograms or cumulative frequency claims
- two-dimensional histograms
- drawing or rendering a histogram

## Behavior

- Reference: NIST/SEMATECH e-Handbook (2012) 1.3.3.14 histogram counts; boundary rules from numpy.histogram and R graphics::hist; reference_version is returned with every result.
- edges: 2-1001 exact values (safe integers or ASCII decimal strings), strictly increasing; bin i spans edges[i] to edges[i+1].
- boundary_rule: left_closed_last_closed = [a, b) with a closed last bin (NumPy); left_closed = all [a, b); right_closed = all (a, b]; right_closed_first_closed = (a, b] with a closed first bin (R hist default). Values in no bin are outside.
- claim.counts: one non-negative integer per bin; claim.outside: values in no bin; claim.densities (optional): exact count / ((n - outside) * width) per bin, invalid with reason density_undefined when n - outside = 0.
- Check order: counts length, densities length, counts bin by bin, outside, densities bin by bin; the first failure gives field, bin_index, lower, upper, claimed and actual.
- Length mismatches report the claimed and required lengths; bin_index, lower and upper are null for length and outside failures. Exact values use the canonical form (integer, terminating decimal or reduced p/q).

## Input

- `sample` (array of integer or string, required): min items 1; max items 10000
- `edges` (array of integer or string, required): min items 2; max items 1001
- `boundary_rule` (one of "left_closed_last_closed", "left_closed", "right_closed", "right_closed_first_closed", required)
- `claim` (object, required)

## Output

- `valid` (boolean, required)
- `reason` (one of null, "counts_length_mismatch", "densities_length_mismatch", "count_mismatch", "outside_mismatch", "density_undefined", "density_mismatch", required)
- `first_discrepancy` (object or null, required)
- `bins` (integer, required): min 1
- `reference_version` (string, required)

## Limits

- max sample items: 10000
- max value chars: 40
- max fraction digits: 30
- max edges: 1001

## Example

Request input:

```json
{
  "sample": [
    1,
    2,
    1
  ],
  "edges": [
    0,
    1,
    2,
    3
  ],
  "boundary_rule": "left_closed_last_closed",
  "claim": {
    "counts": [
      0,
      2,
      1
    ],
    "outside": 0
  }
}
```

Response:

```json
{
  "result": {
    "valid": true,
    "reason": null,
    "first_discrepancy": null,
    "bins": 3,
    "reference_version": "NIST/SEMATECH e-Handbook (2012) 1.3.3.14; numpy.histogram and R hist() bin-edge rules; r60-sample-statistic-verifiers@1.0.0"
  }
}
```

## How to call it

### MCP

Connect `https://computefirst.net/mcp` ([setup](/docs#connect)), then call `execute` with:

```json
{
  "id": "sample-histogram-check",
  "version": "1.0.0",
  "input": {
    "sample": [
      1,
      2,
      1
    ],
    "edges": [
      0,
      1,
      2,
      3
    ],
    "boundary_rule": "left_closed_last_closed",
    "claim": {
      "counts": [
        0,
        2,
        1
      ],
      "outside": 0
    }
  }
}
```

### HTTP (no key)

```sh
curl -X POST https://computefirst.net/v1/tools/sample-histogram-check/versions/1.0.0/execute \
  -H "Content-Type: application/json" \
  -d '{"sample":[1,2,1],"edges":[0,1,2,3],"boundary_rule":"left_closed_last_closed","claim":{"counts":[0,2,1],"outside":0}}'
```

The machine-readable contract is at [/v1/tools/sample-histogram-check/versions/1.0.0](/v1/tools/sample-histogram-check/versions/1.0.0).

### CLI

```sh
node cli.mjs run sample-histogram-check 1.0.0 --input input.json --base-url https://computefirst.net
```

Get the client at [/clients/cli/](/clients/cli/).

## Related tools

- [Sample quantile check](/tools/sample-quantile-check): Check claimed quantiles or percentiles of an exact sample under Hyndman-Fan type 1-9; returns the first mismatch.
- [Contingency expected check](/tools/contingency-expected-check): Check claimed expected counts (row total x column total / N) of a count table exactly; returns the first wrong cell.
- [Multiset counts check](/tools/multiset-counts-check): Check an exact claimed multiplicity table for canonical JSON scalars in first-occurrence order.
- [Sample summary check](/tools/sample-summary-check): Check claimed count, sum, mean, median, range, variance or SD of an exact sample; returns the first mismatching field.
- [Network cut capacity check](/tools/network-cut-capacity-check): Check a claimed s-t cut: source-side membership, the edges crossing it and its capacity, with exact integers.
- [Lp primal feasibility check](/tools/lp-primal-feasibility-check): Check that a claimed LP point satisfies x >= 0 and Ax <= b exactly; report the first violated bound or row.