# getHistogram

A Histogram model is a data model that represents a list of labeled data points for *bins* (ranges) of data, defined as ticks over a numerical range, Suitable for histogram charts.

## **Usage**

```typescript
const formula = await dataSource.getHistogram({
    column: 'column_A',
    ticks: [5, 10, 15],
    operation: 'count'
    // + base options...
});
```

## **Options**

The `getHistogram` model inherits all options from the [base options](https://docs.carto.com/carto-for-developers/reference/carto-widgets-reference/models/..#model-base-options), plus:

```typescript
export interface HistogramRequestOptions extends BaseRequestOptions {
  column: string;
  ticks: number[];
  operation: 'count' | 'avg' | 'min' | 'max' | 'sum';
}
```

* **column:** the name of the column that you will run the statistical operation on. It also accepts the `*` value, that will
* **ticks**: the list of numerical **upper bound** thresholds that will be used to create the bins. There's no maximum number of ticks.
* **operation:** the aggregation that will be performed on the `column` for each range bin. Accepted values are:
  * `count`
  * `avg`
  * `min`
  * `max`
  * `sum`

## **Response**

An ordered array containing the value for each histogram bin.

{% hint style="info" %}
Please note that the response always contain one additional row compared to the amount of ticks specified in the options. This is because ticks are the upper bound threshold, and there needs to be an additional bucket for values above the last tick.
{% endhint %}

```typescript
type HistogramModelResponse = number[];
/* example response 
  [
    389, // < 5
    648, // 5-9
    478, // 10-14
    120 // > 15
  ]
*/    
```

The response can be then mapped to any HTML element, but commonly it will be mapped to a a charting library to create histogram charts.

<figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-49815b1fe0fae91eec7a0e6cbab8f05cc3642947%2FScreenshot%202024-09-02%20at%2017.34.15.png?alt=media" alt=""><figcaption></figcaption></figure>