# Core

[View on Github](https://github.com/CartoDB/carto-react-template)

{% hint style="warning" %}
**Note:** We are reducing our investment in CARTO for React and currently we discourage users from starting new projects with it.

CARTO for React is an opinionated framework with pre-built components and templates. This greatly speeds up the process to create React-based applications, but customization options are limited.

If you need further customization in React, or you want to build geospatial applications using **Vue, Angular, or any other Javascript-based framework**, we recommend going directly to the main CARTO for Developers documentation, including [CARTO + deck.gl](https://github.com/CartoDB/gitbook-documentation/blob/master/carto-for-developers/key-concepts/carto-for-deck.gl), which allows for maximum flexibility and scalability.
{% endhint %}

| Package           | Version                                                                                                                         | Downloads                                                                                                                          |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| @carto/react-core | [![version](https://img.shields.io/npm/v/@carto/react-core.svg?style=flat-square)](https://npmjs.org/package/@carto/react-core) | [![downloads](https://img.shields.io/npm/dt/@carto/react-core.svg?style=flat-square)](https://npmjs.org/package/@carto/react-core) |

Set of common functions, to be used mostly by other packages. You won’t usually consume this package directly, but when using `AggregationTypes` for widgets or when creating custom widgets.

**Tip:** The computations performed internally by widgets use these functions. They can be useful in the context of new custom widgets (for example using a different charting library)

## Functions <a href="#functions" id="functions"></a>

### **aggregationFunctions**

Contains a set of basic aggregation functions (count, min, max, sum, and average), used automatically for widgets and layers, see [AggregationTypes](#aggregationtypes). Functions are applicable to numbers and also objects using a numeric property.

* **Input**:

| Param  | Type     | Description                                                                  |
| ------ | -------- | ---------------------------------------------------------------------------- |
| values | `Array`  | Array of numbers or objects with a numerical property                        |
| \[key] | `string` | (optional). When using objects, name of the property to use for calculations |

* **Returns**: `Object` - An object with Aggregation functions, which keys are every `AggregationTypes` values
* **Example**:

```jsx
import { aggregationFunctions, AggregationTypes } from "@carto/react-core";

const values = [{ f: 1 }, { f: 2 }, { f: 3 }, { f: 4 }, { f: 5 }];
const avgFn = aggregationFunctions[AggregationTypes.AVG];

console.log(avgFn(values, "f")); // 3
```

### **groupValuesByColumn**

Makes groups from features based in a column (`keysColumn`) and applying an `operation` to the numeric values in a predefined column (`valuesColumn`).

* **Input**:

| Param        | Type     | Default | Description                                                                     |
| ------------ | -------- | ------- | ------------------------------------------------------------------------------- |
| data         | `Array`  |         | Features for calculations (plain objects with properties)                       |
| valuesColumn | `string` |         | Quantitative column for grouping (the name of a numeric property in the object) |
| keysColumn   | `string` |         | Qualitative column for grouping (the name of a string property in the object)   |
| operation    | `string` |         | Operation for groups calculations, see [AggregationTypes](#aggregationtypes)    |

* **Returns**: `Array` - Grouped values
* **Example**:

```jsx
import { groupValuesByColumn, AggregationTypes } from "@carto/react-core";

const data = [
  { category: "A", population: 100 },
  { category: "A", population: 200 },
  { category: "B", population: 50 },
];

const groups = groupValuesByColumn(data, "population", "category", AggregationTypes.SUM);

console.log(groups); // output: [ { name: 'A', value: 300 }, { name: 'B', value: 50 }]
```

### **histogram**

Categorizes numeric values as a histogram from a set of features, having the option of just calculating the frequency (with COUNT operation) or an aggregated operation on the features inside the bin (e.g., SUM).

* **Input**:

| Param      | Type     | Description                                                                                                                      |
| ---------- | -------- | -------------------------------------------------------------------------------------------------------------------------------- |
| features   | `Array`  | Features for calculations (plain objects with properties)                                                                        |
| columnName | `string` | Quantitative column for calculations (the name of a number property in the object)                                               |
| ticks      | `Array`  | Array of numbers to build intervals (eg 1, 5, 10 will defines 4 intervals: <1, 1 to 5, 5 to 10 and >10)                          |
| operation  | `string` | Operation for groups calculations, see [AggregationTypes](https://docs.carto.com/react/library-reference/core/#aggregationtypes) |

* **Returns**: `Array` - Histogram data for each bin, derived from ticks
* **Example**:

```jsx
import { histogram, AggregationTypes } from "@carto/react-core";

const features = [
  { field: 1 },
  { field: 2 },
  { field: 2 },
  { field: 3 },
  { field: 3 },
  { field: 3 },
  { field: 4 },
  { field: 4 },
  { field: 5 },
];

const ticks = [2, 4, 6];

const h = histogram(features, "field", ticks, AggregationTypes.COUNT);
console.log(h); // [1, 5, 3, 0]
/* 
        histogram results as:
        <2          --> 1 item
        >=2 to <4   --> 5 items
        >=4 to <6   --> 3 items
        >=6         --> 0 items
    */
```

### **scatterPlot**

Receives an array of features and the properties that will be used for each axis, checks that properties are valid and returns a formatted array.

* **Input**:

| Param       | Type     | Description                                |
| ----------- | -------- | ------------------------------------------ |
| features    | `Array`  | Features                                   |
| xAxisColumn | `string` | Property containing values for the X axis. |
| yAxisColumn | `string` | Property containing values for the Y axis. |

* **Returns**: `Array` - Formatted array.
* **Example**:

```jsx
import { scatterPlot } from "@carto/react-core";

const data = [
  { x: 0 }, // Missing y
  { y: 1 }, // Missing x
  { x: null, y: 1 }, // null x
  { x: 1, y: null }, // null y
  { x: 0, y: 0 }, // zero for both
  { x: 1, y: 2 }, // valid
  {}, // no values for both
  { x: 2, y: 3 } // valid
];
sp = scatterPlot(data, 'x', 'y'));
console.log(sp); // [[0, 0],[1, 2],[2, 3]]; Invalid values are filtered out
```

## Constants & enums <a href="#constants--enums" id="constants--enums"></a>

### **AggregationTypes**

Enum for the different types of aggregations, available for widgets.

* **Options**:
  * COUNT
  * SUM
  * AVG
  * MIN
  * MAX
* **Example:**

```jsx
import { AggregationTypes } from "@carto/react-core";

console.log(AggregationTypes.COUNT);
```