# Stats histogram

`stats-histogram` · version 1.0.0 · Other utilities · free, no key needed

Count decimal-string values in caller-supplied fixed bins and return below- and above-range totals.

**Use when you need to: build a fixed bin histogram · count values in numeric ranges · bucket decimal string values.**

## Decide before calling

Read the [versioned contract](/v1/tools/stats-histogram/versions/1.0.0) and the supported scope below. Reuse `stats-histogram@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 `stats-histogram@1.0.0` for build a fixed bin histogram. 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

- build a fixed bin histogram
- count values in numeric ranges
- bucket decimal string values
- histogram with custom edges
- count below and above bins
- frequency table for fixed intervals

## Not supported

- automatic bin selection
- weighted histogram

## Behavior

- Bins are left-closed and right-open, except the final bin is closed at both ends.
- Values outside the edge range are counted in below or above; decimal comparisons are exact.

## Input

- `values` (array of string, required): min items 1; max items 256; each min length 1; each max length 128
- `bin_edges` (array of string, required): min items 2; max items 65; each min length 1; each max length 128

## Output

- `standard_version` (constant "packet-r90-fixed-bin-histogram-1.0.0", required)
- `counts` (array of integer, required): each min 0
- `below` (integer, required): min 0
- `above` (integer, required): min 0

## Limits

- max input bytes: 16384
- max items: 256
- max bin edges: 65
- max decimal chars: 128
- max output bytes: 16384
- max bin comparisons: 4096

## Example

Request input:

```json
{
  "values": [
    "0",
    "1",
    "2",
    "3"
  ],
  "bin_edges": [
    "0",
    "2",
    "3"
  ]
}
```

Response:

```json
{
  "result": {
    "standard_version": "packet-r90-fixed-bin-histogram-1.0.0",
    "counts": [
      2,
      2
    ],
    "below": 0,
    "above": 0
  }
}
```

## How to call it

### MCP

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

```json
{
  "id": "stats-histogram",
  "version": "1.0.0",
  "input": {
    "values": [
      "0",
      "1",
      "2",
      "3"
    ],
    "bin_edges": [
      "0",
      "2",
      "3"
    ]
  }
}
```

### HTTP (no key)

```sh
curl -X POST https://computefirst.net/v1/tools/stats-histogram/versions/1.0.0/execute \
  -H "Content-Type: application/json" \
  -d '{"values":["0","1","2","3"],"bin_edges":["0","2","3"]}'
```

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

### CLI

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

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

## Related tools

- [Array duplicates find](/tools/array-duplicates-find): List duplicated JSON values with counts and first indexes, preserving first-seen order.
- [Bytes format human](/tools/bytes-format-human): Format an exact byte count as both SI and IEC strings and return the rounding mode used.
- [Cron describe fields](/tools/cron-describe-fields): Parse a five-field cron expression and return each field’s expanded numeric values and wildcard status.
- [Stats describe exact](/tools/stats-describe-exact): Return exact descriptive statistics and requested-precision standard deviations for decimal strings.
- [Polygon measures compute](/tools/polygon-measures-compute): Compute exact signed double-area, area, orientation, and squared edge lengths for a rational simple polygon.
- [Stats percentile](/tools/stats-percentile): Compute an exact percentile from decimal strings using a named Hyndman-Fan type 1 through 9.