{"id":13893761,"url":"https://github.com/RobTillaart/Correlation","last_synced_at":"2025-07-17T08:30:46.049Z","repository":{"id":40994917,"uuid":"264906119","full_name":"RobTillaart/Correlation","owner":"RobTillaart","description":"Arduino library to determine the correlation between X and Y datasets.","archived":false,"fork":false,"pushed_at":"2025-03-24T15:20:19.000Z","size":55,"stargazers_count":8,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-02T22:04:56.517Z","etag":null,"topics":["arduino","correlation","math","statistics"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/RobTillaart.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"RobTillaart","custom":"https://www.paypal.me/robtillaart"}},"created_at":"2020-05-18T10:30:58.000Z","updated_at":"2025-03-24T15:19:58.000Z","dependencies_parsed_at":"2024-11-19T06:41:39.419Z","dependency_job_id":null,"html_url":"https://github.com/RobTillaart/Correlation","commit_stats":null,"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/RobTillaart/Correlation","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RobTillaart%2FCorrelation","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RobTillaart%2FCorrelation/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RobTillaart%2FCorrelation/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RobTillaart%2FCorrelation/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/RobTillaart","download_url":"https://codeload.github.com/RobTillaart/Correlation/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RobTillaart%2FCorrelation/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265585272,"owners_count":23792712,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["arduino","correlation","math","statistics"],"created_at":"2024-08-06T18:01:16.597Z","updated_at":"2025-07-17T08:30:46.043Z","avatar_url":"https://github.com/RobTillaart.png","language":"C++","funding_links":["https://github.com/sponsors/RobTillaart","https://www.paypal.me/robtillaart"],"categories":["C++"],"sub_categories":[],"readme":"\n[![Arduino CI](https://github.com/RobTillaart/Correlation/workflows/Arduino%20CI/badge.svg)](https://github.com/marketplace/actions/arduino_ci)\n[![Arduino-lint](https://github.com/RobTillaart/Correlation/actions/workflows/arduino-lint.yml/badge.svg)](https://github.com/RobTillaart/Correlation/actions/workflows/arduino-lint.yml)\n[![JSON check](https://github.com/RobTillaart/Correlation/actions/workflows/jsoncheck.yml/badge.svg)](https://github.com/RobTillaart/Correlation/actions/workflows/jsoncheck.yml)\n[![GitHub issues](https://img.shields.io/github/issues/RobTillaart/Correlation.svg)](https://github.com/RobTillaart/Correlation/issues)\n\n[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/RobTillaart/Correlation/blob/master/LICENSE)\n[![GitHub release](https://img.shields.io/github/release/RobTillaart/Correlation.svg?maxAge=3600)](https://github.com/RobTillaart/Correlation/releases)\n[![PlatformIO Registry](https://badges.registry.platformio.org/packages/robtillaart/library/Correlation.svg)](https://registry.platformio.org/libraries/robtillaart/Correlation)\n\n\n# Correlation\n\nArduino library to determine the linear correlation between X and Y datasets.\n\n\n## Description\n\nThis library calculates the coefficients of the linear correlation\nbetween two (relative small) datasets. The size of these datasets is\n20 by default. The size can be set in the constructor.\n\nPlease note that the correlation object uses about ~50 bytes per instance,\nand 2 floats == 8 bytes per pair of elements.\nSo ~120 elements will use up 50% of the RAM of an UNO.\n\nThe formula of the correlation is expressed as **Y = A + B \\* X**.\n\nIf all points are on a vertical line, e.g. **Y = 3**, the parameter B will be NAN,\nThis will happen if the **sumX2** is zero or very small.\n\nUse with care.\n\n\n### Related\n\n- https://github.com/RobTillaart/Correlation\n- https://github.com/RobTillaart/GST - Golden standard test metrics\n- https://github.com/RobTillaart/Histogram\n- https://github.com/RobTillaart/RunningAngle\n- https://github.com/RobTillaart/RunningAverage\n- https://github.com/RobTillaart/RunningMedian\n- https://github.com/RobTillaart/statHelpers - combinations \u0026 permutations\n- https://github.com/RobTillaart/Statistic\n- https://github.com/RobTillaart/PrintHelpers - print values in scientific / engineering format.\n\n\n## Interface\n\n```cpp\n#include \"Correlation.h\"\n```\n\n### Constructor\n\n- **Correlation(uint8_t size = 20)** allocates the arrays needed and resets internal admin.\nSize should be between 1 and 255. Size = 0 will set the size to 20.\nIf the arrays cannot be allocated size will be set to zero.\n- **~Correlation()** frees the allocated arrays.\n\n\n### Base functions\n\n- **bool add(float x, float y)** adds a pair of **floats** to the internal storage array's.\nReturns true if the value is added, returns false when internal array is full.\nWhen running correlation is set, **add()** will replace the oldest element and return true.\nWarning: **add()** does not check if the floats are NAN or INFINITE.\n- **uint8_t count()** returns the amount of items in the internal arrays.\nThis number is always between 0 ..**size()**\n- **uint8_t size()** returns the size of the internal arrays.\n- **void clear()** resets the data structures to the start condition (zero elements added).\n- **bool calculate()** does the math to calculate the correlation parameters A, B and R.\nThis function will be called automatically when needed.\nYou can call it on a more convenient time.\nReturns false if nothing to calculate **count == 0**\n\n### Configure calculation\n\n- **void setR2Calculation(bool)** enables / disables the calculation of Rsquared.\n- **bool getR2Calculation()** returns the flag set.\n- **void setE2Calculation(bool)** enables / disables the calculation of Esquared.\n- **bool getE2Calculation()** returns the flag set.\n\n\n### Get correlation parameters\n\nAfter the calculation the following functions can be called to return the core values.\n- **float getA()** returns the A parameter of formula **Y = A + B \\* X**\n- **float getB()** returns the B parameter of formula **Y = A + B \\* X**\n- **float getR()** returns the correlation coefficient R which is always between -1 .. 1\nThe closer to 0 the less correlation there is between X and Y.\nCorrelation can be positive or negative.\nMost often the Rsquared **R x R** is used.\n- **float getRsquare()** returns **R x R** which is always between 0.. 1.\n- **float getEsquare()** returns the error squared to get an indication of the\nquality of the correlation.\n- **float getAverageX()** returns the average of all elements in the X dataset.\n- **float getAverageY()** returns the average of all elements in the Y dataset.\n- **float getEstimateX(float y)** use to calculate the estimated X for a given Y.\n- **float getEstimateY(float x)** use to calculate the estimated Y for a given X.\n\n\n### Correlation Coefficient R\n\nIndicative description of the correlation value.\n\n|  R             |  correlation  |\n|:--------------:|:--------------|\n|  +1.0          |  Perfect      |\n|  +0.8 to +1.0  |  Very strong  |\n|  +0.6 to +0.8  |  Strong       |\n|  +0.4 to +0.6  |  Moderate     |\n|  +0.2 to +0.4  |  Weak         |\n|   0.0 to +0.2  |  Very weak    |\n|  -0.0 to +0.0  |  None         | -0.05..+0.05?\n|  -0.0 to -0.2  |  Very weak    |\n|  -0.2 to -0.4  |  Weak         |\n|  -0.4 to -0.6  |  Moderate     |\n|  -0.6 to -0.8  |  Strong       |\n|  -0.8 to -1.0  |  Very strong  |\n|  -1.0          |  Perfect      |\n\nThe library does not provide these as a string array as the boundaries are subjective.\nNote the table is symmetrical.\n\n\n### Running correlation\n\n- **void setRunningCorrelation(bool rc)** sets the internal variable runningMode\nwhich allows **add()** to overwrite old elements in the internal arrays.\n- **bool getRunningCorrelation()** returns the runningMode flag.\n\nThe running correlation will be calculated over the last **count** elements.\nIf the array is full, count will be size.\nThis running correlation allows for more adaptive formula finding e.g. find the\nrelation between temperature and humidity per hour, and how it changes over time.\n\n\n### Bounding box of data points\n\nThese functions give an indication of the \"trusted interval\" for estimations.\nThe idea is that for **getEstimateX()** the further outside the range defined\nby **getMinX()** and **getMaxX()**, the less the result can be trusted.\nThis also depends on **R** of course. Idem for **getEstimateY()**\n\nThe functions to find the \"bounding box\" of the \"trusted interval\".\n\n- **float getMinX()** idem\n- **float getMaxX()** idem\n- **float getMinY()** idem\n- **float getMaxY()** idem\n\n\n### Debugging / educational\n\nNormally not used. For all these functions index should be \u003c count!\notherwise the setters return false to indicate failure, while the \ngetters will return NAN.\n\n- **bool setXY(uint8_t index, float x, float y)** overwrites a pair of values.\nReturns true if succeeded.\n- **bool setX(uint8_t index, float x)** overwrites single X.\n- **bool setY(uint8_t index, float y)** overwrites single Y.\n- **float getX(uint8_t index)** returns single value.\n- **float getY(uint8_t index)** returns single value.\n\nCalculated internals:\n\n- **float getSumXY()** returns sum(Xi \\* Yi).\n- **float getSumX2()** returns sum(Xi \\* Xi).\n- **float getSumY2()** returns sum(Yi \\* Yi).\n\n\n### Obsolete since 0.3.0\n\nTo improve readability the following functions are replaced.\n\n- **float getAvgX()**    ==\u003e **getAverageX()**\n- **float getAvgY()**    ==\u003e **getAverageY()**\n- **float getSumXiYi()** ==\u003e **getSumXY()**\n- **float getSumXi2()**  ==\u003e **getSumX2()**\n- **float getSumYi2()**  ==\u003e **getSumY2()**\n\n\n## Future\n\n#### Must\n\n- improve documentation\n\n#### Should\n\n- examples\n  - real world if possible.\n\n#### Could\n\n- Template version?\nThe constructor should get a TYPE parameter, as this\nallows smaller data types to be analysed taking less memory.\nOr allow more elements in same amount of RAM.\n- put configuration booleans into one byte to save 3 bytes RAM\n\n#### Wont\n\n- move code from .h to .cpp\n\n## Support\n\nIf you appreciate my libraries, you can support the development and maintenance.\nImprove the quality of the libraries by providing issues and Pull Requests, or\ndonate through PayPal or GitHub sponsors.\n\nThank you,\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FRobTillaart%2FCorrelation","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FRobTillaart%2FCorrelation","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FRobTillaart%2FCorrelation/lists"}