Skip to content

Latest commit

 

History

History
258 lines (199 loc) · 8.51 KB

README.md

File metadata and controls

258 lines (199 loc) · 8.51 KB
Raw

NPM version License NPM downloads

chartjs-plugin-regression

Chart.js plugin to calculate and draw statistical linear, exponential, power, logarithmic, and polynomial regressions using chart datasets data.

The plugin, at the current version, uses the regression npm package as its calculation engine.

Important

  • Only bar, line, and scatter chart types are supported.
  • The plugin works just fine with [email protected], however that version may have some problems handling certain color configuration (not related with the plugin). No problems have been found with chart.js@^2.6.0.
  • The plugin does not work with [email protected]

Demo

For a better understanding of the capabilities of this plugin, please see this Live Demo.

Download

The compressed version includes the regression package.

Installation

npm install --save chartjs-plugin-regression

Usage

For a single chart, it needs to be listed in plugins section.

Example:

new Chart(ctx, {
  type: 'bar',
  plugins: [
    // This chart will use the plugin
    ChartRegressions
  ],
  data: {
    ...
    datasets: [
      {
        ...
        // Configuration of the plugin per dataset (only will be drawn the datasets with this property) 
        regressions: {
          type: 'linear',
          line: { color: 'red', width: 3},
          ...
        }
      }
    ]
    ...
  }
});

Also, it's possible to register the plugin for all the charts:

Chart.plugins.register(ChartRegressions);

Configuration

The plugin has three levels of configuration:

  • global (for all the datasets in a chart)
  • Per dataset
  • Per section

There are common properties that the three levels share, and the priority of them are: section, dataset, and global.

Common properties

Common to the three levels of configuration.

Property Description
type Type of regression to be calculated. It can be 'copy', 'linear', 'exponential', 'power', 'polynomial', 'polynomial3', 'polynomial4', or 'logarithmic'. It also can be an array with a combination of these types, in which case the regression type with the best R² will be drawn.
line Line configuration for drawing the regression. It has the following properties: {width, color, dash}
calculation Precision and polynomial order of the values returned by the regression calculations
extendPredictions Previous sections predictions for the current section will be drawed as dashed lines
copy Only if type=='copy'. Behavior of sections that copy other section's calculation

Some considerations:

  • type: polynomial3 and polynomial4 are pseudo-types added for convenience, they allow combinationss where the plugin will draw the regression with bigger R². Example:
{
  type: ['polynomial', 'polynomial3', 'polynomial4'],
  calculation: {order 2}
}
  • calculation has the following properties:
Property Description
precision Determines how many decimals will have the results (default: 2).
order Only for polynomial regression type, i.e. polynomial3 and polynomial4 are not affected by this property. Example: ax² + bx + c has order 2.
  • copy has the following properties:
Property Description
overwriteData Possible values: 'none', 'all', 'empty', or 'last'. Default: 'none'. It determines how the dataset's data will be overwritten in this section (empty: Only zero, undefined, or null data will be overwriten). Obs. the plugin is only prepared to overwrite numerical data arrays, e.g. [1,2,3,...], scatter charts use xy data arrays, e.g. [{x:1,y:1}, {x:2,y:2},...], with them the behavior is undetermined. In these cases it's better use overwriteData: 'none'.
minValue Minimum value that the predicted value can be written into the data.
maxValue Maximum value that the predicted value can be written into the data.

Global

The global configuration affects all the regressions calculated for all the datasets in the chart. It contains all the common properties and the following properties:

Property Description
onCompleteCalculation Callback called when the regressions for all the datasets in a chart have been calculated

Example:

options: {
  plugins: {
    regressions: {
      type: ['linear', 'polynomial'],
      line: { color: 'blue', width: 3 },
      onCompleteCalculation: function callback(chart){ ... }
    }
  }
}

Per Dataset

It's possible to configure the regressions per dataset. The configuration will contain all the common properties and the following properties:

Property Description
sections Array of sections of the data that shall be drawn. If not specified it's assumed [{start:0,end:data.length-1}]

Example:

datasets: [
  {
    ...
    // Configuration of the plugin per dataset (only will be drawn the datasets with this property) 
    regressions: {
      type: ['linear','exponential'],
      line: { color: '#ff0', width: 3},
      calculation: { precision: 5 },
      sections: [{startIndex: 10, endIndex: 50}],
      ...
    }
  }
]

Per Section

Each section can be configured independently using all the common properties and the following properties:

Property Description
startIndex Start index on dataset's data. Default: 0
endIndex End index on dataset's data. Default: data.length-1
label Label that will be drawn in the top of the right border line. Default: xaxis' label
copy.fromSectionIndex Copy the predictions calculated by other section (the one with index fromSectionIndex)

Example:

datasets: [
  {
    ...
    // Configuration of the plugin per dataset (only will be drawn the datasets with this property) 
    regressions: {
      line: { width: 3 },
      calculation: { precision: 5 },
      sections: [
        {
          type: ['linear','exponential'],
          line: { color: 'red' },
          startIndex: 10, 
          endIndex: 50
        },
        {
          type: 'polynomial',
          line: { color: 'green' },
          startIndex: 50, 
          endIndex: 80,
          calculation: { order: 4 }
        },
      ]
    }
  }
  ...
]

API

.getDataset(chart, datasetIndex)

Returns the metadata associated to one dataset used internally by the plugin to work.

var meta = ChartRegressions.getDataset(chart, datasetIndex);

This object provides the following information:

Property Description
sections array of sections for each dataset (it will contain at least 1 section)
getXY(x, y) Returns the canvas coordinates {x,y} for the data point x, y.
topY Minimum y coordinate in the canvas.
bottomY Maximum y coordinate in the canvas.

.getSections(chart, datasetIndex)

Returns the sections with all the properties calculated (some with default values, or inherited from dataset's plugin configuration or the global configuration in options).

This object provides the following information:

Property Description
type array of regression types used to calculate and draw the section.
startIndex Index of the dataset's data.
endIndex Index of the dataset's data.
line Configuration used to draw the lines {color, width, dash}.
result Regression calculation result (see demo) to see how to use this information.

Events

onCompleteCalculation(chart)

The plugin provides one single event to inform when the calculation of all the regresions for a chart have been conmpleted.

This callback should be configured in the chart options.

Example:

options: {
  plugins: {
    regressions: {
      onCompleteCalculation: function callback(chart){ ... }
    }
  }
}

License

The project is released under the ISC license.