SciGrapher.js

SciGrapher.js is a JavaScript/TypeScript library capable of producing high quality scientific oriented graphs on the browser with minimum configuration. It's based on the HTML canvas element to ensure high responsively and avoid overload the DOM with potentially hundreds of elements.

What do I mean with "scientific oriented"?

SciGrapher.js, unlike other tools like Chart.js or D3.js, is not a general purpose charting library, its goal is to accurately represent numeric data generated by mathematical equations or other (physical) sources. The resulting graphs are closer to those generated by MATLAB or Matplotlib, rather than an illustrative panel, for example.

At the moment, the library offers four chart types, including:

Line chart, this can be used to generate dispersion graphs as well.
Area, used to represent the area between two curves.
Heatmap, to represent scalar fields.
Vector field, to represent two-dimensional vector fields.

Installation

To install just type

npm install scigrapher

In a terminal on your project folder.

Usage

Each graph is controlled by a single object created by calling the graph2D function.

graph2D(element)
graph2D(element, options)

Where

element is a div element.
options is an object containing the options to change the default behavior and appearance of the graph.

Note: The options object has a lot of properties and complex structure, its use is intended for copying or generate graphs from another graphs. All its properties are breake down in the graph2D methods, is best to use those instead.

To start, call the graph2D function and assign the object generated to a variable, use its methods to change the appearance and behavior to your needs and finally call the draw method to render the final result. The methods can be chained.

HTML:

<body>
   <div id="my-graph"></div>
</body>

JS:

const element = document.querrySelector("#my-graph");
const graph = graph2D(element).axisPoition("center").draw();

Result:

Almost every method is overcharged, so you can set or get the properties, for example calling graph.axisType() will return the current axis type used in the graph, and calling graph.axisType("polar") will set the graph axis type to polar and return a reference to the same graph object, so more methods can be chained.

Additionally, almost every method accepts a callback function as a second parameter. This callback will be executed right after the graph properties are updated, but before is render to the screen.

The callback function can accept one optional parameter that represents the graph object from which the method is call upon.

Note: The execution of the optional callback function is unique to that method call, so in order to execute that function more than ones it needs to be passed to the method on each call.

Warning: The callback function will only run if there is a change in the graph properties. For example, if you try to change the axis type to polar but the axis already have that property value the function will skyp all calculations, including the callback, and continue with the normal flow.

To add data to the graph, you need to call the addDataset method specifying the type of the data you intend to create, the return value can be stored in a variable to later use.

addDataset(datatype)
addDataset(datatype, options)

Where:

datatype is one of the data types available : "linechart", "area", "heatmap" or "vectorfield".
options is an object containing the options to change the default behavior and appearance of the dataset.

Note. The options object has a lot of properties and complex structure, its use is intended for copying or generate datasets from another datasets. All its properties are breake down in the corresponding dataset methods, is best to use those instead.

The resulting dataset is bound to the graph, so in order to render the result, you must call the draw method of the graph after the dataset creation or any modification made to it.

Example:

const element = document.querrySelector("#my-graph");
const graph = graph2D(element)
	      .axisDomain({
	          x : {start : -8, end : 8},
		  y : {start : -1.2, end : 1.2}
	       })
	      .containerSize({width : 800, height : 300});

const data = graph.addDataset("linechart")
	      .dataX(linspace(-8, 8, 100))
	      .dataY((dataset)=>{
	          return dataset.dataX().map(x=>Math.cos(x));
	       });

graph.draw();

Result:

The details on how to manipulate the datasets will be discussed in its corresponding section.

Graph Methods

Background

Color:

This method returns or changes the graph background color.

Method:

backgroundColor()
backgroundColor(option)
backgroundColor(option, callback)

Where:

option is a string representing the background color in the format #rrggbb or any of the standard color names.
callback is a function that is run after the color is set but before the next render, this callback accepts an optional argument that represents the graph object from which the method is called upon.

Returns:

A string representing the graph background color if no arguments are passed.
A reference to the graph object from which the method is called upon.

Default value:

The default value for the background color is "#ffffff" (white)

Opacity:

This method returns or changes the graph background opacity.

Method:

backgroundOpacity()
backgroundOpacity(option)
backgroundOpacity(option, callback)

Where:

option is a number between 0 and 1 representing the graph background opacity.
callback is a function that is run after the opacity is set but before the next render, this callback accepts an optional argument that represents the graph object from which the method is called upon.

Returns:

A number between 0 and 1 representing the graph background opacity if no arguments are passed.
A reference to the graph object from which the method is called upon.

Default value:

The default value of the background opacity is 1

Axis

Position:

This method returns or change the current axis position.

Method:

axisPosition()
axisPosition(option)
axisPosition(option, callback)

Where:

option is a string representing the axis position, the available options are:
- "center"
- "bottom-left"
- "bottom-right"
- "top-left"
- "top-right"
callback is a function that is run after the axis position is set but before the next render, this callback accepts an optional argument that represents the graph object from which the method is called upon.

Returns:

A string representing the current axis position if no arguments are passed.
A reference to the graph object from which the method is called upon.

Default value:

The default value for the axis position is "center".

Type:

This method returns or changes the current axis type.

Method:

axisType()
axisType(option)
axisType(option, callback)

Where:

option is a string representing the axis type, the available options are:
- "rectangular": Linear scales on both axis.
- "polar": Effectively the same as "rectangular" but with the grid in polar representation.
- "x-log": Base 10 logarithmic scale on the x axis and linear scale on the y axis.
- "y-log": Base 10 logarithmic scale on the y axis and linear scale on the x axis.
- "log-log" Base 10 logarithmic scale on both axis.
callback is a function that is run after the axis type is set but before the next render, this callback accepts an optional argument that represents the graph object from which the method is called upon.

Warning: An axis cannot have a logarithmic scale set unless its domain is strictly positive or negative, in other words the axis domain must contain only positive values or only negative values not include zero.

Returns:

A string representing the current axis type if no arguments are passed.
A reference to the graph object from which the method is called upon.

Default value:

The default value for the axis type is "rectangular".

Domain:

This method returns or sets the current domain of each axis. It is only necessary to define the values that you want to change and only that values will be updated, leaving the rest as they are.

Method:

axisDomain()
axisDomain(options)
axisDomain(options, callback)

Where:

options is an object representing the axis domain, this object has the properties:
- x : An object containing the properties start and end.
  - The property start is the value at the left most side of the x axis.
  - The property end is the value at the right most side of the x axis.
- y : An object containing the properties start and end.
  - The property start is the value at the bottom of the y axis.
  - The property end is the value at the top of the y axis.
callback is a function that is run after the axis domain is set but before the next render, this callback accepts an optional argument that represents the graph object from which the method is called upon.

Why the end value of the y axis is at the top and not the bottom? : Because of the convention of having the vertical axis values increase from bottom to top, this is a convention to follow for other similar properties.

On that note, it is not necessary to have the start value be smaller than the end value. In that case, the axis "direction" will be reverted.

Returns:

An object representing the current axis domain if no arguments are pass.
A reference to the graph object from which the method is called upon.

Default values:

The default values for the axis domain are as follows:

{
   x : {
      start : -5,
      end : 5
   },
   y : {
      start : -5,
      end : 5
   }
}

Color:

This method lets you set or get the current colors of each axis base, ticks and text independently.

The options object has some properties that change the colors in a generalized way, and those changes cascaded towards the more specific properties. The more specific the property is, the more priority takes.

It is only necessary to define the values that you want to change and only that values will be updated, leaving the rest as they are.

Method:

axisColor()
axisColor(options)
axisColor(options, callback)

Where:

options is an object that represent the color of each axis base, ticks and text. This object has the following properties:
- axis : a string representing the color of both whole axis.
- xAxis : a string representing the color of the whole x axis.
- yAxis : a string representing the color of the whole y axis.
- base : an object containing the following properties:
  - x: a string representing the color of the x axis base.
  - y: a string representing the color of the y axis base.
- tick : an object containing the following properties:
  - x: a string representing the color of the x axis ticks.
  - y: a string representing the color of the y axis ticks.
- text : an object containing the following properties:
  - x: a string representing the color of the x axis text.
  - y: a string representing the color of the y axis text.
callback is a function that is run after the axis color is set but before the next render, this callback accepts an optional argument that represents the graph object from which the method is called upon.

Note: The color can be in the format "#rrggbb" or be any of the standard color names.

Return:

An object representing the current axis colors if no arguments are pass.
A reference to the graph object from which the method is called upon.

Default values:

The default values for the axis color are as follows: ("#000000" represents the color black)

{
   base : {
      x : "#000000",
      y : "#000000"
   },
   tick : {
      x : "#000000",
      y : "#000000"
   },
   text : {
      x : "#000000",
      y : "#000000"
   }
}

Opacity:

This method lets you set or get the current opacities of each axis base, ticks and text independently.

The options object has some properties that change the opacities in a generalized way, and those changes cascaded towards the more specific properties. The more specific the property is, the more priority takes.

It is only necessary to define the values that you want to change and only that values will be updated, leaving the rest as they are.

Method:

axisOpacity()
axisOpacity(options)
axisOpacity(options, callback)

Where:

options is an object that represent the opacity of each axis base, ticks and text. This object has the following properties:
- axis : a number between 0 and 1 representing the opacity of both whole axis.
- xAxis : a number between 0 and 1 representing the opacity of the whole x axis.
- yAxis : a number between 0 and 1 representing the opacity of the whole y axis.
- base : an object containing the following properties:
  - x: a number between 0 and 1 representing the opacity of the x axis base.
  - y: a number between 0 and 1 representing the opacity of the y axis base.
- tick : an object containing the following properties:
  - x: a number between 0 and 1 representing the opacity of the x axis ticks.
  - y: a number between 0 and 1 representing the opacity of the y axis ticks.
- text : an object containing the following properties:
  - x: a number between 0 and 1 representing the opacity of the x axis text.
  - y: a number between 0 and 1 representing the opacity of the y axis text.
callback is a function that is run after the axis opacity is set but before the next render, this callback accepts an optional argument that represents the graph object from which the method is called upon.

Return:

An object representing the current axis opacities if no arguments are pass.
A reference to the graph object from which the method is called upon.

Default values:

The default values for the axis opacity are as follows:

{
   base : {
      x : 1,
      y : 1
   },
   tick : {
      x : 1,
      y : 1
   },
   text : {
      x : 1,
      y : 1
   }
}

Units:

This property lets you set or get the units of each axis. The units appear on each tick at the right of the number.

It is only necessary to define the values that you want to change and only that values will be updated, leaving the rest as they are.

Method:

 axisUnits()
 axisUnits(options)
 axisUnits(options, callback)

Where:

options is an object containing the following properties:
- x : a string representig the x axis units:
- y : a string representig the y axis units:
callback is a function that is run after the axis units are set but before the next render, this callback accepts an optional argument that represents the graph object from which the method is called upon.

Returns:

An object representing the current axis units if no arguments are pass.
A reference to the graph object from which the method is called upon.

Dafault Values:

The default values for the axis units are as follow:

{
  x : "",
  y : ""
}

Base:

This metod lets you set or get the properties of each axis base.

It is only necessary to define the values that you want to change and only that values will be updated, leaving the rest as they are.

Method:

axisBase()
axisBase(options)
axisBase(options, callback)

Where:

options is an object containing the following properties:
- x : an object containing the following properties:
  - color : a string representing the x axis base color.
  - opacity : a number between 0 and 1 representing the x axis base opacity.
  - width : an integer positive number representing the line width of the x axis base.
- y : an object containing the following properties:
  - color : a string representing the y axis base color.
  - opacity : a number between 0 and 1 representing the y axis base opacity.
  - width : an integer positive number representing the line width of the y axis base.
callback is a function that is run after the properties of the axis base are set but before the next render, this callback accepts an optional argument that represents the graph object from which the method is called upon.

Note: The color can be in the format "#rrggbb" or be any of the standard color names.

Returns:

An object representing the current properties of the axis base if no arguments are pass.
A reference to the graph object from which the method is called upon.

Default Values:

The default values of the properties of the axis base are as follow: ("#000000" represents the color black)

{
  x : {
    color : "#000000",
    opacity : 1,
    width : 1
  },
  y : {
    color : "#000000",
    opacity : 1,
    width : 1
  },
}

Ticks:

This method lets you set or get the properties of each axis ticks.

It is only necessary to define the values that you want to change and only that values will be updated, leaving the rest as they are.

Method:

axisTicks()
axisTicks(options)
axisTicks(options, callback)

Where:

options : is an object with the followin properties:
- x : an object with the following properties:
  - color : a string representing the color of the x axis ticks.
  - opacity : a number between 0 and 1 representing the opacity of the x axis ticks.
  - width : a positive integer representing the line width of the x axis ticks.
  - size : a number representing the size in pixels of the x axis ticks.
  - ticks: this property controls how many ticks will be displayed, the value can be one of the following options:
    - The string "auto" to let the graph object decide where to put the ticks.
    - A number representing the amount of ticks in the axis. The ticks will be equally spaced and will contain the start and end of the axis.
    - An array of numbers representing the location of the ticks to be displayed.
  - minSpacing: If the ticks property is set to "auto" controls the minimum space in pixels that the ticks can have between them, otherwise it has no effect.
- y : an object with the following properties:
  - color : a string representing the color of the y axis ticks.
  - opacity : a number between 0 and 1 representing the opacity of the y axis ticks.
  - width : a positive integer representing the line width of the y axis ticks.
  - size : a number representing the size in pixels of the y axis ticks.
  - ticks: this property controls how many ticks will be displayed, the value can be one of the following options:
    - The string "auto" to let the graph object decide where to put the ticks.
    - A number representing the amount of ticks in the axis. The ticks will be equally spaced and will contain the start and end of the axis.
    - An array of numbers representing the location of the ticks to be displayed.
  - minSpacing: If the ticks property is set to "auto" controls the minimum space in pixels that the ticks can have between them, otherwise it has no effect.
callback is a function that is run after the properties of the axis ticks are set but before the next render, this callback accepts an optional argument that represents the graph object from which the method is called upon.

Note: The color can be in the format "#rrggbb" or be any of the standard color names.

Note: If the axis position is set to center the tick size will be double of the size property. This is because in that position, the tick runs on both sides of the axis base.

Returns:

An object representing the current properties of the axis ticks if no arguments are pass.
A reference to the graph object from which the method is called upon.

Default Values:

The default values for the properties of the axis ticks are: ("#000000" represents the color black)

{
  x : {
    color : "#000000",
    opacity : 1,
    width : 1,
    size : 5,
    ticks : "auto",
    minSpacing : 45
  },
  y : {
    color : "#000000",
    opacity : 1,
    width : 1,
    size : 5,
    ticks : "auto",
    minSpacing : 45
  },
}

Text:

This method lets you set or get the text properties of each axis.

It is only necessary to define the values that you want to change and only that values will be updated, leaving the rest as they are.

Method:

axisText()
axisText(options)
axisText(options, callback)

Where:

options: is an object containing the following properties
- x: and object with the following properties:
  - color: a string representing the color of the text in the x axis.
  - opacity: a number between 0 and 1 representing the opacity of the text in the x axis.
  - font: a string representing the font of the text in the x axis.
  - size: a string representing the size of the text in the x axis.
  - specifier: a string representing the font specifier of the text in the x axis.
- y: and object with the following properties:
  - color: a string representing the color of the text in the y axis.
  - opacity: a number between 0 and 1 representing the opacity of the text in the y axis.
  - font: a string representing the font of the text in the y axis.
  - size: a string representing the size of the text in the y axis.
  - specifier: a string representing the font specifier of the text in the y axis.
callback is a function that is run after the properties of the axis text are set but before the next render, this callback accepts an optional argument that represents the graph object from which the method is called upon.

Note: The color can be in the format "#rrggbb" or be any of the standard color names.

Note: The font value can be any font or stack of fonts available in the browser. Its advised to use safe web fonts.

Note: The size value can be any valid css size including em, rem, etc.

Note: The specifier can be any combination of the following css font properties.

font-style.

font-variant.

font-weight.

font-stretch.

line-height.

Some fonts may not support all specifier options.

Returns:

An object representing the current properties of the axis text if no arguments are pass.
A reference to the graph object from which the method is called upon.

Defaul values: The defaul values for the properties of the axis text are as follows: ("#000000" represents the color black)

{
  x : {
    color : "#000000",
    opacity : 1,
    font : "Arial, Helvetica Neue, Helvetica, sans-serif",
    size : "10px",
    specifier : ""
  },
  y : {
    color : "#000000",
    opacity : 1,
    font : "Arial, Helvetica Neue, Helvetica, sans-serif",
    size : "10px",
    specifier : ""
  }
}

Dynamic

This method lets you set or get the dynamic properties of each axis.

This method only is relevant if the axis position is set to center. In this position, the axis text is located below the x axis and at the left of the y axis, and the two axis intersects at the coordinate (0,0).

When that coordinate is no longer inside the graph area, the axis shift to remain visible and the text change positions relative to the axis base.

Those two are the behaviors that this method can change.

For example, in the next illustration, the axis shift when the start value of the y axis domain is bigger than zero.

It is only necessary to define the values that you want to change and only that values will be updated, leaving the rest as they are.

Method:

axisDynamic()
axisDynamic(dynamic)
axisDynamic(dynamic, callback)

Where:

dynamic is an object containing the following properties:
- x: and object with the following properties:
  - dynamic: a boolean that determines whether the x axis text changes position relative to the base.
  - contained: a boolean that determines whether the x axis shifts to remain visible.
- y: and object with the following properties:
  - dynamic: a boolean that determines whether the y axis text changes position relative to the base.
  - contained: a boolean that determines whether the y axis shifts to remain visible.
callback is a function that is run after the properties of the axis dynamics are set but before the next render, this callback accepts an optional argument that represents the graph object from which the method is called upon.

Returns:

An object representing the current properties of the axis dynamics if no arguments are pass.
A reference to the graph object from which the method is called upon.

Dafault values:

The default values for the properties of the axis dynamics are:

{
  x : {
    dynamic : true,
    contained : true
  },
  y : {
    dynamic : true,
    contained : true
  }
}

Overlap

This method lets you set or get the overlap properties of each axis.

This method only is relevant if the axis position is set to center. In this position, the axis text may overlap with each other or with the axis itself.

To enhance visibility, a little area around each text is clear, so neither the base nor ticks will render on top of the text.

This method lets you modify that behavior.

It is only necessary to define the values that you want to change and only that values will be updated, leaving the rest as they are.

Method:

axisOverlap()
axisOverlap(overlap)
axisOverlap(overlap, callback)

Where:

overlap is an object cotaining the following properties:
- priority: a string with the values "x" or "y".
- x: a boolean representing whether a small area arround the text of the x axis should be cleared.
- y: a boolean representing whether a small area arround the text of the y axis should be cleared.
callback is a function that is run after the properties of the axis overlap are set but before the next render, this callback accepts an optional argument that represents the graph object from which the method is called upon.

Note: In the case that the text of one axis overlaps with the text of the other, the one render on top will be determined by the value of the priority property.

Returns:

An object representing the current properties of the axis overlap if no arguments are pass.
A reference to the graph object from which the method is called upon.

Dafault values:

The default values for the properties of the axis overlap are:

{
  priority : "x",
  x : true,
  y : true
}

Secondary Enable:

This method lets you enable the secondary set of axis.

Each graph have the capability of defining two sets of axis, the primary x and y axis are always defined while the secondary x and y can be defined independently.

The properties of the secondary axis can be manipulated in the same way the primaries can, but the axis must be defined first and the axis position must NOT be center.

Each dataset can decide what pair of axis use.

It is only necessary to define the values that you want to change and only that values will be updated, leaving the rest as they are.

Note: center positioned axis cannot have secondary axis defined.

Method:

secondaryAxisEnable()
secondaryAxisEnable(options)
secondaryAxisEnable(options, callback)

Where:

options is an object containing the following properties:
- x: a boolean that determines whether the secondary x axis must be enable.
- y: a boolean that determines whether the secondary y axis must be enable.
callback is a function that is run after the properties of the secondary axis enable are set but before the next render, this callback accepts an optional argument that represents the graph object from which the method is called upon.

Note: The secondary axis will not be enabled if the axis position is set to center.

Returns:

An object representing the current properties of the secondary axis enable if no arguments are pass.
A reference to the graph object from which the method is called upon.

Default Values:

The default values of the secondary axis enable are as follows:

{
  x : false,
  y : false
}

Seocndary Domain:

This method lets you set or get the properties of the secondary axis domain.

It is only necessary to define the values that you want to change and only that values will be updated, leaving the rest as they are.

Method:

secondaryAxisDomain()
secondaryAxisDomain(options)
secondaryAxisDomain(options, callback)

Where:

options is an object representing the axis domain, this object has the properties:
- x : An object containing the properties start and end.
  - The property start is the value at the left most side of the x axis.
  - The property end is the value at the right most side of the x axis.
- y : An object containing the properties start and end.
  - The property start is the value at the bottom of the y axis.
  - The property end is the value at the top of the y axis.
callback is a function that is run after the axis domain is set but before the next render, this callback accepts an optional argument that represents the graph object from which the method is called upon.

Why the end value of the y axis is at the top and not the bottom? : Because of the convention of having the vertical axis values increase from bottom to top, this is a convention to follow for other similar properties.

On that note, it is not necessary to have the start value be smaller than the end value. In that case, the axis "direction" will be reverted.

Note: To change any secondary axis property, the corresponding axis must be enabled first.

Warning: If any of the axis is not defined yet, the correspondign property will return the value undefined.

Returns:

An object representing the current secondary axis domain if no arguments are pass.
A reference to the graph object from which the method is called upon.

Default values:

The default values for the secondary axis domain are as follows:

{
   x : {
      start : -5,
      end : 5
   },
   y : {
      start : -5,
      end : 5
   }
}

Secondary Color:

This method lets you set or get the current colors of each secondary axis base, ticks and text independently.

The options object has some properties that change the colors in a generalized way, and those changes cascaded towards the more specific properties. The more specific the property is, the more priority takes.

It is only necessary to define the values that you want to change and only that values will be updated, leaving the rest as they are.

Method:

secondaryAxisColor()
secondaryAxisColor(options)
secondaryAxisColor(options, callback)

Where:

options is an object that represent the color of each axis base, ticks and text. This object has the following properties:
- axis : a string representing the color of both whole axis.
- xAxis : a string representing the color of the whole x axis.
- yAxis : a string representing the color of the whole y axis.
- base : an object containing the following properties:
  - x: a string representing the color of the x axis base.
  - y: a string representing the color of the y axis base.
- tick : an object containing the following properties:
  - x: a string representing the color of the x axis ticks.
  - y: a string representing the color of the y axis ticks.
- text : an object containing the following properties:
  - x: a string representing the color of the x axis text.
  - y: a string representing the color of the y axis text.
callback is a function that is run after the axis color is set but before the next render, this callback accepts an optional argument that represents the graph object from which the method is called upon.

Note: The color can be in the format "#rrggbb" or be any of the standard color names.

Note: To change any secondary axis property, the corresponding axis must be enabled first.

Warning: If any of the axis is not defined yet, the correspondign property will return the value undefined.

Return:

An object representing the current secondary axis colors if no arguments are pass.
A reference to the graph object from which the method is called upon.

Default values:

The default values for the secondary axis color are as follows: ("#000000" represents the color black)

{
   base : {
      x : "#000000",
      y : "#000000"
   },
   tick : {
      x : "#000000",
      y : "#000000"
   },
   text : {
      x : "#000000",
      y : "#000000"
   }
}

Secondary Opacity:

This method lets you set or get the current opacities of each secondary axis base, ticks and text independently.

The options object has some properties that change the opacities in a generalized way, and those changes cascaded towards the more specific properties. The more specific the property is, the more priority takes.

It is only necessary to define the values that you want to change and only that values will be updated, leaving the rest as they are.

Method:

secondaryAxisOpacity()
secondaryAxisOpacity(options)
secondaryAxisOpacity(options, callback)

Where:

options is an object that represent the opacity of each axis base, ticks and text. This object has the following properties:
- axis : a number between 0 and 1 representing the opacity of both whole axis.
- xAxis : a number between 0 and 1 representing the opacity of the whole x axis.
- yAxis : a number between 0 and 1 representing the opacity of the whole y axis.
- base : an object containing the following properties:
  - x: a number between 0 and 1 representing the opacity of the x axis base.
  - y: a number between 0 and 1 representing the opacity of the y axis base.
- tick : an object containing the following properties:
  - x: a number between 0 and 1 representing the opacity of the x axis ticks.
  - y: a number between 0 and 1 representing the opacity of the y axis ticks.
- text : an object containing the following properties:
  - x: a number between 0 and 1 representing the opacity of the x axis text.
  - y: a number between 0 and 1 representing the opacity of the y axis text.
callback is a function that is run after the axis opacity is set but before the next render, this callback accepts an optional argument that represents the graph object from which the method is called upon.

Note: To change any secondary axis property, the corresponding axis must be enabled first.

Warning: If any of the axis is not defined yet, the correspondign property will return the value undefined.

Return:

An object representing the current secondary axis opacities if no arguments are pass.
A reference to the graph object from which the method is called upon.

Default values:

The default values for the secondary axis opacity are as follows:

{
   base : {
      x : 1,
      y : 1
   },
   tick : {
      x : 1,
      y : 1
   },
   text : {
      x : 1,
      y : 1
   }
}

Secondary Units:

This property lets you set or get the units of each secondary axis. The units appear on each tick at the right of the number.

It is only necessary to define the values that you want to change and only that values will be updated, leaving the rest as they are.

Method:

 secondaryAxisUnits()
 secondaryAxisUnits(options)
 secondaryAxisUnits(options, callback)

Where:

options is an object containing the following properties:
- x : a string representig the x axis units:
- y : a string representig the y axis units:
callback is a function that is run after the axis units are set but before the next render, this callback accepts an optional argument that represents the graph object from which the method is called upon.

Note: To change any secondary axis property, the corresponding axis must be enabled first.

Warning: If any of the axis is not defined yet, the correspondign property will return the value undefined.

Returns:

An object representing the current secondary axis units if no arguments are pass.
A reference to the graph object from which the method is called upon.

Dafault Values:

The default values for the secondary axis units are as follow:

{
  x : "",
  y : ""
}

Secondary Base:

This metod lets you set or get the properties of each secondary axis base.

It is only necessary to define the values that you want to change and only that values will be updated, leaving the rest as they are.

Method:

secondaryAxisBase()
secondaryAxisBase(options)
secondaryAxisBase(options, callback)

Where:

options is an object containing the following properties:
- x : an object containing the following properties:
  - color : a string representing the x axis base color.
  - opacity : a number between 0 and 1 representing the x axis base opacity.
  - width : an integer positive number representing the line width of the x axis base.
- y : an object containing the following properties:
  - color : a string representing the y axis base color.
  - opacity : a number between 0 and 1 representing the y axis base opacity.
  - width : an integer positive number representing the line width of the y axis base.
callback is a function that is run after the properties of the axis base are set but before the next render, this callback accepts an optional argument that represents the graph object from which the method is called upon.

Note: The color can be in the format "#rrggbb" or be any of the standard color names.

Note: To change any secondary axis property, the corresponding axis must be enabled first.

Warning: If any of the axis is not defined yet, the correspondign property will return the value undefined.

Returns:

An object representing the current properties of the secondary axis base if no arguments are pass.
A reference to the graph object from which the method is called upon.

Default Values:

The default values of the properties of the secondary axis base are as follow: ("#000000" represents the color black)

{
  x : {
    color : "#000000",
    opacity : 1,
    width : 1
  },
  y : {
    color : "#000000",
    opacity : 1,
    width : 1
  },
}

Secondary Ticks:

This method lets you set or get the properties of each secondary axis ticks.

It is only necessary to define the values that you want to change and only that values will be updated, leaving the rest as they are.

Method:

secondaryAxisTicks()
secondaryAxisTicks(options)
secondaryAxisTicks(options, callback)

Where:

options : is an object with the followin properties:
- x : an object with the following properties:
  - color : a string representing the color of the x axis ticks.
  - opacity : a number between 0 and 1 representing the opacity of the x axis ticks.
  - width : a positive integer representing the line width of the x axis ticks.
  - size : a number representing the size in pixels of the x axis ticks.
  - ticks: this property controls how many ticks will be displayed, the value can be one of the following options:
    - The string "auto" to let the graph object decide where to put the ticks.
    - A number representing the amount of ticks in the axis. The ticks will be equally spaced and will contain the start and end of the axis.
    - An array of numbers representing the location of the ticks to be displayed.
  - minSpacing: If the ticks property is set to "auto" controls the minimum space in pixels that the ticks can have between them, otherwise it has no effect.
- y : an object with the following properties:
  - color : a string representing the color of the y axis ticks.
  - opacity : a number between 0 and 1 representing the opacity of the y axis ticks.
  - width : a positive integer representing the line width of the y axis ticks.
  - size : a number representing the size in pixels of the y axis ticks.
  - ticks: this property controls how many ticks will be displayed, the value can be one of the following options:
    - The string "auto" to let the graph object decide where to put the ticks.
    - A number representing the amount of ticks in the axis. The ticks will be equally spaced and will contain the start and end of the axis.
    - An array of numbers representing the location of the ticks to be displayed.
  - minSpacing: If the ticks property is set to "auto" controls the minimum space in pixels that the ticks can have between them, otherwise it has no effect.
callback is a function that is run after the properties of the axis ticks are set but before the next render, this callback accepts an optional argument that represents the graph object from which the method is called upon.

Note: The color can be in the format "#rrggbb" or be any of the standard color names.

Note: To change any secondary axis property, the corresponding axis must be enabled first.

Warning: If any of the axis is not defined yet, the correspondign property will return the value undefined.

Returns:

An object representing the current properties of the secondary axis ticks if no arguments are pass.
A reference to the graph object from which the method is called upon.

Default Values:

The default values for the properties of the secondary axis ticks are: ("#000000" represents the color black)

{
  x : {
    color : "#000000",
    opacity : 1,
    width : 1,
    size : 5,
    ticks : "auto",
    minSpacing : 45
  },
  y : {
    color : "#000000",
    opacity : 1,
    width : 1,
    size : 5,
    ticks : "auto",
    minSpacing : 45
  },
}

Secondary Text:

This method lets you set or get the text properties of each secondary axis.

It is only necessary to define the values that you want to change and only that values will be updated, leaving the rest as they are.

Method:

secondaryAxisText()
secondaryAxisText(options)
secondaryAxisText(options, callback)

Where:

options: is an object containing the following properties
- x: and object with the following properties:
  - color: a string representing the color of the text in the x axis.
  - opacity: a number between 0 and 1 representing the opacity of the text in the x axis.
  - font: a string representing the font of the text in the x axis.
  - size: a string representing the size of the text in the x axis.
  - specifier: a string representing the font specifier of the text in the x axis.
- y: and object with the following properties:
  - color: a string representing the color of the text in the y axis.
  - opacity: a number between 0 and 1 representing the opacity of the text in the y axis.
  - font: a string representing the font of the text in the y axis.
  - size: a string representing the size of the text in the y axis.
  - specifier: a string representing the font specifier of the text in the y axis.
callback is a function that is run after the properties of the axis ticks are set but before the next render, this callback accepts an optional argument that represents the graph object from which the method is called upon.

Note: The color can be in the format "#rrggbb" or be any of the standard color names.

Note: The font value can be any font or stack of fonts available in the browser. Its advised to use safe web fonts.

Note: The size value can be any valid css size including em, rem, etc.

Note: To change any secondary axis property, the corresponding axis must be enabled first.

Warning: If any of the axis is not defined yet, the correspondign property will return the value undefined.

Note: The specifier can be any combination of the following css font properties.

font-style.

font-variant.

font-weight.

font-stretch.

line-height.

Some fonts may not support all specifier options.

Returns:

An object representing the current properties of the secondary axis text if no arguments are pass.
A reference to the graph object from which the method is called upon.

Defaul values: The defaul values for the properties of the secondary axis text are as follows: ("#000000" represents the color black)

{
  x : {
    color : "#000000",
    opacity : 1,
    font : "Arial, Helvetica Neue, Helvetica, sans-serif",
    size : "10px",
    specifier : ""
  },
  y : {
    color : "#000000",
    opacity : 1,
    font : "Arial, Helvetica Neue, Helvetica, sans-serif",
    size : "10px",
    specifier : ""
  }
}

Secondary Type:

This method let you set or get the properties of each secondary axis type.

It is only necessary to define the values that you want to change and only that values will be updated, leaving the rest as they are.

Method:

secondaryAxisType()
secondaryAxisType(opions)
secondaryAxisType(opions, callback)

Where:

options is an object containing the following properties:
- x : a string with the value "rectangular" or "log" representing the type of the secondary axis x.
- y : a string with the value "rectangular" or "log" representing the type of the secondary axis y.
callback is a function that is run after the properties of the axis type are set but before the next render, this callback accepts an optional argument that represents the graph object from which the method is called upon.

Warning: An axis cannot have a logarithmic scale set unless its domain is strictly positive or negative, in other words the axis domain must contain only positive values or only negative values not include zero.

Note: To change any secondary axis property, the corresponding axis must be enabled first.

Warning: If any of the axis is not defined yet, the correspondign property will return the value undefined.

Returns:

An object representing the current properties of the secondary axis type if no arguments are pass.
A reference to the graph object from which the method is called upon.

Default Values:

The defaul values for the properties of the secondary axis type are as follows:

{
  x : "rectangular",
  y : "rectangular"
}

Grid

The graph can define the use of grids to improve the data reading. There are two types of grids:

Primary: The primary grid runs along the axis ticks.
Secondary: The secondary grid runs in between the axis ticks.

Each grid have an x and y component, and runs perpendicular to its corresponding axis.

For example, the x component of the primary grid is composed of parallel vertical lines extending the x axis ticks.

Note: If the axis type is set to polar the grid behavior changes.

In the case that the axis position is set to polar, then the behavior of the grids are as follows:

Primary:
- The x component of the primary grid is composed of concentric circles around the origin with radii equal to each tick in the x direction.
- The y component of the primary grid is composed of rays coming out of the origin with equal angle variation.
Secondary:
- The x component of the secondary grid is composed of concentric circles arround the origin with raii equal to values in between the ticks in the x direction.
- The y component of the secondary grid is composed of rays coming out of the origin, with equal angle variation in between each ray of the y component of the primary grid.

The x component of the grids is meant to improve the reading of the radial component of the data, while the y component improves the reading of the angle data.

Color:

This method let you set or get the color properties of each grid.

The options object has some properties that change the colors in a generalized way, and those changes cascaded towards the more specific properties. The more specific the property is, the more priority takes.

It is only necessary to define the values that you want to change and only that values will be updated, leaving the rest as they are.

Method:

gridColor()
gridColor(options)
gridColor(options, callback)

Where:

options is an object containing the following properties:
- grid: a string representing the color of both whole grids.
- primary: a string representing the color of the whole primary grid.
- secondary: a string representing the color of the whole secondary grid.
- x: an object with the following properties:
  - primary: a string representing the color of the x component of the primary grid.
  - secondary: a string representing the color of the x component of the secondary grid.
- y: an object with the following properties:
  - primary: a string representing the color of the y component of the primary grid.
  - secondary: a string representing the color of the y component of the secondary grid.
callback is a function that is run after the color properties of the grids are set but before the next render, this callback accepts an optional argument that represents the graph object from which the method is called upon.

Note: The color can be in the format "#rrggbb" or be any of the standard color names.

Returns:

An object representing the current color properties of the grids if no arguments are pass.
A reference to the graph object from which the method is called upon.

Default Values:

The defaul values for the color properties of the grids are as follows: ("#000000" represents the color black)

{
  x : {
    primary : "#000000",
    secondary : "#000000",
  },
  y : {
    primary : "#000000",
    secondary : "#000000",
  }
}

Opacity:

This method let you set or get the opacity properties of each grid.

The options object has some properties that change the opacities in a generalized way, and those changes cascaded towards the more specific properties. The more specific the property is, the more priority takes.

It is only necessary to define the values that you want to change and only that values will be updated, leaving the rest as they are.

Method:

gridOpacity()
gridOpacity(options)
gridOpacity(options, callback)

Where:

options is an object containing the following properties:
- grid: a number representing the opacity of both whole grids.
- primary: a number representing the opacity of the whole primary grid.
- secondary: a number representing the opacity of the whole secondary grid.
- x: an object with the following properties:
  - primary: a number representing the opacity of the x component of the primary grid.
  - secondary: a number representing the opacity of the x component of the secondary grid.
- y: an object with the following properties:
  - primary: a number representing the opacity of the y component of the primary grid.
  - secondary: a number representing the opacity of the y component of the secondary grid.
callback is a function that is run after the opacity properties of the grids are set but before the next render, this callback accepts an optional argument that represents the graph object from which the method is called upon.

Note: The value of the opacity must be a number between 0 and 1.

Returns:

An object representing the current opacity properties of the grids if no arguments are pass.
A reference to the graph object from which the method is called upon.

Default Values:

The defaul values for the color properties of the grids are as follows:

{
  x : {
    primary : 0.2,
    secondary : 0.1,
  },
  y : {
    primary : 0.2,
    secondary : 0.1,
  }
}

Style:

This method let you set or get the style properties of each grid.

The options object has some properties that change the styles in a generalized way, and those changes cascaded towards the more specific properties. The more specific the property is, the more priority takes.

It is only necessary to define the values that you want to change and only that values will be updated, leaving the rest as they are.

Method:

gridStyle()
gridStyle(options)
gridStyle(options, callback)

Where:

options is an object containing the following properties:
- grid: a string representing the style of both whole grids.
- primary: a string representing the style of the whole primary grid.
- secondary: a string representing the style of the whole secondary grid.
- x: an object with the following properties:
  - primary: a string representing the style of the x component of the primary grid.
  - secondary: a string representing the style of the x component of the secondary grid.
- y: an object with the following properties:
  - primary: a string representing the style of the y component of the primary grid.
  - secondary: a string representing the style of the y component of the secondary grid.
callback is a function that is run after the style properties of the grids are set but before the next render, this callback accepts an optional argument that represents the graph object from which the method is called upon.

The style can be represented with one of the following options:

Style	Result
`"solid"`
`"dot"`
`"dash"`
`"long-dash"`
`"dash-dot"`
`"dash-2dot"`

Also, the string can be a list of space separated integers representing line and space length in pixel to form a custom pattern.

For example, the string "3 2 10 2 3" forms a pattern of 3 pixels line, 2 pixels space, 10 pixels line, etc.

Returns:

An object representing the current style properties of the grids if no arguments are pass.
A reference to the graph object from which the method is called upon.

Default Values:

The defaul values for the style properties of the grids are as follows:

{
  x : {
    primary : "solid",
    secondary : "dot",
  },
  y : {
    primary : "solid",
    secondary : "dot",
  }
}

Width:

This method let you set or get the width properties of each grid.

The options object has some properties that change the widths in a generalized way, and those changes cascaded towards the more specific properties. The more specific the property is, the more priority takes.

It is only necessary to define the values that you want to change and only that values will be updated, leaving the rest as they are.

Method:

gridWidth()
gridWidth(options)
gridWidth(options, callback)

Where:

options is an object containing the following properties:
- grid: a number representing the width of both whole grids.
- primary: a number representing the width of the whole primary grid.
- secondary: a number representing the width of the whole secondary grid.
- x: an object with the following properties:
  - primary: a number representing the width of the x component of the primary grid.
  - secondary: a number representing the width of the x component of the secondary grid.
- y: an object with the following properties:
  - primary: a number representing the width of the y component of the primary grid.
  - secondary: a number representing the width of the y component of the secondary grid.
callback is a function that is run after the width properties of the grids are set but before the next render, this callback accepts an optional argument that represents the graph object from which the method is called upon.

Note: The value of the width must be a positive integer.

Returns:

An object representing the current width properties of the grids if no arguments are pass.
A reference to the graph object from which the method is called upon.

Default Values:

The defaul values for the width properties of the grids are as follows:

{
  x : {
    primary : 1,
    secondary : 1,
  },
  y : {
    primary : 1,
    secondary : 1,
  }
}

Primary:

This method lets you set or get all properties of the primary grid.

It is only necessary to define the values that you want to change and only that values will be updated, leaving the rest as they are.

Method:

primaryGrid()
primaryGrid(options)
primaryGrid(options, callback)

Where:

options is an object with the following properties:
- grid: an object with the properties:
  - enable: a boolean that determines whether the whole gid should be enabled.
  - color: a string representing the color of the whole grid.
  - opacity: a number representing the opacity of the whole grid.
  - width: a number representing the line width of the whole grid.
  - style: a string representing the line style of the whole grid.
- x: an object with the properties:
  - enable: a boolean that determines whether the grid x component should be enabled.
  - color: a string representing the color of the grid x component.
  - opacity: a number representing the opacity of the grid x component.
  - width: a number representing the line width of the grid x component.
  - style: a string representing the line style of the grid x component.
- y: an object with the properties:
  - enable: a boolean that determines whether the grid y component should be enabled.
  - color: a string representing the color of the grid y component.
  - opacity: a number representing the opacity of the grid y component.
  - width: a number representing the line width of the grid y component.
  - style: a string representing the line style of the grid y component.
callback is a function that is run after the grid properties are set but before the next render, this callback accepts an optional argument that represents the graph object from which the method is called upon.

Note: The color can be in the format "#rrggbb" or be any of the standard color names.

Note: The value of the opacity must be a number between 0 and 1.

Note: The value of the width must be a positive integer.

The style can be represented with one of the following options:

Style	Result
`"solid"`
`"dot"`
`"dash"`
`"long-dash"`
`"dash-dot"`
`"dash-2dot"`

Also, the string can be a list of space separated integers representing line and space length in pixel to form a custom pattern.

For example, the string "3 2 10 2 3" forms a pattern of 3 pixels line, 2 pixels space, 10 pixels line, etc.

Returns:

An object representing the current properties of the primary grid if no arguments are pass.
A reference to the graph object from which the method is called upon.

Defaul Values:

The defaul values for the properties of the primary grid are as follows: ("#000000" represents the color black)

{
  x : {
    enable : true,
    color : "#000000",
    opacity : 0.2,
    width : 1,
    style : "solid"
  },
  y : {
    enable : true,
    color : "#000000",
    opacity : 0.2,
    width : 1,
    style : "solid"
  }
}

Secondary:

This method lets you set or get all properties of the secondary grid.

It is only necessary to define the values that you want to change and only that values will be updated, leaving the rest as they are.

Method:

secondaryGrid()
secondaryGrid(options)
secondaryGrid(options, callback)

Where:

options is an object with the following properties:
- grid: an object with the properties:
  - enable: a boolean that determines whether the whole gid should be enabled.
  - color: a string representing the color of the whole grid.
  - opacity: a number representing the opacity of the whole grid.
  - width: a number representing the line width of the whole grid.
  - style: a string representing the line style of the whole grid.
  - density: this property controls how many parts each tick is subdivided into, it can have one of these values:
    - The string "auto" to compute the optimal number of divisions automatically.
    - A number representing how many divisions to make on each tick.
  - minSpacing: a number that represent the minimum length in pixels that a subdivision can have. This property is only relevant when the density value is set to "auto".
  - maxDensity: a number that represents the maximum number of subdivision that a tick can have. This property is only relevant when the density value is set to "auto".
- x: an object with the properties:
  - enable: a boolean that determines whether the grid x component should be enabled.
  - color: a string representing the color of the grid x component.
  - opacity: a number representing the opacity of the grid x component.
  - width: a number representing the line width of the grid x component.
  - style: a string representing the line style of the grid x component.
  - density: this property controls how many parts each tick is subdivided into, it can have one of these values:
    - The string "auto" to compute the optimal number of divisions automatically.
    - A number representing how many divisions to make on each tick.
  - minSpacing: a number that represent the minimum length in pixels that a subdivision can have. This property is only relevant when the density value is set to "auto".
  - maxDensity: a number that represents the maximum number of subdivision that a tick can have. This property is only relevant when the density value is set to "auto".
- y: an object with the properties:
  - enable: a boolean that determines whether the grid y component should be enabled.
  - color: a string representing the color of the grid y component.
  - opacity: a number representing the opacity of the grid y component.
  - width: a number representing the line width of the grid y component.
  - style: a string representing the line style of the grid y component.
  - density: this property controls how many parts each tick is subdivided into, it can have one of these values:
    - The string "auto" to compute the optimal number of divisions automatically.
    - A number representing how many divisions to make on each tick.
  - minSpacing: a number that represent the minimum length in pixels that a subdivision can have. This property is only relevant when the density value is set to "auto".
  - maxDensity: a number that represents the maximum number of subdivision that a tick can have. This property is only relevant when the density value is set to "auto".
callback is a function that is run after the grid properties are set but before the next render, this callback accepts an optional argument that represents the graph object from which the method is called upon.

Note: The color can be in the format "#rrggbb" or be any of the standard color names.

Note: The value of the opacity must be a number between 0 and 1.

Note: The value of the width must be a positive integer.

Note: The properties minSpacing and maxDensity are only relevant when the density property is set to "auto", and its values must be a positive integer.

Note: The values of the property density, if not set to "auto", must be a positive integer.

If the graph is using polar as the axis type, the value of density represents the amount of subdivision of the angle grid, in this case if is set to "auto" there will be always four subdivisions.

The style can be represented with one of the following options:

Style	Result
`"solid"`
`"dot"`
`"dash"`
`"long-dash"`
`"dash-dot"`
`"dash-2dot"`

Also, the string can be a list of space separated integers representing line and space length in pixel to form a custom pattern.

For example, the string "3 2 10 2 3" forms a pattern of 3 pixels line, 2 pixels space, 10 pixels line, etc.

Returns:

An object representing the current properties of the secondary grid if no arguments are pass.
A reference to the graph object from which the method is called upon.

Defaul Values:

The defaul values for the properties of the secondary grid are as follows: ("#000000" represents the color black)

{
  x : {
    enable : true,
    color : "#000000",
    opacity : 0.1,
    width : 1,
    style : "dot",
    density : "auto",
    minSpacing : 20,
    maxDensity : 5
  },
  y : {
    enable : true,
    color : "#000000",
    opacity : 0.1,
    width : 1,
    style : "dot",
    density : "auto",
    minSpacing : 20,
    maxDensity : 5
  }
}

Polar:

This method lets you set or get the amount of divisions in the main grid if the axis type is set to center.

This only affects the y component of the primary grid. The angle divisions always start from the x axis.

Method:

polarGrid()
polarGrid(option)
polarGrid(option, callback)

Where:

option is a number representing the number of main divisions in the angle grid if no arguments are pass.
callback is a function that is run after the grid polar property is set but before the next render, this callback accepts an optional argument that represents the graph object from which the method is called upon.

Note: option must be a positive integer, this property is only relevant when the axis type is set to polar.

Returns:

A number representing the number of main divisions in the angle grid if no arguments are pass.
A reference to the graph object from which the method is called upon.

Default Value:

The defaul values for this property is: 16.

Labels

Currently, the available labels are:

Title: Located at the top of the graph.
Subtitle: Located below the Title.
x Label: Located beside the x axis.
y Label: Located beside the y axis.
Secondary x Label: Located beside the x secondary axis.
Secondary y Label: Located beside the y secondary axis.

The Title and Subtitle can be set at any time, while the x Label and y Label can be set only when the axis position is NOT set to center.

The secondary labels will render only if the corresponding axis is enabled.

The graph client area will change to acomodate the labels.

Title:

This method lets you set or get the properties of the title.

It is only necessary to define the values that you want to change and only that values will be updated, leaving the rest as they are.

Method:

title()
title(options)
title(options, callback)

Where:

options is an object containing the following properties:
- enable: a boolean that determines whether the title must be enabled.
- text: a string representing the text to show as a title.
- font: a string representing the font of the title.
- size: a string representing the size of the title.
- specifier: a string representing the font specifier of the title.
- color: a string representing the color of the title.
- opacity: a number between 0 and 1 representing the opacity of the title.
- filled: a boolean that determines whether the text must be filled or just outlined.
- position: this property controls the relative position of the title, can be one of the following values:
  - "start".
  - "center".
  - "end".
callback is a function that is run after the title properties are set but before the next render, this callback accepts an optional argument that represents the graph object from which the method is called upon.

Note: The color can be in the format "#rrggbb" or be any of the standard color names.

Note: The font value can be any font or stack of fonts available in the browser. Its advised to use safe web fonts.

Note: The size value can be any valid css size including em, rem, etc.

Note: The specifier can be any combination of the following css font properties.

font-style.

font-variant.

font-weight.

font-stretch.

line-height.

Some fonts may not support all specifier options.

Returns:

undefined if the title is not defined yet and no arguments are pass.
An object representing the properties of the title if no arguments are pass.
A reference to the graph object from which the method is called upon.

Default Values:

The default values for the properties of the title are as follows: ("#000000" represents the color black)

{
  enable : true,
  text : "",
  font : "Perpetua, Baskerville, Big Caslon, Palatino Linotype, Palatino, serif",
  size : "25px",
  specifier : "",
  color : "#000000",
  opacity : 1,
  filled : true,
  position : "start"
}

Subtitle:

This method lets you set or get the properties of the subtitle.

It is only necessary to define the values that you want to change and only that values will be updated, leaving the rest as they are.

Method:

subtitle()
subtitle(options)
subtitle(options, callback)

Where:

options is an object containing the following properties:
- enable: a boolean that determines whether the subtitle must be enabled.
- text: a string representing the text to show as a subtitle.
- font: a string representing the font of the subtitle.
- size: a string representing the size of the subtitle.
- specifier: a string representing the font specifier of the subtitle.
- color: a string representing the color of the subtitle.
- opacity: a number between 0 and 1 representing the opacity of the subtitle.
- filled: a boolean that determines whether the text must be filled or just outlined.
- position: this property controls the relative position of the subtitle, can be one of the following values:
  - "start".
  - "center".
  - "end".
callback is a function that is run after the subtitle properties are set but before the next render, this callback accepts an optional argument that represents the graph object from which the method is called upon.

Note: The color can be in the format "#rrggbb" or be any of the standard color names.

Note: The font value can be any font or stack of fonts available in the browser. Its advised to use safe web fonts.

Note: The size value can be any valid css size including em, rem, etc.

Note: The specifier can be any combination of the following css font properties.

font-style.

font-variant.

font-weight.

font-stretch.

line-height.

Some fonts may not support all specifier options.

Returns:

undefined if the subtitle is not defined yet and no arguments are pass.
An object representing the properties of the subtitle if no arguments are pass.
A reference to the graph object from which the method is called upon.

Default Values:

The default values for the properties of the subtitle are as follows: ("#000000" represents the color black)

{
  enable : true,
  text : "",
  font : "Perpetua, Baskerville, Big Caslon, Palatino Linotype, Palatino, serif",
  size : "15px",
  specifier : "",
  color : "#000000",
  opacity : 1,
  filled : true,
  position : "start"
}

x Label:

This method lets you set or get the properties of the x label.

It is only necessary to define the values that you want to change and only that values will be updated, leaving the rest as they are.

Method:

xLabel()
xLabel(options)
xLabel(options, callback)

Where:

options is an object containing the following properties:
- enable: a boolean that determines whether the x label must be enabled.
- text: a string representing the text to show as a x label.
- font: a string representing the font of the x label.
- size: a string representing the size of the x label.
- specifier: a string representing the font specifier of the x label.
- color: a string representing the color of the x label.
- opacity: a number between 0 and 1 representing the opacity of the x label.
- filled: a boolean that determines whether the text must be filled or just outlined.
- position: this property controls the relative position of the x label, can be one of the following values:
  - "start".
  - "center".
  - "end".
callback is a function that is run after the x label properties are set but before the next render, this callback accepts an optional argument that represents the graph object from which the method is called upon.

Note: The color can be in the format "#rrggbb" or be any of the standard color names.

Note: The font value can be any font or stack of fonts available in the browser. Its advised to use safe web fonts.

Note: The size value can be any valid css size including em, rem, etc.

Note: The label will render only if the axis position is not set to center.

Note: The specifier can be any combination of the following css font properties.

font-style.

font-variant.

font-weight.

font-stretch.

line-height.

Some fonts may not support all specifier options.

Returns:

undefined if the x label is not defined yet and no arguments are pass.
An object representing the properties of the x label if no arguments are pass.
A reference to the graph object from which the method is called upon.

Default Values:

The default values for the properties of the x label are as follows: ("#000000" represents the color black)

{
  enable : true,
  text : "",
  font : "Perpetua, Baskerville, Big Caslon, Palatino Linotype, Palatino, serif",
  size : "15px",
  specifier : "",
  color : "#000000",
  opacity : 1,
  filled : true,
  position : "center"
}

y Label:

This method lets you set or get the properties of the y label.

It is only necessary to define the values that you want to change and only that values will be updated, leaving the rest as they are.

Method:

yLabel()
yLabel(options)
yLabel(options, callback)

Where:

options is an object containing the following properties:
- enable: a boolean that determines whether the y label must be enabled.
- text: a string representing the text to show as a y label.
- font: a string representing the font of the y label.
- size: a string representing the size of the y label.
- specifier: a string representing the font specifier of the y label.
- color: a string representing the color of the y label.
- opacity: a number between 0 and 1 representing the opacity of the y label.
- filled: a boolean that determines whether the text must be filled or just outlined.
- position: this property controls the relative position of the y label, can be one of the following values:
  - "start".
  - "center".
  - "end".
callback is a function that is run after the y label properties are set but before the next render, this callback accepts an optional argument that represents the graph object from which the method is called upon.

Note: The color can be in the format "#rrggbb" or be any of the standard color names.

Note: The font value can be any font or stack of fonts available in the browser. Its advised to use safe web fonts.

Note: The size value can be any valid css size including em, rem, etc.

Note: The label will render only if the axis position is not set to center.

Note: The specifier can be any combination of the following css font properties.

font-style.

font-variant.

font-weight.

font-stretch.

line-height.

Some fonts may not support all specifier options.

Returns:

undefined if the y label is not defined yet and no arguments are pass.
An object representing the properties of the y label if no arguments are pass.
A reference to the graph object from which the method is called upon.

Default Values:

The default values for the properties of the y label are as follows: ("#000000" represents the color black)

{
  enable : true,
  text : "",
  font : "Perpetua, Baskerville, Big Caslon, Palatino Linotype, Palatino, serif",
  size : "15px",
  specifier : "",
  color : "#000000",
  opacity : 1,
  filled : true,
  position : "center"
}

Secondary x Label:

This method lets you set or get the properties of the secondary x label.

It is only necessary to define the values that you want to change and only that values will be updated, leaving the rest as they are.

Method:

xLabelSecondary()
xLabelSecondary(options)
xLabelSecondary(options, callback)

Where:

options is an object containing the following properties:
- enable: a boolean that determines whether the secondary x label must be enabled.
- text: a string representing the text to show as a secondary x label.
- font: a string representing the font of the secondary x label.
- size: a string representing the size of the secondary x label.
- specifier: a string representing the font specifier of the secondary x label.
- color: a string representing the color of the secondary x label.
- opacity: a number between 0 and 1 representing the opacity of the secondary x label.
- filled: a boolean that determines whether the text must be filled or just outlined.
- position: this property controls the relative position of the secondary x label, can be one of the following values:
  - "start".
  - "center".
  - "end".
callback is a function that is run after the secondary x label properties are set but before the next render, this callback accepts an optional argument that represents the graph object from which the method is called upon.

Note: The color can be in the format "#rrggbb" or be any of the standard color names.

Note: The font value can be any font or stack of fonts available in the browser. Its advised to use safe web fonts.

Note: The size value can be any valid css size including em, rem, etc.

Note: The label will render only if the axis position is not set to center.

Note: This label will not render if the secodary x axis is not enabled.

Note: The specifier can be any combination of the following css font properties.

font-style.

font-variant.

font-weight.

font-stretch.

line-height.

Some fonts may not support all specifier options.

Returns:

undefined if the secondary x label is not defined yet and no arguments are pass.
An object representing the properties of the secondary x label if no arguments are pass.
A reference to the graph object from which the method is called upon.

Default Values:

The default values for the properties of the secondary x label are as follows: ("#000000" represents the color black)

{
  enable : true,
  text : "",
  font : "Perpetua, Baskerville, Big Caslon, Palatino Linotype, Palatino, serif",
  size : "15px",
  specifier : "",
  color : "#000000",
  opacity : 1,
  filled : true,
  position : "center"
}

Secondary y Label:

This method lets you set or get the properties of the secondary y label.

It is only necessary to define the values that you want to change and only that values will be updated, leaving the rest as they are.

Method:

yLabelSecondary()
yLabelSecondary(options)
yLabelSecondary(options, callback)

Where:

options is an object containing the following properties:
- enable: a boolean that determines whether the secondary y label must be enabled.
- text: a string representing the text to show as a secondary y label.
- font: a string representing the font of the secondary y label.
- size: a string representing the size of the secondary y label.
- specifier: a string representing the font specifier of the secondary y label.
- color: a string representing the color of the secondary y label.
- opacity: a number between 0 and 1 representing the opacity of the secondary y label.
- filled: a boolean that determines whether the text must be filled or just outlined.
- position: this property controls the relative position of the secondary y label, can be one of the following values:
  - "start".
  - "center".
  - "end".
callback is a function that is run after the secondary y label properties are set but before the next render, this callback accepts an optional argument that represents the graph object from which the method is called upon.

Note: The color can be in the format "#rrggbb" or be any of the standard color names.

Note: The font value can be any font or stack of fonts available in the browser. Its advised to use safe web fonts.

Note: The size value can be any valid css size including em, rem, etc.

Note: The label will render only if the axis position is not set to center.

Note: This label will not render if the secodary y axis is not enabled.

Note: The specifier can be any combination of the following css font properties.

font-style.

font-variant.

font-weight.

font-stretch.

line-height.

Some fonts may not support all specifier options.

Returns:

undefined if the secondary y label is not defined yet and no arguments are pass.
An object representing the properties of the secondary y label if no arguments are pass.
A reference to the graph object from which the method is called upon.

Default Values:

The default values for the properties of the secondary y label are as follows: ("#000000" represents the color black)

{
  enable : true,
  text : "",
  font : "Perpetua, Baskerville, Big Caslon, Palatino Linotype, Palatino, serif",
  size : "15px",
  specifier : "",
  color : "#000000",
  opacity : 1,
  filled : true,
  position : "center"
}

Utilities

The graph object implements some general utility methods to help you to move, zoom and resize the graph and all its components.

Three of the four methods set event listeners on the container div element, all these event perform changes on the graph properties.

As usual, all this methods accept an optional callback if you need aditional functionality.

The available utility methods are:

pointerMove: Lets you pan the graph with a pointer based event (mouse and touch).
pointerZoom: Lets you zoom the graph with a pointer based event (mouse and touch).
containerResize: Lets you adjust the graph size with a resize observer event.
aspectRatio: Sets the aspect ratio of an axis with respect of other.

Note: The utilities pointerMove and pointerZoom are incompatibles when used with a non touch device.

It is importan to note that the utilities pointerMove and pointerZoom use both pointer based events, so if a mouse fire the event and are both enabled, only pointerMove will take effect. For this to work you must enable and disable the utilities manually.

This is not a problem when usin a movile (touch based) device. This is because diferent gestures are used each one, touch and grab for pointerMove and pinch for pointerZoom.

Pointer Move:

This method allows you to move the graph using the pointer (mouse or touch).

This method creates a new instance of the event listener, discartign any previous one.

It is only necessary to define the values that you want to customize, the rest will be set to its default.

Method:

pointerMove()
pointerMove(options)

Where:

options is an object with the following properties:
- enable: a boolean tha determines whether the utility must be enabled.
- delay: a number representing the delay in milliseconds of the throttle implementation.
- pointerCapture: a boolean that determines whether the pointer event should be capture.
- defaultCursor: a string that represent the default cursor.
- hoverCursor: a string that represent the cursor when its hovering the active area.
- moveCursor: a string that represent the cursor when is performing the move.
- primaryAxis: a boolean that determines if the move affects the primary axis.
- secondaryAxis: a boolean that determines if the move affects the secondary axis.
- callback : a function that runs afther the graph new properties are set but before the next render, this callback accepts an optional argument that represents the graph object from which the method is called upon.

Note: The properties of the graph after the move is made are computed in a throttle function to avoid overload de browser. The delay property affects how often that calculations are made.

Note: The value of the defaultCursor, hoverCursor, moveCursor can be any of the standar cursor names.

Note: When disabled, the cursor will be set to defaultCursor.

Note: Unlike other methods, the callback function is contained inside the options object.

Returns:

A reference to the graph object from which the method is called upon.

Default Values:

The default values for the properties of the pointerMove method are as follow:

{
  enable : true,
  delay : 12,
  pointerCapture: true,
  defaultCursor : "default",
  hoverCursor : "grab",
  moveCursor : "grabbing",
  primaryAxis : true,
  secondaryAxis : true,
  callback : undefined
}

Pointer Zoom:

This method allows you to zoom the graph using the pointer (mouse or touch).

This method creates a new instance of the event listener, discartign any previous one.

The zoom applied is calculated using the primary axis.

It is only necessary to define the values that you want to customize, the rest will be set to its default.

Method:

pointerZoom()
pointerZoom(options)

Where:

options is an object with the following properties:
- enable: a boolean tha determines whether the utility must be enabled.
- delay: a number representing the delay in milliseconds of the throttle implementation.
- pointerCapture: a boolean that determines whether the pointer event should be capture.
- defaultCursor: a string that represent the default cursor.
- hoverCursor: a string that represent the cursor when its hovering the active area.
- moveCursor: a string that represent the cursor when is performing the move.
- primaryAxis: a boolean that determines if the move affects the primary axis.
- secondaryAxis: a boolean that determines if the move affects the secondary axis.
- anchor : this property controls the point that will remain constant during the zoom. It can be one of the following options:
  - The string "center" to fix the mid point of both axis.
  - The string "pointer" to fix the point that the pointer was at the start of the action.
  - An array of two numbers [x, y] representing the coordinate of the fixed point.
- type : this property control the type of zoom gesture. It can be one of the following options:
  - The string "area" to make zoom drawing a rectangle.
  - The string "drag" to make zoom dragging the pointer.
- strength : a number representing the strength of the zoom. This property is only relevant when the type property is set to drag or when using touch devices.
- rect: an object representing the rectangle draw when usin the drag zoom type:
  - background: a string representing the background color of the rectangle.
  - opacity: a number representing the opacity of the rectangle.
  - borderColor: a string representing the color of the rectangle border.
  - borderOpacity: a number representing the opacity of the rectangle border.
  - borderWidth: a number representing the line width of the rectangle border.
- callback : a function that runs afther the graph new properties are set but before the next render, this callback accepts an optional argument that represents the graph object from which the method is called upon.

Note: The properties of the graph after the zoom is made are computed in a throttle function to avoid overload de browser. The delay property affects how often that calculations are made.

Note: The value of the defaultCursor, hoverCursor, moveCursor can be any of the standar cursor names.

Note: When disabled, the cursor will be set to defaultCursor.

Note: Unlike other methods, the callback function is contained inside the options object.

When using the zoom with the type set to `"area" you can draw a rectangle, and the area of that rectangle will be represented by the axis after the mouse is released.

Also, while drawing the area, you can hold the shift key to move the origin of the rectangle. In this mode, only zoom-in is available.

When using the zoom whith the type set to "drag" you must click and drag to perform the zoom. Dragging to the right relative to the initial click will zoom-in, while gragging to the left will perform a zoom-out.

In this mode, the zoom conserve the axis aspect ratio.

If you are using a touch device, the zoom will perform using the pinch gesture regardless the value of the property type.

Returns:

A reference to the graph object from which the method is called upon.

Default Values:

The default values for the properties of the pointerZoom method are as follow:

{
  enable : true,
  delay : 12,
  pointerCapture: true,
  defaultCursor : "default",
  hoverCursor : "zoom-in",
  moveCursor : "zoom-in",
  primaryAxis : true,
  secondaryAxis : true,
  callback : undefined,
  anchor : "pointer",
  type : "area",
  strength : 5,
  rect : {
    background : "#0075FF",
    opacity : 0.05,
    borderColor  : "#0057bd",
    borderOpacity : 0.5,
    borderWidth : 1
  }
}

Container Resize:

This method allows the resize of the graph whether the container div element changes size.

This method creates a new instance of the event listener, discartign any previous one.

It is only necessary to define the values that you want to customize, the rest will be set to its default.

Method:

constainerResize()
constainerResize(options)

Where:

options is an object containing the following properties:
- enable: a boolean tha determines whether the utility must be enabled.
- delay: a number representing the delay in milliseconds of the throttle implementation.
- preserveAspectRatio: a boolean that determines whether the axis aspect ratio must be conserved after the resize.
- anchor : this property controls the point in the primary axis that will remain constant during the resize. It can be one of the following options:
  - The string "center" to fix the mid point of both axis.
  - An array of two numbers [x, y] representing the coordinate in the primary axis of the fixed point.
- secondaryAnchor : this property controls the point in the secondary axis that will remain constant during the resize. It can be one of the following options:
  - The string "center" to fix the mid point of both axis.
  - An array of two numbers [x, y] representing the coordinate in the secondary axis of the fixed point.
- primaryAxis: a boolean that determines if the move affects the primary axis.
- secondaryAxis: a boolean that determines if the move affects the secondary axis.
- callback : a function that runs afther the graph new properties are set but before the next render, this callback accepts an optional argument that represents the graph object from which the method is called upon.

`preserveAspectRatio`	Result
`true`
`false`

Returns:

A reference to the graph object from which the method is called upon.

Default Values:

The default values for the properties of the containerResize method are as follow:

{
  enable : true,
  delay : 12,
  preserveAspectRatio : true,
  anchor : "center",
  secondaryAnchor : "center",
  primaryAxis : true,
  secondaryAxis : true,
  callback : undefined
}

Aspect Ratio:

This method allows you to set the aspect ratio of one axis relative to another.

This utility is not event-based, so its effects will only be applied once.

It is only necessary to define the values that you want to customize, the rest will be set to its default.

Method:

aspectRatio()
aspectRatio(options)
aspectRatio(options, callback)

Where:

options is an object containing the following properties:
- ratio: a number representing the aspect ratio to set.
- source: a string representing the source axis. It can be one of the folloging options:
  - The string "x" to set the x axis as the source.
  - The string "y" to set the y axis as the source.
  - The string "xSecondary" to set the secondary x axis as the source.
  - The string "ySecondary" to set the secondary y axis as the source.
- target: a string representing the target axis. It can be one of the folloging options:
  - The string "x" to set the x axis as the target.
  - The string "y" to set the y axis as the target.
  - The string "xSecondary" to set the secondary x axis as the target.
  - The string "ySecondary" to set the secondary y axis as the target.
- anchor: this property controls the point on the target axis that will remain unchaged afther the transformation. It can be one of the following values:
  - The string "start" to fix the start value of the target axis domain.
  - The string "end" to fix the end value of the target axis domain.
  - A number to fix that coordinate of the target axis domain.
callback is a function that is run after the aspect ratio is set but before the next render, this callback accepts an optional argument that represents the graph object from which the method is called upon.

The aspect ratio represents the amount of pixels that each unit of the target axis takes with respect the source axis.

For example, if the ratio property is set to 2, each unit of the target axis will occupy twice as much pixels that one unit of the source axis.

Note: If the source or target properties are set to either secondary axis, and that axis is not enabled, the method will take no effect.

Note: The the source or target properties can both be set to the same axis, in that case only that axis will change.

Returns:

A reference to the graph object from which the method is called upon.

Default Values:

The default values for the properties of the aspectRatio method are as follow:

{
  ratio : 1,
  source : "x",
  target : "y",
  anchor : "start"
}

Graph Properties

Margin:

This method lets you set or get the margins of the graph.

It is only necessary to define the values that you want to change and only that values will be updated, leaving the rest as they are.

Method:

margin()
margin(options)
margin(options, callback)

Where:

options is an object containing the following properties:
- x: an object whith the properties:
  - start: this property controls the margin at the left most side of the x axis. It can have one of the following values:
    - The string "auto" to compute the margin automatically.
    - A number representing the margin in pixels.
  - end: this property controls the margin at the right most side of the x axis. It can have one of the following values:
    - The string "auto" to compute the margin automatically.
    - A number representing the margin in pixels.
- y: an object whith the properties:
  - start: this property controls the margin at the bottom of the y axis. It can have one of the following values:
    - The string "auto" to compute the margin automatically.
    - A number representing the margin in pixels.
  - end: this property controls the margin at the top of the y axis. It can have one of the following values:
    - The string "auto" to compute the margin automatically.
    - A number representing the margin in pixels.
callback is a function that is run after the margins are set but before the next render, this callback accepts an optional argument that represents the graph object from which the method is called upon.

Why the end value of the y component is at the top and not the bottom? : Because of the convention of having the vertical axis values increase from bottom to top, this is a convention to follow for other similar properties.

Note: Any margin can have negative values, the behavior is as expected.

Return:

An object representing the current margins if no arguments are pass.
A reference to the graph object from which the method is called upon.

Note: Even when the value of any margin is set to "auto", this method will always return an object with numeric values.

Default values:

The default values for the margins are as follows:

{
  x : {
    start : "auto",
    end : "auto",
  },
  y : {
    start : "auto",
    end : "auto",
  },
}

Border:

This method lets you set or get the border properties of the graph.

The options object has some properties that change the borders in a generalized way, and those changes cascaded towards the more specific properties. The more specific the property is, the more priority takes.

It is only necessary to define the values that you want to change and only that values will be updated, leaving the rest as they are.

Method:

border()
border(options)
border(options, callback)

Where:

options is an object containing the following properties:
- border: an object with the properties:
  - enable: a boolean that determines whether all borders should be enabled.
  - color: a string that represent the color of all borders.
  - opacity: a number between 0 and 1 that represent the opacity of all borders.
  - width: a number that represent the line width of all borders.
  - style: a string that represents the line style of all borders.
- x : a object with the following properties:
  - start: an object that represent the properties of the left border:
    - enable: a boolean that determines whether the border should be enabled.
    - color: a string that represent the color of the border.
    - opacity: a number between 0 and 1 that represent the opacity of the border.
    - width: a number that represent the line width of the border.
    - style: a string that represents the line style of the border.
  - end: an object that represent the properties of the right border:
    - enable: a boolean that determines whether the border should be enabled.
    - color: a string that represent the color of the border.
    - opacity: a number between 0 and 1 that represent the opacity of the border.
    - width: a number that represent the line width of the border.
    - style: a string that represents the line style of the border.
- y : a object with the following properties:
  - start: an object that represent the properties of the bottom border:
    - enable: a boolean that determines whether the border should be enabled.
    - color: a string that represent the color of the border.
    - opacity: a number between 0 and 1 that represent the opacity of the border.
    - width: a number that represent the line width of the border.
    - style: a string that represents the line style of the border.
  - end: an object that represent the properties of the top border:
    - enable: a boolean that determines whether the border should be enabled.
    - color: a string that represent the color of the border.
    - opacity: a number between 0 and 1 that represent the opacity of the border.
    - width: a number that represent the line width of the border.
    - style: a string that represents the line style of the border.
callback is a function that is run after the borders are set but before the next render, this callback accepts an optional argument that represents the graph object from which the method is called upon.

Note: The color can be in the format "#rrggbb" or be any of the standard color names. Note: The value of the width must be a positive integer.

The style can be represented with one of the following options:

Style	Result
`"solid"`
`"dot"`
`"dash"`
`"long-dash"`
`"dash-dot"`
`"dash-2dot"`

Also, the string can be a list of space separated integers representing line and space length in pixel to form a custom pattern.

For example, the string "3 2 10 2 3" forms a pattern of 3 pixels line, 2 pixels space, 10 pixels line, etc.

Returns:

An object representing the current border properties if no arguments are pass.
A reference to the graph object from which the method is called upon.

Default values:

The default values for the borders are as follows:

{
  x : {
    start : {
      enable : false,
      color : "#000000",
      opacity : 1,
      width : 1,
      style : "solid"
    },
    end : {
      enable : false,
      color : "#000000",
      opacity : 1,
      width : 1,
      style : "solid"
    }
  },
  y : {
    start : {
      enable : false,
      color : "#000000",
      opacity : 1,
      width : 1,
      style : "solid"
    },
    end : {
      enable : false,
      color : "#000000",
      opacity : 1,
      width : 1,
      style : "solid"
    }
  }
}

Container Size:

This method lets you set or get the size of the container div element.

The graph change sizes accordingly, maintaining the values of the axis domain. In other words, this method do not conserve the axis aspect ratio.

It is only necessary to define the values that you want to change and only that values will be updated, leaving the rest as they are.

Method:

containerSize()
containerSize(options)
containerSize(options, callback)

Where:

options is an object containing the following properties:
- width: a number representing the width of the container in pixels.
- height: a number representing the height of the container in pixels.
callback is a function that is run after the container size is set but before the next render, this callback accepts an optional argument that represents the graph object from which the method is called upon.

Note: The width and height properties mus be a positive integer.

Returns:

An object representing the current size of the container if no arguments are pass.
A reference to the graph object from which the method is called upon.

Default values:

The default values for the container size are as follows:

{
  width : 500,
  height : 500
}

Readonly Methods

The graph implements some read only methods that are valuable for external interactions/calculations. For example if you want to write a custom event listener.

Draw:

This method render the graph only if its properties have been changed since the last call.

You need to call this method every time you made some change to the graph, add, remove or change data.

Method:

draw()

Returns:

A reference to the graph object from which the method is called upon.

Canvas Elements:

This method returns the html canvas elements used in the graph.

Those are children elements of the div container.

Method:

canvasElements()

Returns:

An array of two html canvas elements, the first is used to draw the axis, grids and labels, and the second one is were the data, colorbars and legends are draw.

Note: The pointer events of the pointerMove and pointerZoom methods are set on the second element of the array.

Client Rect:

This method returns the client rec.

The client rect is a rectangle defined inside the graph and contains the axis and the graph rect. This area is affected by the labels.

The graph rect is contained within the client rect.

Method:

clientRect()

Returns:

An object representing the x and y coordinates of the top left corner and the width and height in pixels of the client rect.

Examples of the client rect:

Graph Rect:

This method returns the graph rec.

The graph rect is a rectangle defined inside the graph and contains only the graphing area. This area is affected by the labels, margins and the axis size.

Method:

graphRect()

Returns:

An object representing the x and y coordinates of the top left corner and the width and height in pixels of the graph rect.

Examples of the graph rect:

Coordinate Maps:

This method returns the mappin objets used to transform between pixel coordinates and internal axis coordinates.

The mapping domain is the axis coordinates, while the range is the pixel coordinates. The pixel coordinates are measured from the graph rect.

Method:

coordinateMaps()

Returns:

An object with the mapping or scale of each axis. The mapping of the secondary axis may be undefined if that axis is not enabled.

Save:

This method lets you save the graph state, including the datasets, legends and colorbars. The resulting object can be serialized, usin JSON.stringify() for example.

This method can be used alongside the utility function restoreGraph to restore a saved graph.

Method:

save()

Returns:

An object with the following properties:
- graph: an object with the state of the graph. This object is compatible with the options arument of the graph2D function.
- assets: an array of objects, this objects represent all the datasets, colorbars and legends associated with the graph. Each object contains:
  - options: an object with the state of the asset. This object is compatible with the options argument of its corresponding function.
  - assetType: a string that identifies the asset type, can be one of the following options:
    - "linechart"
    - "area"
    - "heatmap"
    - "vectorfield"
    - "colorbar"
    - "legend"

Note: This method saves the graph statically. That is if any dataset has its data points or any property generated dynamically via a callback function, that callback will be evaluated and only the result will be saved.

Assets:

The graph object can hold a variety of assets, that includes colorbars, legends or any of the available datasets.

Each of these assets is bound to the graph at the moment of its creation.

Add Dataset:

This method lets you create a dataset.

Method:

addDataset(type)
addDataset(type, options)
addDataset(type, options, callback)

Where:

type is a string indicating one of the available datasets. The posible values are:
- "linechart".
- "area".
- "heatmap".
- "vectorfield".
options is an object containing the options to change the default behavior and appearance of the dataset.
callback is a function that is run after the dataset is created but before the next render, this callback accepts an optional argument that represents the graph object from which the method is called upon.

Note. The options object has a lot of properties and complex structure, its use is intended for copying or generate datasets from another datasets. All its properties are breake down in the corresponding dataset methods, is best to use those instead.

Returns:

A dataset object. This object contains the methods of the selected type so it's convenient to assign this value to a variable for later use.

Get Datasets

This method returns an object containing all the datasets associated with the graph.

Method:

getDatasets()

Returns:

An object with the following properties:

linechart: an array with all linechart objects.
area: an array with all area objects.
heatmap: an array with all heatmap objects.
vectorfield: an array with all vectorfield objects.

Remove Dataset

This method removes a dataset form the graph.

Method:

removeDataset(id)
removeDataset(id, callback)

Where:

id is the id string of the dataset you want to remove.
callback is a function that is run after the dataset is removed but before the next render, this callback accepts an optional argument that represents the graph object from which the method is called upon.

Returns:

A reference to the graph object from which the method is called upon.

Add Colorbar:

This method lets you create a colorbar.

Method:

addColorbar()
addColorbar(options)
addColorbar(options, callback)

Where:

options is an object containing the options to change the default behavior and appearance of the colorbar.
callback is a function that is run after the colorbar is created but before the next render, this callback accepts an optional argument that represents the graph object from which the method is called upon.

Note. The options object has a lot of properties and complex structure, its use is intended for copying or generate colorbars from another colorbars. All its properties are breake down in the colorbar methods, is best to use those instead.

Returns:

A colorbar object. This object contains the methods to change the behavior and appearence of the colorbar, so it's convenient to assign this value to a variable for later use.

Get Colorbars

This method returns an array containing all the colorbars associated with the graph.

Method:

getColorbars()

Returns:

An array with all colorbars.

Remove Colorbar

This method removes a colorbar form the graph.

Method:

removeColorbar(id)
removeColorbar(id, callback)

Where:

id is the id string of the colorbar you want to remove.
callback is a function that is run after the colorbar is removed but before the next render, this callback accepts an optional argument that represents the graph object from which the method is called upon.

Returns:

A reference to the graph object from which the method is called upon.

Add Legend:

This method lets you create a colorbar.

Method:

addLegend()
addLegend(options)
addLegend(options, callback)

Where:

options is an object containing the options to change the default behavior and appearance of the legend.
callback is a function that is run after the legend is created but before the next render, this callback accepts an optional argument that represents the graph object from which the method is called upon.

Note. The options object has a lot of properties and complex structure, its use is intended for copying or generate legends from another legends. All its properties are breake down in the legend methods, is best to use those instead.

Returns:

A legend object. This object contains the methods to change the behavior and appearence of the legend, so it's convenient to assign this value to a variable for later use.

Get Legends

This method returns an array containing all the legends associated with the graph.

Method:

getLegends()

Returns:

An array with all legends.

Remove Legend

This method removes a legend form the graph.

Method:

removeLegend(id)
removeLegend(id, callback)

Where:

id is the id string of the legend you want to remove.
callback is a function that is run after the legend is removed but before the next render, this callback accepts an optional argument that represents the graph object from which the method is called upon.

Returns:

A reference to the graph object from which the method is called upon.

Datasets

Line Chart:

The linechart dataset is use to create, as the name implies, line charts but also can create dispersion graphs.

It uses a set of datapoints that consist of two arrays of numbers with the same size representing the [x, y] coordinates of each point.

The main components of a line chart are:

The data itself.
The lines that can be draw connecting each datapoint.
The markers that can be draw on each datapoint.
The error bars that can be draw on each datapoint.

The datapoints and properties of that datapoints can be defined to be static or dynamic, meaning that its values can be static and never change or be computed on each draw and even be based on the values of other properties.

If you set any of the datapoint components to be dynamic, that component must be defined by a function of the type:

generator()
generator(dataset)
generator(dataset, graph)

Where:

dataset: is a reference to the dataset from which the function is call upon.
graph: is a reference of the graph that the dataset is bound to.

These two optional arguments always holds the dataset and graph latest state at the moment of the call.

Note: Unlike the callback that most methods accept, the generator function runs on every draw.

The linechart data generator must return an array of numbers.

Example:

First, lets create a static line chart.

//Gets the container div element
const element = document.querrySelector("#my-graph");

//Creates and customize the graph object
const my_graph = graph2D(element);

my_graph.axisDomain({
  x : {start : -8, end : 8},
  y : {start : -1.2, end : 1.2}
})
.containerSize({width : 800,  height : 300})
.pointerMove();

//Creates the linechart
const line_chart = my_graph.addDataset("linechart");

//Creates the data arrays
const x_data = linspace(-8, 8, 150);
const y_data = x_data.map(x => Math.cos(x));

//Add the data to the linechart
line_chart.dataX(x_data).dataY(y_data);

//Finally draws the graph
my_graph.draw();

Result:

Note: linspace is a utility function, you can learn more about this functions on the extras section.

The properties of the linechart can be easily modified, for example by adding to the last script.

line_cart.lineColor("#cf0808");

//Don't forget to call the draw() method after each change.
my_graph.draw();

Changes the line color

Now let's recreate the same graph but using dynamic data instead.

//Gets the container div element
const element = document.querrySelector("#my-graph");

//Creates and customize the graph object
const my_graph = graph2D(element);

my_graph.axisDomain({
  x : {start : -8, end : 8},
  y : {start : -1.2, end : 1.2}
})
.containerSize({width : 800,  height : 300})
.pointerMove();

//Creates the linechart and add the data
const line_chart = my_graph.addDataset("linechart");

line_chart.dataX((dataset, graph)=>{
  //This function will run on every draw
  //Inside this function, dataset makes reference to line_chart and 
  //graph to my_graph

  const domain = graph.axisDomain(); 

  //The return value must be an array of numbers
  return linspace(domain.x.start, domain.x.end, 150)
})
.dataY( dataset=>{
  //In this case we only need a reference to the dataset

  const x_values = dataset.dataX(); //From here we can get the generated x values and other non dynamic properties.

  const y = x_values.map(x=>Math.cos(x));

  //Again, the return value must be an array of numbers
  return y;
});

//Finally draws the graph
my_graph.draw();

Result:

As shown, the graph can be moved indefinitely and the data moves along with it.

Warning: You may only read static properties from dynamic data generators, this is because dynamic properties depend on the x and y data values, so calling those from a data generator will create a circular dependency and the program will stop.

Warning: You must not call the dataX() or draw() method from the x data generator because that will create a circular dependency and the program will stop.

Warning: You must not call the dataY() or draw() method from the y data generator because that will create a circular dependency and the program will stop.

Note: It is safe to call the dataX() method from within the y data generator and vice versa.

The creation of dynamic properties is slightly different. This is because the properties are assigned to each datapoint so the generator function depends directly on the x and y data components.

The generator function will be call once for each datapoint and must return a suitable value for that datapoint.

The generator can accept some optional parameters that must be call in the next order:

generator(x, y, index, arrayX, arrayY, dataset, graph)

Where:

x: is the x value of the datapoint.
y: is the y value of the datapoint.
index: is the index corresponding to the x and y values.
arrayX: is the complete arary of x data values.
arrayY: is the complete arary of y data values.
dataset: is a reference to the dataset from which the function is call upon.
graph: is a reference of the graph that the dataset is bound to.

Note: All the arguments of the property generator function are optional.

Note: The property generator operates in a similar way of the array methods (map, forEach, etc).

For example, the line color of the last graph can be dynamically change to be dependent of the y values by adding:

//Create a colormap
const color = colorMap({
  from : -1,
  to : 1,
  type : "magnet"
});

line_chart.lineColor((x, y)=>{
  //In this case we only need access to the data values in the arguments.
  
  //The return value will be assigned to the corresponding datapoint
  return color(y);
});

my_graph.draw();

Result:

Note: colorMap is a utility function, you can learn more about this functions on the extras section.

ID:

This method lets you set or get the id string of the dataset.

Method:

id()
id(option)
id(option, callback)

Where:

option: is a string representing the id of the dataset.
callback: is a function that is run after the id is set but before the next render, this callback accept two optional arguments that represents the dataset object from which the method is called upon and the graph object that is bound to, in that order.

Note: The id is used to identify the dataset, so the string must be unique among other datasets.

By default, the id is generated automatically to guarantee its uniqueness, so in the majority of cases it is best to leave it as it is.

Returns:

A string representing the id of the dataset if no arguments are pass.
A reference to the dataset object from which the method is called upon.

Index:

This method lets you set or get the index of the dataset.

The index is used to determine the order in which the datasets will be drawn. The dataset with the lower index value will be drawn first and appear to be behind other datasets.

Method:

index()
index(option)
index(option, callback)

Where:

option: is a number representing the index value of the dataset.
callback: is a function that is run after the index is set but before the next render, this callback accept two optional arguments that represents the dataset object from which the method is called upon and the graph object that is bound to, in that order.

Note: The draw order of datasets with the same index value will be indeterminate.

Returns:

A number that represents the index of the dataset if no aguments are pass.
A reference to the dataset object from which the method is called upon.

Dataset Type:

This method returns the linechart dataset type.

Method:

datasetType()

Returns:

This method always return the string "linechart".

This is usefull when you read the dataset from the graph2D getDatasets() method or the restoreGraph() function.

Line Data

The data in the linechart is composed of two arrays of numbers with equal length. Each pair of numbers that share the same index in the arrays represent the [x, y] coordinates of one data point.

Each array must be defined independently.

Data x:

This method lets you get ot set the x component of the data points.

Method:

dataX()
dataX(data)
dataX(data, callback)

Where:

data: represents the x component of the data points. It can be one of the following options:
- An array of numbers.
- A function that returns an array of numbers. This function can accept two optional parameters in the following order:
  - An object that represents the dataset from which the method is called upon.
  - An object that represents the graph object that the dataset is bound to.
callback: is a function that is run after the data is set but before the next render, this callback accept two optional arguments that represents the dataset object from which the method is called upon and the graph object that is bound to, in that order.

Note: Unlike the callback, If you define the data as a function, that function will be executed on each subsequent draw and the arguments will hold the latest state of the dataset and graph at the moment of the call.

Warning: Neither dataX() nor draw() should be called from within the data function, because that will cause a circular dependency and the program will stop.

Warning: Any dynamic property should not be read from within the data function, because that will cause a circular dependency and the program will stop.

Note: It is safe to call static properties.

When the data is defined as a function, we say that is dynamically generated.

If the data is dynamically generated, its values are updated on each draw. It is important to note that the draw() method only updates the graph if a change is made to it or any of its assets, so if you change an external value, even if that value is used inside the data function, it will not be detected and the data will not update.

Note: The linechart data generator functions are discussed in deep here.

Returns:

An array of numbers representing the x component of the datapoints if no arguments are pass.
A reference to the dataset object from which the method is called upon.

Note: Even when the data is defined as a function, this method will return an array of numbers.

Data y:

This method lets you get ot set the y component of the data points.

Method:

dataY()
dataY(data)
dataY(data, callback)

Where:

data: represents the y component of the data points. It can be one of the following options:
- An array of numbers.
- A function that returns an array of numbers. This function can accept two optional parameters in the following order:
  - An object that represents the dataset from which the method is called upon.
  - An object that represents the graph object that the dataset is bound to.
callback: is a function that is run after the data is set but before the next render, this callback accept two optional arguments that represents the dataset object from which the method is called upon and the graph object that is bound to, in that order.

Note: Unlike the callback, If you define the data as a function, that function will be executed on each subsequent draw and the arguments will hold the latest state of the dataset and graph at the moment of the call.

Warning: Neither dataY() nor draw() should be called from within the data function, because that will cause a circular dependency and the program will stop.

Warning: Any dynamic property should not be read from within the data function, because that will cause a circular dependency and the program will stop.

Note: It is safe to call static properties.

When the data is defined as a function, we say that is dynamically generated.

If the data is dynamically generated, its values are updated on each draw. It is important to note that the draw() method only updates the graph if a change is made to it or any of its assets, so if you change an external value, even if that value is used inside the data function, it will not be detected and the data will not update.

Note: The linechart data generator functions are discussed in deep here.

Returns:

An array of numbers representing the y component of the datapoints if no arguments are pass.
A reference to the dataset object from which the method is called upon.

Note: Even when the data is defined as a function, this method will return an array of numbers.

Axis Used:

This method lets you set or get the axis used by the linechart.

Method:

axisUsed()
axisUsed(options)
axisUsed(options, callback)

Where:

options: is an object containing the following properties:
- x: a string representing the x axis that the dataset is goin to use. It can be "primary" or "secondary".
- y: a string representing the y axis that the dataset is goin to use. It can be "primary" or "secondary".
callback: is a function that is run after the axis used is set but before the next render, this callback accept two optional arguments that represents the dataset object from which the method is called upon and the graph object that is bound to, in that order.

Returns:

An object representing the axis being used by the dataset if no arguments are pass.
A reference to the dataset object from which the method is called upon.

Default Value:

The default values for the axis used property are as follow.

{
  x : "primary",
  y : "primary"
}

Polar:

This method lets you set or get the polar property of the linechart.

This property controls whether the data arrays must be interpreted in rectangular or polar coordinates system.

Method:

polar()
polar(option)
polar(option, callback)

Where:

option: is a boolean that determines whether the data must be interpreted in polar coordinates.
callback: is a function that is run after the polar property is set but before the next render, this callback accept two optional arguments that represents the dataset object from which the method is called upon and the graph object that is bound to, in that order.

If the polar property is set to true then:

dataX will be interpreted as the radial coordinates.
dataY will be interpreted as the angular coordinates.

For example, consider the data arrays:

const r = linspace(1, 1, 200);          //[1,1,1, ..., 1]
const theta = linspace(0, 2*Math.PI, 200);  //[0, 0.042, ..., 6.283]

//Assign the data to the linechart
line_chart.dataX(r).dataY(theta);

//Don't forget to render the new state.
my_graph.draw();

`polar(false)`	`polar(true)`

When the polar property is set to false the linechart only shows a straight line but the data is correctly interpreted as a full circumference of radius one if the polar property is set as true.

Returns:

A boolean that represents the linechart polar property value if no arguments are pass.
A reference to the dataset object from which the method is called upon.

Default Value:

The default value for the linechart polar property is false.

Line Properties

Line Enable:

This method lets you set or get the enable status of the line drawn.

Method:

lineEnable()
lineEnable(option)
lineEnable(option, callback)

Where:

option: is a boolean that determines whether the line must be enabled.
callback: is a function that is run after the line enable property is set but before the next render, this callback accept two optional arguments that represents the dataset object from which the method is called upon and the graph object that is bound to, in that order.

Note: This method only affects the line that is draw between datapoints, to fully disable a linechart the marks and error bars must be disabled as well.

Returns:

A bolean representing the enable status of the line.
A reference to the dataset object from which the method is called upon.

Default Value:

The default values for the enable property of the line is true.

Line Color:

This method lets you set or get the color of the line drawn between datapoints.

Method:

lineColor()
lineColor(option)
lineColor(option, callback)

Where:

option: represents the line color. It can be one of the following options:
- A string that represents the whole line color.
- An array of strings, each representing the line color on each datapoint.
- A generator function that returns a string representing the color at each datapoint.
callback: is a function that is run after the line color is set but before the next render, this callback accept two optional arguments that represents the dataset object from which the method is called upon and the graph object that is bound to, in that order.

Note: The color can be in the format "#rrggbb" or be any of the standard color names.

Note: If the color is defined as an array, its length must be the same as the data arrays.

Note: The linechart property generator functions are discussed in deep here.

Returns:

A string or an array of strings representing the line color if no argument is pass.
A reference to the dataset object from which the method is called upon.

Note: The returned value will be an array even if the color is defined as a function.

Default Value:

The default value for the line color is "#0043e0".

Line Opacity:

This method lets you set or get the opacity of the line drawn between datapoints.

Method:

lineOpacity()
lineOpacity(option)
lineOpacity(option, callback)

Where:

option: represents the line opacity. It can be one of the following options:
- A number that represents the whole line opacity.
- An array of numbers, each representing the line opacity on each datapoint.
- A generator function that returns a number representing the opacity at each datapoint.
callback: is a function that is run after the line opacity is set but before the next render, this callback accept two optional arguments that represents the dataset object from which the method is called upon and the graph object that is bound to, in that order.

Note: The opacity values must be a number between 0 and 1.

Note: If the opacity is defined as an array, its length must be the same as the data arrays.

Note: The linechart property generator functions are discussed in deep here.

Returns:

A number or an array of numbers representing the line opacity if no argument is pass.
A reference to the dataset object from which the method is called upon.

Note: The returned value will be an array even if the opacity is defined as a function.

Default Value:

The default value for the line opacity is 1.

Line Style:

This method lets you set or get the style of the line drawn between datapoints.

Method:

lineStyle()
lineStyle(option)
lineStyle(option, callback)

Where:

option: represents the line style. It can be one of the following options:
- A string that represents the whole line style.
- An array of strings, each representing the line style on each datapoint.
- A generator function that returns a string representing the style at each datapoint.
callback: is a function that is run after the line style is set but before the next render, this callback accept two optional arguments that represents the dataset object from which the method is called upon and the graph object that is bound to, in that order.

Note: If the style is defined as an array, its length must be the same as the data arrays.

Note: The linechart property generator functions are discussed in deep here.

The style can be represented with one of the following options:

Style	Result
`"solid"`
`"dot"`
`"dash"`
`"long-dash"`
`"dash-dot"`
`"dash-2dot"`

Also, the string can be a list of space separated integers representing line and space length in pixel to form a custom pattern.

For example, the string "3 2 10 2 3" forms a pattern of 3 pixels line, 2 pixels space, 10 pixels line, etc.

Returns:

A string or an array of strings representing the line style if no argument is pass.
A reference to the dataset object from which the method is called upon.

Note: The returned value will be an array even if the style is defined as a function.

Default Value:

The default value for the line style is "solid".

Line Width:

This method lets you set or get the width of the line drawn between datapoints.

Method:

lineWidth()
lineWidth(option)
lineWidth(option, callback)

Where:

option: represents the line width. It can be one of the following options:
- A number that represents the whole line width.
- An array of numbers, each representing the line width on each datapoint.
- A generator function that returns a number representing the width at each datapoint.
callback: is a function that is run after the line width is set but before the next render, this callback accept two optional arguments that represents the dataset object from which the method is called upon and the graph object that is bound to, in that order.

Note: The width values must be a positive integer.

Note: If the width is defined as an array, its length must be the same as the data arrays.

Note: The linechart property generator functions are discussed in deep here.

Returns:

A number or an array of numbers representing the line width if no argument is pass.
A reference to the dataset object from which the method is called upon.

Note: The returned value will be an array even if the width is defined as a function.

Default Value:

The default value for the line width is 1.

Marker

The markers are symbols that can be drawn on each data point.

These are useful when the data is not that dense and you need to show exactly where each datapoint is.

Marker Enable:

This method lets you set or get the enable status of the markers.

Method:

markerEnable()
markerEnable(option)
markerEnable(option, callback)

Where:

option: is a boolean that determines whether the markers must be enabled.
callback: is a function that is run after the markers enable property is set but before the next render, this callback accept two optional arguments that represents the dataset object from which the method is called upon and the graph object that is bound to, in that order.

Note: This method only affects the markers, to fully disable a linechart the line and error bars must be disabled as well.

Returns:

A bolean representing the enable status of the marker.
A reference to the dataset object from which the method is called upon.

Default Value:

The default value for the enable property of the marker is false.

Marker Color:

This method lets you set or get the color of the markers.

Method:

markerColor()
markerColor(option)
markerColor(option, callback)

Where:

option: represents the marker color. It can be one of the following options:
- A string that represents the color of all markers.
- An array of strings, each representing the marker color at each datapoint.
- A generator function that returns a string representing the color at each datapoint.
callback: is a function that is run after the marker color is set but before the next render, this callback accept two optional arguments that represents the dataset object from which the method is called upon and the graph object that is bound to, in that order.

Note: The color can be in the format "#rrggbb" or be any of the standard color names.

Note: If the color is defined as an array, its length must be the same as the data arrays.

Note: The linechart property generator functions are discussed in deep here.

Returns:

A string or an array of strings representing the markers color if no argument is pass.
A reference to the dataset object from which the method is called upon.

Note: The returned value will be an array even if the color is defined as a function.

Default Value:

The default value for the markers color is "#0043e0".

Marker Opacity:

This method lets you set or get the opacity of the markers.

Method:

markerOpacity()
markerOpacity(option)
markerOpacity(option, callback)

Where:

option: represents the marker opacity. It can be one of the following options:
- A number that represents the opacity of all markers.
- An array of numbers, each representing the marker opacity at each datapoint.
- A generator function that returns a number representing the marker opacity at each datapoint.
callback: is a function that is run after the marker opacity is set but before the next render, this callback accept two optional arguments that represents the dataset object from which the method is called upon and the graph object that is bound to, in that order.

Note: The opacity values must be a number between 0 and 1.

Note: If the opacity is defined as an array, its length must be the same as the data arrays.

Note: The linechart property generator functions are discussed in deep here.

Returns:

A number or an array of numbers representing the marker opacity if no argument is pass.
A reference to the dataset object from which the method is called upon.

Note: The returned value will be an array even if the opacity is defined as a function.

Default Value:

The default value for the marker opacity is 1.

Marker Style:

This method lets you set or get the style of the markers.

Method:

markerStyle()
markerStyle(option)
markerStyle(option, callback)

Where:

option: represents the marker line style. It can be one of the following options:
- A string that represents the style of all markers.
- An array of strings, each representing the marker line style at each datapoint.
- A generator function that returns a string representing the marker line style at each datapoint.
callback: is a function that is run after the marker style is set but before the next render, this callback accept two optional arguments that represents the dataset object from which the method is called upon and the graph object that is bound to, in that order.

Note: This method is only relevant wen the marker filled property is set to false.

Note: If the style is defined as an array, its length must be the same as the data arrays.

Note: The linechart property generator functions are discussed in deep here.

The style can be represented with one of the following options:

Style	Result
`"solid"`
`"dot"`
`"dash"`
`"long-dash"`
`"dash-dot"`
`"dash-2dot"`

Also, the string can be a list of space separated integers representing line and space length in pixel to form a custom pattern.

For example, the string "3 2 10 2 3" forms a pattern of 3 pixels line, 2 pixels space, 10 pixels line, etc.

Returns:

A string or an array of strings representing the marker line style if no argument is pass.
A reference to the dataset object from which the method is called upon.

Note: The returned value will be an array even if the style is defined as a function.

Default Value:

The default value for the marker line style is "solid".

Marker Width:

This method lets you set or get the line width of markers.

Method:

markerWidth()
markerWidth(option)
markerWidth(option, callback)

Where:

option: represents the marker line width. It can be one of the following options:
- A number that represents line width of all markers.
- An array of numbers, each representing the marker line width at each datapoint.
- A generator function that returns a number representing the marker line width at each datapoint.
callback: is a function that is run after the marker line width is set but before the next render, this callback accept two optional arguments that represents the dataset object from which the method is called upon and the graph object that is bound to, in that order.

Note: This method is only relevant wen the marker filled property is set to false.

Note: The width values must be a positive integer.

Note: If the width is defined as an array, its length must be the same as the data arrays.

Note: The linechart property generator functions are discussed in deep here.

Returns:

A number or an array of numbers representing the marker line width if no argument is pass.
A reference to the dataset object from which the method is called upon.

Note: The returned value will be an array even if the width is defined as a function.

Default Value:

The default value for the marker line width is 1.

Marker Filled:

This method lets you set or get the filled property of the markers.

If set to true, the marker will be drawn as a solid figure, otherwise will only be outlined.

Method:

markerFilled()
markerFilled(option)
markerFilled(option, callback)

Where:

option: represents the marker filled property. It can be one of the following options:
- A boolean that determine whether all markers should be filled.
- An array of boolean, each representing whether the marker should be filled at each datapoint.
- A generator function that returns a boolean determining whether the marker should be filled at each datapoint.
callback: is a function that is run after the marker filled property is set but before the next render, this callback accept two optional arguments that represents the dataset object from which the method is called upon and the graph object that is bound to, in that order.

Note: If the filled property is defined as an array, its length must be the same as the data arrays.

Note: The linechart property generator functions are discussed in deep here.

Returns:

A bolean or a string of boolean representing the marker filled property.
A reference to the dataset object from which the method is called upon.

Note: The returned value will be an array even if filled is defined as a function.

Default Value:

The default values for the enable property of the line is true.

Marker Type:

This method lets you set or get the marker type.

Method:

markerType()
markerType(option)
markerType(option, callback)

Where:

option: represents the marker type. It can be one of the following options:
- A string representing the type of all markers.
- An array of strings representing the marker type at each datapoint.
- A generator function that returns a string representing the marker type at each datapoint.
callback: is a function that is run after the marker type is set but before the next render, this callback accept two optional arguments that represents the dataset object from which the method is called upon and the graph object that is bound to, in that order.

Note: If the marker type is defined as an array, its length must be the same as the data arrays.

Note: The linechart property generator functions are discussed in deep here.

The property type can be any of the following options:

Type			Type
"circle"			"square"
"v-rect"			"h-rect"
"cross"			"star"
"triangle"			"inv-triangle"

Returns:

A string or an array of strings representing the marker type if no argument is pass.
A reference to the dataset object from which the method is called upon.

Note: The returned value will be an array even if the type is defined as a function.

Default Value:

The default value for the marker type is "circle".

Marker Size:

This method lets you set or get the size of the markers.

Method:

markerSize()
markerSize(option)
markerSize(option, callback)

Where:

option: represents the marker size. It can be one of the following options:
- A number representing the size of all markers.
- An array of numbers representing the marker size at each datapoint.
- A generator function that returns a number representing the marker size at each datapoint.
callback: is a function that is run after the marker size is set but before the next render, this callback accept two optional arguments that represents the dataset object from which the method is called upon and the graph object that is bound to, in that order.

Note: The marker size must be a positive number.

Note: If the marker size is defined as an array, its length must be the same as the data arrays.

Note: The linechart property generator functions are discussed in deep here.

Unlike other numeric properties, the marker size is not expressed in pixels, but relative to the default size.

That is, the default size is 1, so a value of 2 will be double the size and 0.5 the half.

Note: Each size is different to maintain the apparent size between them consistent. For reference, the default size of the markers is approximately 10px.

Returns:

A number or an array of numbers representing the marker size if no argument is pass.
A reference to the dataset object from which the method is called upon.

Note: The returned value will be an array even if the size is defined as a function.

Default Value:

The defaul value for the marker size is 1.

Error Bars

The error bars are aditional markers that represent the error or uncertainty in the values or the datapoints.

Unlike regular markers, the error bars have a precise and measurable meaning. It can represent a standad deviation, standard error or some confidence interval.

Either way, the value associated with a given error bar will extend equally on both sides of the datapoint in the corresponding axis.

Error Bar Enabled

This method lets you set or get the enable status of the errorbars.

It is only necessary to define the values that you want to change and only that values will be updated, leaving the rest as they are.

Method:

markerEnable()
markerEnable(option)
markerEnable(option, callback)

Where:

option: is an object containing the following properties.
- x: a boolean that determines whether the x error bars must be enabled.
- y: a boolean that determines whether the y error bars must be enabled.
callback: is a function that is run after the error bars enable property is set but before the next render, this callback accept two optional arguments that represents the dataset object from which the method is called upon and the graph object that is bound to, in that order.

Note: This method only affects the error bars, to fully disable a linechart the line and markers must be disabled as well.

Returns:

An object representing the enable property of the error bars.
A reference to the dataset object from which the method is called upon.

Default Value:

The default values for the enable property of the error bars are as follows:

{
  x : false,
  y : false
}

Error Bar Type:

This method lets you set or get the type of the error bars.

Method:

errorbarType()
errorbarType(option)
errorbarType(option, callback)

Where:

option: represents the error bar type. It can be one of the following options:
- A string representing the type of all error bars.
- An array of strings representing the error bar type at each datapoint.
- A generator function that returns a string representing the error bar type at each datapoint.
callback: is a function that is run after the error bar type is set but before the next render, this callback accept two optional arguments that represents the dataset object from which the method is called upon and the graph object that is bound to, in that order.

Note: If the error bar type is defined as an array, its length must be the same as the data arrays.

Note: The linechart property generator functions are discussed in deep here.

The property type can be any of the following options:

Type		Type
`"rectangle"`		`"cross"`
`"corner"`		`"tail-cross"`

Returns:

A string or an array of strings representing the error bar type if no argument is pass.
A reference to the dataset object from which the method is called upon.

Note: The returned value will be an array even if the type is defined as a function.

Default Value:

The default value for the error bar type is "tail-cross".

Error Bar Data x

This method lets you set or get the data values for the error bar x component.

Method:

errorbarDataX()
errorbarDataX(option)
errorbarDataX(option, callback)

Where:

option: represents the data of the error bar x component. It can be one of the following options:
- A number that represents the x data of all error bars.
- An array of numbers, each representing the errorbar x data at each datapoint.
- A generator function that returns a number representing the error bar x data at each datapoint.
callback: is a function that is run after the error bar data is set but before the next render, this callback accept two optional arguments that represents the dataset object from which the method is called upon and the graph object that is bound to, in that order.

Note: If the data is defined as an array, its length must be the same as the data arrays.

Note: The linechart property generator functions are discussed in deep here.

Returns:

A number or an array of numbers representing the data of the error bar x component if no argument is pass.
A reference to the dataset object from which the method is called upon.

Note: The returned value will be an array even if the data is defined as a function.

Default Value:

The default value for the error bar x data is 0.

Error Bar Data y

This method lets you set or get the data values for the error bar y component.

Method:

errorbarDataY()
errorbarDataY(option)
errorbarDataY(option, callback)

Where:

option: represents the data of the error bar y component. It can be one of the following options:
- A number that represents the y data of all error bars.
- An array of numbers, each representing the errorbar y data at each datapoint.
- A generator function that returns a number representing the error bar y data at each datapoint.
callback: is a function that is run after the error bar data is set but before the next render, this callback accept two optional arguments that represents the dataset object from which the method is called upon and the graph object that is bound to, in that order.

Note: If the data is defined as an array, its length must be the same as the data arrays.

Note: The linechart property generator functions are discussed in deep here.

Returns:

A number or an array of numbers representing the data of the error bar y component if no argument is pass.
A reference to the dataset object from which the method is called upon.

Note: The returned value will be an array even if the data is defined as a function.

Default Value:

The default value for the error bar y data is 0.

Error Bar Color x:

This method lets you set or get the color of the error bar x component.

Method:

errorBarColorX()
errorBarColorX(option)
errorBarColorX(option, callback)

Where:

option: represents the color of the error bar x component. It can be one of the following options:
- A string that represents the color of all error bars.
- An array of strings, each representing the error bar color at each datapoint.
- A generator function that returns a string representing the error bar color at each datapoint.
callback: is a function that is run after the error bar color is set but before the next render, this callback accept two optional arguments that represents the dataset object from which the method is called upon and the graph object that is bound to, in that order.

Note: The color can be in the format "#rrggbb" or be any of the standard color names.

Note: If the color is defined as an array, its length must be the same as the data arrays.

Note: The linechart property generator functions are discussed in deep here.

Returns:

A string or an array of strings representing the color of the error bar x component if no argument is pass.
A reference to the dataset object from which the method is called upon.

Note: The returned value will be an array even if the color is defined as a function.

Default Value:

The default value for the error bars x color is "#666666".

Error Bar Color y:

This method lets you set or get the color of the error bar y component.

Method:

errorBarColorY()
errorBarColorY(option)
errorBarColorY(option, callback)

Where:

option: represents the color of the error bar y component. It can be one of the following options:
- A string that represents the color of all error bars.
- An array of strings, each representing the error bar color at each datapoint.
- A generator function that returns a string representing the error bar color at each datapoint.
callback: is a function that is run after the error bar color is set but before the next render, this callback accept two optional arguments that represents the dataset object from which the method is called upon and the graph object that is bound to, in that order.

Note: The color can be in the format "#rrggbb" or be any of the standard color names.

Note: If the color is defined as an array, its length must be the same as the data arrays.

Note: The linechart property generator functions are discussed in deep here.

Returns:

A string or an array of strings representing the color of the error bar y component if no argument is pass.
A reference to the dataset object from which the method is called upon.

Note: The returned value will be an array even if the color is defined as a function.

Default Value:

The default value for the error bars y color is "#666666".

Error Bar Opacity x:

This method lets you set or get the opacity of the error bar x component.

Method:

errorbarOpacityX()
errorbarOpacityX(option)
errorbarOpacityX(option, callback)

Where:

option: represents the opacity of the error bar x component. It can be one of the following options:
- A number that represents the opacity of all error bars.
- An array of numbers, each representing the error bar opacity at each datapoint.
- A generator function that returns a number representing the error bar opacity at each datapoint.
callback: is a function that is run after the error bar opacity is set but before the next render, this callback accept two optional arguments that represents the dataset object from which the method is called upon and the graph object that is bound to, in that order.

Note: The opacity values must be a number between 0 and 1.

Note: If the opacity is defined as an array, its length must be the same as the data arrays.

Note: The linechart property generator functions are discussed in deep here.

Returns:

A number or an array of numbers representing the opacity of the error bar x component if no argument is pass.
A reference to the dataset object from which the method is called upon.

Note: The returned value will be an array even if the opacity is defined as a function.

Default Value:

The default value for the error bar x opacity is 1.

Error Bar Opacity y:

This method lets you set or get the opacity of the error bar y component.

Method:

errorbarOpacityY()
errorbarOpacityY(option)
errorbarOpacityY(option, callback)

Where:

option: represents the opacity of the error bar y component. It can be one of the following options:
- A number that represents the opacity of all error bars.
- An array of numbers, each representing the error bar opacity at each datapoint.
- A generator function that returns a number representing the error bar opacity at each datapoint.
callback: is a function that is run after the error bar opacity is set but before the next render, this callback accept two optional arguments that represents the dataset object from which the method is called upon and the graph object that is bound to, in that order.

Note: The opacity values must be a number between 0 and 1.

Note: If the opacity is defined as an array, its length must be the same as the data arrays.

Note: The linechart property generator functions are discussed in deep here.

Returns:

A number or an array of numbers representing the opacity of the error bar y component if no argument is pass.
A reference to the dataset object from which the method is called upon.

Note: The returned value will be an array even if the opacity is defined as a function.

Default Value:

The default value for the error bar y opacity is 1.

Error Bar Style x:

This method lets you set or get the style of the error bar x component.

Method:

errorbarStyleX()
errorbarStyleX(option)
errorbarStyleX(option, callback)

Where:

option: represents the line style of the error bar x component. It can be one of the following options:
- A string that represents the style of all error bars.
- An array of strings, each representing the error bar line style at each datapoint.
- A generator function that returns a string representing the error bar line style at each datapoint.
callback: is a function that is run after the error bar style is set but before the next render, this callback accept two optional arguments that represents the dataset object from which the method is called upon and the graph object that is bound to, in that order.

Note: If the style is defined as an array, its length must be the same as the data arrays.

Note: The linechart property generator functions are discussed in deep here.

The style can be represented with one of the following options:

Style	Result
`"solid"`
`"dot"`
`"dash"`
`"long-dash"`
`"dash-dot"`
`"dash-2dot"`

Also, the string can be a list of space separated integers representing line and space length in pixel to form a custom pattern.

For example, the string "3 2 10 2 3" forms a pattern of 3 pixels line, 2 pixels space, 10 pixels line, etc.

Returns:

A string or an array of strings representing the line style of the error bar x component if no argument is pass.
A reference to the dataset object from which the method is called upon.

Note: The returned value will be an array even if the style is defined as a function.

Default Value:

The default value for the error bar x line style is "solid".

Error Bar Style y:

This method lets you set or get the style of the error bar y component.

Method:

errorbarStyleY()
errorbarStyleY(option)
errorbarStyleY(option, callback)

Where:

option: represents the line style of the error bar y component. It can be one of the following options:
- A string that represents the style of all error bars.
- An array of strings, each representing the error bar line style at each datapoint.
- A generator function that returns a string representing the error bar line style at each datapoint.
callback: is a function that is run after the error bar style is set but before the next render, this callback accept two optional arguments that represents the dataset object from which the method is called upon and the graph object that is bound to, in that order.

Note: If the style is defined as an array, its length must be the same as the data arrays.

Note: The linechart property generator functions are discussed in deep here.

The style can be represented with one of the following options:

Style	Result
`"solid"`
`"dot"`
`"dash"`
`"long-dash"`
`"dash-dot"`
`"dash-2dot"`

Also, the string can be a list of space separated integers representing line and space length in pixel to form a custom pattern.

For example, the string "3 2 10 2 3" forms a pattern of 3 pixels line, 2 pixels space, 10 pixels line, etc.

Returns:

A string or an array of strings representing the line style of the error bar y component if no argument is pass.
A reference to the dataset object from which the method is called upon.

Note: The returned value will be an array even if the style is defined as a function.

Default Value:

The default value for the error bar y line style is "solid".

Error Bar Width x:

This method lets you set or get the line width of the error bar x component.

Method:

errorbarWidthX()
errorbarWidthX(option)
errorbarWidthX(option, callback)

Where:

option: represents the line width of the error bar x component. It can be one of the following options:
- A number that represents line width of all error bars.
- An array of numbers, each representing the error bar line width at each datapoint.
- A generator function that returns a number representing the error bar line width at each datapoint.
callback: is a function that is run after the error bar line width is set but before the next render, this callback accept two optional arguments that represents the dataset object from which the method is called upon and the graph object that is bound to, in that order.

Note: The width values must be a positive integer.

Note: If the width is defined as an array, its length must be the same as the data arrays.

Note: The linechart property generator functions are discussed in deep here.

Returns:

A number or an array of numbers representing the line width of the error bar x component if no argument is pass.
A reference to the dataset object from which the method is called upon.

Note: The returned value will be an array even if the width is defined as a function.

Default Value:

The default value for the error bar x line width is 1.

Error Bar Width y:

This method lets you set or get the line width of the error bar y component.

Method:

errorbarWidthY()
errorbarWidthY(option)
errorbarWidthY(option, callback)

Where:

option: represents the line width of the error bar y component. It can be one of the following options:
- A number that represents line width of all error bars.
- An array of numbers, each representing the error bar line width at each datapoint.
- A generator function that returns a number representing the error bar line width at each datapoint.
callback: is a function that is run after the error bar line width is set but before the next render, this callback accept two optional arguments that represents the dataset object from which the method is called upon and the graph object that is bound to, in that order.

Note: The width values must be a positive integer.

Note: If the width is defined as an array, its length must be the same as the data arrays.

Note: The linechart property generator functions are discussed in deep here.

Returns:

A number or an array of numbers representing the line width of the error bar y component if no argument is pass.
A reference to the dataset object from which the method is called upon.

Note: The returned value will be an array even if the width is defined as a function.

Default Value:

The default value for the error bar y line width is 1.

Area:

The area dataset is used to show the area between two curves, for example when you need to represent the integral of a given function.

It uses two sets of datapoints, each consisting of two array of numbers representing the [x, y] coordinates of each point.

The two sets of datapoints can be defined to be static or dynamic, meaning that its values can be static and never change or be computed on each draw and even be based on the values of other properties.

If you set any of the datapoint components to be dynamic, that component must be defined by a function of the type:

generator()
generator(dataset)
generator(dataset, graph)

Where:

dataset: is a reference to the dataset from which the function is call upon.
graph: is a reference of the graph that the dataset is bound to.

These two optional arguments always holds the dataset and graph latest state at the moment of the call.

Note: Unlike the callback that most methods accept, the generator function runs on every draw.

First lets create a static area graph.

//Gets the container div element
const element = document.querrySelector("#my-graph");

//Creates and customize the graph object
const my_graph = graph2D(element);

my_graph.axisDomain({
  x : {start : -12, end : 12},
  y : {start : -0.3, end : 1.1}
})
.containerSize({width : 800,  height : 300})
.pointerMove();


//Creates a simple linechart for reference
const line_chart = my_graph.addDataset("linechart");

const line_data_x = linspace(-12, 12, 150);
const line_data_y = line_data_x.map(x => Math.sin(x)/x);

line_chart.dataX(line_data_x).dataY(line_data_y);


//Now creates the area graph.
const area = my_graph.addDataset("area");

//Creates the data arrays
const area_data_x = linspace(-12, 12, 150);
const area_data_y = area_data_x.map(x => Math.sin(x)/x); 

//The area need two sets of data arrays
const area_base_x = [-12, 12];
const area_base_y : [0, 0];

//Add the data to the area graph
area.dataX(area_data_x)
    .dataY(area_data_y)
    .baseX(area_base_x)
    .baseY(area_base_y);

//Finally draws the graph
my_graph.draw();

Result:

Note: linspace is a utility function, you can learn more about this functions on the extras section.

As shown, the area is being drawn between the data and the base curves. In this case, the data curve follows the linechar and the base curve follows the x axis, that is, a straight line from [-12, 0] to [12, 0].

Note: It is not necessary for the base to be a straight line, it can be any arbitrary curve.

Note: It is not necessary for the data and base curves to share the same endpoints or datapoint number, they both are independent.

Now let's recreate the same graph but using dynamic data instead.

//Gets the container div element
const element = document.querrySelector("#my-graph");

//Creates and customize the graph object
const my_graph = graph2D(element);

my_graph.axisDomain({
  x : {start : -12, end : 12},
  y : {start : -0.3, end : 1.1}
})
.containerSize({width : 800,  height : 300})
.pointerMove();


//Creates a simple linechart for reference
const line_chart = my_graph.addDataset("linechart");

//The linechart data remains static
const line_data_x = linspace(-12, 12, 150);
const line_data_y = line_data_x.map(x => Math.sin(x)/x);

line_chart.dataX(line_data_x).dataY(line_data_y);



//Now creates the area graph ans add the data.
const area = my_graph.addDataset("area");

area.dataX((dataset, graph)=>{
  //This function will run on every draw
  //Inside this function, dataset makes reference to line_chart and 
  //graph to my_graph

  const domain = graph.axisDomain(); 

  //The return value must be an array of numbers
  return linspace(domain.x.start, domain.x.end, 150)
})
.dataY( dataset=>{
  //In this case we only need a reference to the dataset

  const x_values = dataset.dataX(); //From here we can get the generated x values

  const y = x_values.map(x=>Math.sin(x)/x);

  //Again, the return value must be an array of numbers
  return y;
} )
.baseX((dataset, graph)=>{
  const domain = graph.axisDomain();

  //In this case only the axis endpoints are need.
  return [domain.x.start, domain.x.end];
})
.baseY([0, 0]);

//Finally draws the graph
my_graph.draw();

Result:

As shown, the graph can be moved indefinitely and the area moves along with it.

Warning: You must not call the dataX() or draw() method from the x data generator because that will create a circular dependency and the program will stop.

Warning: You must not call the dataY() or draw() method from the y data generator because that will create a circular dependency and the program will stop.

Warning: You must not call the baseX() or draw() method from the x base generator because that will create a circular dependency and the program will stop.

Warning: You must not call the baseY() or draw() method from the y base generator because that will create a circular dependency and the program will stop.

It is safe to call every other method from the generator functions.

ID:

This method lets you set or get the id string of the dataset.

Method:

id()
id(option)
id(option, callback)

Where:

option: is a string representing the id of the dataset.
callback: is a function that is run after the id is set but before the next render, this callback accept two optional arguments that represents the dataset object from which the method is called upon and the graph object that is bound to, in that order.

Note: The id is used to identify the dataset, so the string must be unique among other datasets.

By default, the id is generated automatically to guarantee its uniqueness, so in the majority of cases it is best to leave it as it is.

Returns:

A string representing the id of the dataset if no arguments are pass.
A reference to the dataset object from which the method is called upon.

Index:

This method lets you set or get the index of the dataset.

The index is used to determine the order in which the datasets will be drawn. The dataset with the lower index value will be drawn first and appear to be behind other datasets.

Method:

index()
index(option)
index(option, callback)

Where:

option: is a number representing the index value of the dataset.
callback: is a function that is run after the index is set but before the next render, this callback accept two optional arguments that represents the dataset object from which the method is called upon and the graph object that is bound to, in that order.

Note: The draw order of datasets with the same index value will be indeterminate.

Returns:

A number that represents the index of the dataset if no aguments are pass.
A reference to the dataset object from which the method is called upon.

Enable:

This method lets you set or get the enable status of the area.

Method:

enable()
enable(option)
enable(option, callback)

Where:

option: is a boolean that determines whether the area must be enabled.
callback: is a function that is run after the area enable property is set but before the next render, this callback accept two optional arguments that represents the dataset object from which the method is called upon and the graph object that is bound to, in that order.

Returns:

A bolean representing the enable status of the area.
A reference to the dataset object from which the method is called upon.

Default Value:

The default values for the enable property of the area is true.

Dataset Type:

This method returns the area dataset type.

Method:

datasetType()

Returns:

This method always return the string "area".

This is usefull when you read the dataset from the graph2D getDatasets() method or the restoreGraph() function.

Area Data

The data in the area dataset is composed of two different sets each with two arrays of numbers with equal length. Each pair of numbers that share the same index in the arrays represent the [x, y] coordinates of one data point.

Each set of data is independent and are named the data and the base curves. The area is drawn between these two curves.

Each array must be defined independently.

Data x:

This method lets you get ot set the x component of the data curve.

Method:

dataX()
dataX(data)
dataX(data, callback)

Where:

data: represents the x component of the data curve. It can be one of the following options:
- An array of numbers.
- A function that returns an array of numbers. This function can accept two optional parameters in the following order:
  - An object that represents the dataset from which the method is called upon.
  - An object that represents the graph object that the dataset is bound to.
callback: is a function that is run after the data is set but before the next render, this callback accept two optional arguments that represents the dataset object from which the method is called upon and the graph object that is bound to, in that order.

Note: Unlike the callback, If you define the data as a function, that function will be executed on each subsequent draw and the arguments will hold the latest state of the dataset and graph at the moment of the call.

Warning: Neither dataX() nor draw() should be called from within the data function, because that will cause a circular dependency and the program will stop.

When the data is defined as a function, we say that is dynamically generated.

If the data is dynamically generated, its values are updated on each draw. It is important to note that the draw() method only updates the graph if a change is made to it or any of its assets, so if you change an external value, even if that value is used inside the data function, it will not be detected and the data will not update.

Note: The area data generator functions are discussed in deep here.

Returns:

An array of numbers representing the x component of the data curve if no arguments are pass.
A reference to the dataset object from which the method is called upon.

Note: Even when the data is defined as a function, this method will return an array of numbers.

Data y:

This method lets you get ot set the y component of the data curve.

Method:

dataY()
dataY(data)
dataY(data, callback)

Where:

data: represents the y component of the data curve. It can be one of the following options:
- An array of numbers.
- A function that returns an array of numbers. This function can accept two optional parameters in the following order:
  - An object that represents the dataset from which the method is called upon.
  - An object that represents the graph object that the dataset is bound to.
callback: is a function that is run after the data is set but before the next render, this callback accept two optional arguments that represents the dataset object from which the method is called upon and the graph object that is bound to, in that order.

Note: Unlike the callback, If you define the data as a function, that function will be executed on each subsequent draw and the arguments will hold the latest state of the dataset and graph at the moment of the call.

Warning: Neither dataY() nor draw() should be called from within the data function, because that will cause a circular dependency and the program will stop.

When the data is defined as a function, we say that is dynamically generated.

If the data is dynamically generated, its values are updated on each draw. It is important to note that the draw() method only updates the graph if a change is made to it or any of its assets, so if you change an external value, even if that value is used inside the data function, it will not be detected and the base will not update.

Note: The area data generator functions are discussed in deep here.

Returns:

An array of numbers representing the y component of the data curve if no arguments are pass.
A reference to the dataset object from which the method is called upon.

Note: Even when the data is defined as a function, this method will return an array of numbers.

Base x:

This method lets you get ot set the x component of the base curve.

Method:

baseX()
baseX(base)
baseX(base, callback)

Where:

base: represents the x component of the base curve. It can be one of the following options:
- An array of numbers.
- A function that returns an array of numbers. This function can accept two optional parameters in the following order:
  - An object that represents the dataset from which the method is called upon.
  - An object that represents the graph object that the dataset is bound to.
callback: is a function that is run after the data is set but before the next render, this callback accept two optional arguments that represents the dataset object from which the method is called upon and the graph object that is bound to, in that order.

Note: Unlike the callback, If you define the base as a function, that function will be executed on each subsequent draw and the arguments will hold the latest state of the dataset and graph at the moment of the call.

Warning: Neither baseX() nor draw() should be called from within the base function, because that will cause a circular dependency and the program will stop.

When the base is defined as a function, we say that is dynamically generated.

If the base is dynamically generated, its values are updated on each draw. It is important to note that the draw() method only updates the graph if a change is made to it or any of its assets, so if you change an external value, even if that value is used inside the data function, it will not be detected and the data will not update.

Note: The area data generator functions are discussed in deep here.

Returns:

An array of numbers representing the x component of the base curve if no arguments are pass.
A reference to the dataset object from which the method is called upon.

Note: Even when the base is defined as a function, this method will return an array of numbers.

Base y:

This method lets you get ot set the y component of the base curve.

Method:

baseX()
baseX(base)
baseX(base, callback)

Where:

base: represents the y component of the base curve. It can be one of the following options:
- An array of numbers.
- A function that returns an array of numbers. This function can accept two optional parameters in the following order:
  - An object that represents the dataset from which the method is called upon.
  - An object that represents the graph object that the dataset is bound to.
callback: is a function that is run after the base is set but before the next render, this callback accept two optional arguments that represents the dataset object from which the method is called upon and the graph object that is bound to, in that order.

Note: Unlike the callback, If you define the base as a function, that function will be executed on each subsequent draw and the arguments will hold the latest state of the dataset and graph at the moment of the call.

Warning: Neither baseY() nor draw() should be called from within the base function, because that will cause a circular dependency and the program will stop.

When the base is defined as a function, we say that is dynamically generated.

If the base is dynamically generated, its values are updated on each draw. It is important to note that the draw() method only updates the graph if a change is made to it or any of its assets, so if you change an external value, even if that value is used inside the data function, it will not be detected and the base will not update.

Note: The area data generator functions are discussed in deep here.

Returns:

An array of numbers representing the y component of the base curve if no arguments are pass.
A reference to the dataset object from which the method is called upon.

Note: Even when the base is defined as a function, this method will return an array of numbers.

Axis Used:

This method lets you set or get the axis used by the area.

Method:

axisUsed()
axisUsed(options)
axisUsed(options, callback)

Where:

options: is an object containing the following properties:
- x: a string representing the x axis that the dataset is goin to use. It can be "primary" or "secondary".
- y: a string representing the y axis that the dataset is goin to use. It can be "primary" or "secondary".
callback: is a function that is run after the axis used is set but before the next render, this callback accept two optional arguments that represents the dataset object from which the method is called upon and the graph object that is bound to, in that order.

Returns:

An object representing the axis being used by the dataset if no arguments are pass.
A reference to the dataset object from which the method is called upon.

Default Value:

The default values for the axis used property are as follow.

{
  x : "primary",
  y : "primary"
}

Polar:

This method lets you set or get the polar property of the area.

This property controls whether the data and base arrays must be interpreted in rectangular or polar coordinates system.

Method:

polar()
polar(option)
polar(option, callback)

Where:

option: is a boolean that determines whether the data and base must be interpreted in polar coordinates.
callback: is a function that is run after the polar property is set but before the next render, this callback accept two optional arguments that represents the dataset object from which the method is called upon and the graph object that is bound to, in that order.

If the polar property is set to true then:

dataX will be interpreted as the radial coordinates of the data curve.
dataY will be interpreted as the angular coordinates of the data curve.
baseX will be interpreted as the radial coordinates of the base curve.
baseY will be interpreted as the angular coordinates of the base curve.

For example, consider the data arrays:

const r = linspace(1, 1, 200);          //[1,1,1, ..., 1]
const theta = linspace(0, 2*Math.PI, 200);  //[0, 0.042, ..., 6.283]

//Assign the data to the linechart
line_chart.dataX(r).dataY(theta);

//Don't forget to render the new state.
my_graph.draw();

`polar(false)`	`polar(true)`

When the polar property is set to false the area is shows a triengle but the data is correctly interpreted as a full circle of radius one if the polar property is set as true.

Returns:

A boolean that represents the area polar property value if no arguments are pass.
A reference to the dataset object from which the method is called upon.

Default Value:

The default value for the area polar property is false.

Area Properties

Color:

This method lets you set or get the color of the area.

Method:

color()
color(option)
color(option, callback)

Where:

option: is a string representing the color of the area.
callback: is a function that is run after the area color is set but before the next render, this callback accept two optional arguments that represents the dataset object from which the method is called upon and the graph object that is bound to, in that order.

Note: The color can be in the format "#rrggbb" or be any of the standard color names.

Returns:

A string that represents the area color if no arguments are pass.
A reference to the dataset object from which the method is called upon.

Default Value:

The default value for the area color is "#0043e0".

Opacity:

This method lets you set or get the opacity of the area.

Method:

opacity()
opacity(option)
opacity(option, callback)

Where:

opacity: is a number representing the opacity of the area.
callback: is a function that is run after the area opacity is set but before the next render, this callback accept two optional arguments that represents the dataset object from which the method is called upon and the graph object that is bound to, in that order.

Note: The opacity must be a number between 0 and 1.

Returns:

A number that represents the area opacity if no arguments are pass.
A reference to the dataset object from which the method is called upon.

Default Value:

The default value for the area opacity is 0.3.

Heatmap

The heatmap dataset is used to represent two dimensional functions or scalar fields. The field values is represented as a color.

The datapoints in this dataset are represented by three arrays, two of which are used to determine the location of the datapoint, these are call the meshX and meshY arrays and the third stores the value itself, this is the data array.

These arrays have a specific structure: All three are two-dimensional matrices

const data = [
  [1,2,3],
  [4,5,6],
  [7,8,9]
]

That is, and array that holds arrays of numbers. Each of the inner arrays can have different lengths as long that difference is present in meshX, meshY and data at the same location.

Note: The meshX, meshY and data arrays must have the same structure.

The datapoints are characterized with two indices (i, j) that represent the row and column of the matrices.

So the x coordinate of the datapoint is at meshX[i][j], the y coordinate at meshY[i][j] and its value is data[i][j].

The mesh, data and datapoint properties can be defined to be static or dynamic, meaning that its values can be static and never change or be computed on each draw and even be based on the values of other properties.

Example:

First, lets create a static heatmap graph.

//Gets the container div element
const element = document.querrySelector("#my-graph");

//Creates and customize the graph object
const my_graph = graph2D(element);

my_graph.axisPosition("bottom-left")
.primaryGrid({
  grid : {enable : false}
})
.secondaryGrid({
  grid : {enable : false}
})
.containerSize({width : 400, height : 400})
.pointerMove();



//Creates the heatmap
const heat_map = my_graph.addDataset("heatmap");

//Creates the mesh
const x_positions = linspace(-4, 4, 100);
const y_positions = linspace(-4, 4, 100);
const [x_mesh, y_mesh] = meshgrid(x_positions, y_positions);

//Creates the data
const values = [];

for(let i=0; i < x_mesh.length; i++){
  values.push([]);
  for(let j=0; j<x_mesh[i].length; j++){
    const x = x_mesh[i][j];
    const y = y_mesh[i][j];
    const r = Math.hypot(x, y);

    values[i].push(Math.cos(r));    
  }
}

//Add the data to the heatmap
heat_map.meshX(x_mesh).meshY(y_mesh).data(values);

//Finally draws the graph
my_graph.draw();

Result:

Note: linspace and meshgrid are utility functions, you can learn more about this functions on the extras section.

As shown, the heatmap position and values are static and remain unchanged.

Now let's make the mesh dynamic. To do that, we need to define each mesh component as a generator function.

The mesh generator function has the form:

generator()
generator(dataset)
generator(dataset, graph)

Where:

dataset: is a reference to the dataset from which the function is call upon.
graph: is a reference of the graph that the dataset is bound to.

These two optional arguments always holds the dataset and graph latest state at the moment of the call.

Note: Unlike the callback that most methods accept, the generator function runs on every draw.

The mesh generator function must return the mesh values.

We will keep the last script up until the data is add to the heatmap.

//Add the data to the heatmap
heat_map.meshX((dataset, graph)=>{
  //This function will run on every draw
  //Inside this function, dataset makes reference to heat_map and 
  //graph to my_graph

  const domain = graph.axisDomain();

  const x_positions = linspace(domain.x.start+1, domain.x.end-1, 100);
  const y_positions = linspace(domain.y.start+1, domain.y.end-1, 100);
  const [x_mesh, y_mesh] = meshgrid(x_positions, y_positions);

  //The return value must be the x mesh component.
  return x_mesh;
})
.meshY((dataset, graph)=>{
  const domain = graph.axisDomain();

  const x_positions = linspace(domain.x.start+1, domain.x.end-1, 100);
  const y_positions = linspace(domain.y.start+1, domain.y.end-1, 100);
  const [x_mesh, y_mesh] = meshgrid(x_positions, y_positions);

  //This time we return the y mesh component.
  return y_mesh;
})
.data(values);


//Finally draws the graph
my_graph.draw();

Result:

Warning: You may only read static properties and data from dynamic mesh generators, this is because dynamic properties depend on the x and y mesh values, so calling those from a data generator will create a circular dependency and the program will stop.

Warning: You must not call the meshX() ot draw() methods from the x mesh generator because that will create a circular dependency and the program will stop.

Warning: You must not call the meshY() ot draw() methods from the y mesh generator because that will create a circular dependency and the program will stop.

Note: It is safe to call the meshX() method from within the y mesh generator and vice versa.

Now in this case, the mesh moves along with the axis and appears always at the center of the graph, but the heatmap values are still static.

To change that, the data values must be defined as a generator function as well. This function will be call once for each datapoint position and must return a value for that datapoint.

The heatmap data generator can accept some optional parameters that must be call in the next order:

generator(x, y, i, j, meshX, meshY, dataset, graph)

Where:

x: is the x position of the datapoint.
y: is the y position of the datapoint.
i: is the i index corresponding to the x and y values.
j: is the j index corresponding to the x and y values.
meshX: is the complete meshX array.
meshY: is the complete meshY array.
dataset: is a reference to the dataset from which the function is call upon.
graph: is a reference of the graph that the dataset is bound to.

Note: All the arguments of the data generator function are optional.

Note: The data generator operates in a similar way of the array methods (map, forEach, etc).

In our example, instead of defining the data statically, we will use a generator:

heat_map.data((x, y)=>{
  //This function will run on every draw
  //In this case we only need the x and y positions.

  const r = Math.hypot(x,y);

  //Return the data value at each datapoint
  return Math.cos(2*r);
})

//Finally draws the graph
my_graph.draw();

Result:

Warning: You may only read static properties from dynamic data generators, this is because dynamic properties depend on the mesh values, so calling those from a data generator will create a circular dependency and the program will stop.

Warning: You must not call the data() or draw() methods from the data generator because that will create a circular dependency and the program will stop.

As shown, the data moves along with the axis and mesh.

Finally, some properties can be dynamic too. The heatmap property generator function in a similar manner than the data generator.

The function will be called once for each datapoint and must return a suitable property value.

The heatmap property generator can accept some optional parameters that must be call in the next order:

generator(value, x, y, i, j, data, meshX, meshY, dataset, graph)

Where:

value: is the value of the datapoint.
x: is the x position of the datapoint.
y: is the y position of the datapoint.
i: is the i index corresponding to the x and y values.
j: is the j index corresponding to the x and y values.
data: is the complete data array.
meshX: is the complete meshX array.
meshY: is the complete meshY array.
dataset: is a reference to the dataset from which the function is call upon.
graph: is a reference of the graph that the dataset is bound to.

Note: All the arguments of the data generator function are optional.

Note: The data generator operates in a similar way of the array methodds (map, forEach, etc).

In the last script we can add:

heat_map.opacity((value, x, y)=>{
  //This function will run on each draw
  //In this case we only need the datapoint value

  const opacity_map = mapping({ from:[-1,1], to:[0,1] });

  //The generator function must return a suitable value.
  return opacity_map.map(value);
});

//Draw the graph after any change
my_graph.draw();

Result:

Warning: You must not call the draw() method from the property generator because that will create a circular dependency and the program will stop.

Note: mapping is a utility function, you can learn more about this functions on the extras section.

ID:

This method lets you set or get the id string of the dataset.

Method:

id()
id(option)
id(option, callback)

Where:

option: is a string representing the id of the dataset.
callback: is a function that is run after the id is set but before the next render, this callback accept two optional arguments that represents the dataset object from which the method is called upon and the graph object that is bound to, in that order.

Note: The id is used to identify the dataset, so the string must be unique among other datasets.

By default, the id is generated automatically to guarantee its uniqueness, so in the majority of cases it is best to leave it as it is.

Returns:

A string representing the id of the dataset if no arguments are pass.
A reference to the dataset object from which the method is called upon.

Index:

This method lets you set or get the index of the dataset.

The index is used to determine the order in which the datasets will be drawn. The dataset with the lower index value will be drawn first and appear to be behind other datasets.

Method:

index()
index(option)
index(option, callback)

Where:

option: is a number representing the index value of the dataset.
callback: is a function that is run after the index is set but before the next render, this callback accept two optional arguments that represents the dataset object from which the method is called upon and the graph object that is bound to, in that order.

Note: The draw order of datasets with the same index value will be indeterminate.

Returns:

A number that represents the index of the dataset if no aguments are pass.
A reference to the dataset object from which the method is called upon.

Enable:

This method lets you set or get the enable status of the heatmap.

Method:

enable()
enable(option)
enable(option, callback)

Where:

option: is a boolean that determines whether the heatmap must be enabled.
callback: is a function that is run after the heatmap enable property is set but before the next render, this callback accept two optional arguments that represents the dataset object from which the method is called upon and the graph object that is bound to, in that order.

Returns:

A bolean representing the enable status of the heatmap.
A reference to the dataset object from which the method is called upon.

Default Value:

The default values for the enable property of the heatmap is true.

Dataset Type:

This method returns the heatmap dataset type.

Method:

datasetType()

Returns:

This method always return the string "heatmap".

This is usefull when you read the dataset from the graph2D getDatasets() method or the restoreGraph() function.

Heatmap Data

The heatmap uses a set of three two-dimensional matrices, two of which are used to determine the location of the datapoint, these are call the meshX and meshY arrays and the third stores the value itself, this is the data array.

Each matrix must be defined independently.

Mesh X:

This method lets you set or get the heatmap meshX array.

Method:

meshX()
meshX(mesh)
meshX(mesh, callback)

Where:

mesh: represents the x positions of the heatmap datapoints. It can be one of the following options:
- A two-dimensional matrix.
- A function that returns a two-dimensional matrix. This function can accept two optional parameters in the following order:
  - An object that represents the dataset from which the method is called upon.
  - An object that represents the graph object that the dataset is bound to.
callback: is a function that is run after the mesh is set but before the next render, this callback accept two optional arguments that represents the dataset object from which the method is called upon and the graph object that is bound to, in that order.

Note: Unlike the callback, If you define the mesh as a function, that function will be executed on each subsequent draw and the arguments will hold the latest state of the dataset and graph at the moment of the call.

Warning: Neither meshX() nor draw() should be called from within the mesh function, because that will cause a circular dependency and the program will stop.

When the mesh is defined as a function, we say that is dynamically generated.

If the mesh is dynamically generated, its values are updated on each draw. It is important to note that the draw() method only updates the graph if a change is made to it or any of its assets, so if you change an external value, even if that value is used inside the mesh function, it will not be detected and the data will not update.

Note: The heatmap mesh generator functions are discussed in deep here.

Returns:

A two-dimensional matrix representing the x coordinate of the datapoints if no arguments are pass.
A reference to the dataset object from which the method is called upon.

Note: Even when the mesh is defined as a function, this method will return a two-dimensional matrix of numbers.

Mesh Y:

This method lets you set or get the heatmap meshY array.

Method:

meshY()
meshY(mesh)
meshY(mesh, callback)

Where:

mesh: represents the y positions of the heatmap datapoints. It can be one of the following options:
- A two-dimensional matrix.
- A function that returns a two-dimensional matrix. This function can accept two optional parameters in the following order:
  - An object that represents the dataset from which the method is called upon.
  - An object that represents the graph object that the dataset is bound to.
callback: is a function that is run after the mesh is set but before the next render, this callback accept two optional arguments that represents the dataset object from which the method is called upon and the graph object that is bound to, in that order.

Note: Unlike the callback, If you define the mesh as a function, that function will be executed on each subsequent draw and the arguments will hold the latest state of the dataset and graph at the moment of the call.

Warning: Neither meshY() nor draw() should be called from within the mesh function, because that will cause a circular dependency and the program will stop.

When the mesh is defined as a function, we say that is dynamically generated.

If the mesh is dynamically generated, its values are updated on each draw. It is important to note that the draw() method only updates the graph if a change is made to it or any of its assets, so if you change an external value, even if that value is used inside the mesh function, it will not be detected and the data will not update.

Note: The heatmap mesh generator functions are discussed in deep here.

Returns:

A two-dimensional matrix representing the y coordinate of the datapoints if no arguments are pass.
A reference to the dataset object from which the method is called upon.

Note: Even when the mesh is defined as a function, this method will return a two-dimensional matrix of numbers.

Data:

This method lets you set or get the heatmap data array.

Method:

data()
data(data)
data(data, callback)

Where:

data: represents the values of the heatmap datapoints. It can be one of the following options:
- A two-dimensional matrix.
- A function that returns a two-dimensional matrix. This function can accept two optional parameters in the following order:
  - An object that represents the dataset from which the method is called upon.
  - An object that represents the graph object that the dataset is bound to.
callback: is a function that is run after the data is set but before the next render, this callback accept two optional arguments that represents the dataset object from which the method is called upon and the graph object that is bound to, in that order.

Note: Unlike the callback, If you define the data as a function, that function will be executed on each subsequent draw and the arguments will hold the latest state of the dataset and graph at the moment of the call.

Warning: Neither data() nor draw() should be called from within the mesh function, because that will cause a circular dependency and the program will stop.

When the data is defined as a function, we say that is dynamically generated.

If the data is dynamically generated, its values are updated on each draw. It is important to note that the draw() method only updates the graph if a change is made to it or any of its assets, so if you change an external value, even if that value is used inside the data function, it will not be detected and the data will not update.

Note: The heatmap data generator functions are discussed in deep here.

Returns:

A two-dimensional matrix representing the value of the datapoints if no arguments are pass.
A reference to the dataset object from which the method is called upon.

Note: Even when the data is defined as a function, this method will return a two-dimensional matrix of numbers.

Axis Used:

This method lets you set or get the axis used by the heatmap.

Method:

axisUsed()
axisUsed(options)
axisUsed(options, callback)

Where:

options: is an object containing the following properties:
- x: a string representing the x axis that the dataset is goin to use. It can be "primary" or "secondary".
- y: a string representing the y axis that the dataset is goin to use. It can be "primary" or "secondary".
callback: is a function that is run after the axis used is set but before the next render, this callback accept two optional arguments that represents the dataset object from which the method is called upon and the graph object that is bound to, in that order.

Returns:

An object representing the axis being used by the dataset if no arguments are pass.
A reference to the dataset object from which the method is called upon.

Default Value:

The default values for the axis used property are as follow.

{
  x : "primary",
  y : "primary"
}

Heatmap Properties

Color:

This method lets you set or get the color of the heatmap.

Method:

color()
color(option)
color(option, callback)

Where:

option: represents the color at each datapoint. It can be one of the following options:
- A string with the name of any predefined color map. The predefined color maps are:
  - "viridis".
  - "plasma".
  - "magma".
  - "magnet".
  - "inv_magnet".
  - "fairy".
  - "inv_fairy".
  - "swamp".
  - "inv_swamp".
  - "fire".
  - "royal".
  - "hsv".
- A two-dimensional matrix of strings, each representing the color at each datapoint.
- A generator function that returns a string representing the color at each datapoint.
callback: is a function that is run after the color is set but before the next render, this callback accept two optional arguments that represents the dataset object from which the method is called upon and the graph object that is bound to, in that order.

Note: The color string can be in the format "#rrggbb" or be any of the standard color names.

Note: If the color is defined as a marix, its dimensions must be the same as the data arrays.

Note: The heatmap property generator functions are discussed in deep here.

If the color is defined as one of the predefined color maps, it will be considered dynamic. In this case, the color map range will be calculated automatically on each draw to accommodate the data.

This may be misleading if the data range changes constantly.

Returns:

A two-dimensional matrix of strings representing the color at each datapoint if no argument is pass.
A reference to the dataset object from which the method is called upon.

Note: The returned value will be a matrix even if the color is defined as a function.

Default Value:

The default value for heatmap color is "viridis".

Opacity:

This method lets you set or get the opacity of the heatmap.

Method:

opacity()
opacity(option)
opacity(option, callback)

Where:

option: represents the opacity of the heatmap. It can be one of the following options:
- A number that represents the opacity of all datapoints.
- A two-dimensional matrix of numbers, each representing the opacity at each datapoint.
- A generator function that returns a number representing the opacity at each datapoint.
callback: is a function that is run after the opacity is set but before the next render, this callback accept two optional arguments that represents the dataset object from which the method is called upon and the graph object that is bound to, in that order.

Note: The opacity values must be a number between 0 and 1.

Note: If the opacity is defined as a matrix, its dimensions must be the same as the data arrays.

Note: The heatmap property generator functions are discussed in deep here.

Returns:

A number or a two-dimensional matrix of numbers representing the opacity of the heatmap if no argument is pass.
A reference to the dataset object from which the method is called upon.

Note: The returned value will be a matrix even if the opacity is defined as a function.

Default Value:

The default value for heatmap opacity is 1.

Smooth:

This method lets you set or get the smooth property of the heatmap.

If set, the heatmap will perform a pixel-wise bi-linear interpolation of the datapoint properties, resulting in a clearer, less pixelated image.

The accuracy of the final image will depend on the density of datapoints.

Warning: This is a complex computation, so it may harm the responsivity of the application. If you plan to use this feature, is best to avoid contant redraws.

Method:

smooth()
smooth(option)
smooth(option, callback)

Where:

option: is a boolean that determines whether the heatmap should be smooth.
callback: is a function that is run after the smooth property is set but before the next render, this callback accept two optional arguments that represents the dataset object from which the method is called upon and the graph object that is bound to, in that order.

Example:

`smooth(false)`	`smooth(true)`

Returns:

A boolean that represents the smooth property if no arguments are pass.
A reference to the dataset object from which the method is called upon.

Default Value:

The default value for smooth property is false.

Vector Field:

The vectorfield is used to create, as the name implies, two-dimensional vector field graphs. It can calso be used to draw single vectors or arrows.

The datapoints in this dataset are represented by four arrays, two of which are used to determine the location of the datapoint, these are call the meshX and meshY arrays and the other two stores the data values, these are the dataX and dataY arrays.

These arrays have a specific structure: All four are two-dimensional matrices

const data = [
  [1,2,3],
  [4,5,6],
  [7,8,9]
]

That is, and array that holds arrays of numbers. Each of the inner arrays can have different lengths as long that difference is present in meshX, meshY, dataX and dataY at the same location.

Note: The meshX, meshY, dataX and dataY arrays must have the same structure.

The datapoints are characterized with two indices (i, j) that represent the row and column of the matrices.

So the x coordinate of the datapoint is at meshX[i][j], the y coordinate at meshY[i][j], the x component of the vector is at dataX[i][j] and the y component at dataY[i][j].

The mesh, data and datapoint properties can be defined to be static or dynamic, meaning that its values can be static and never change or be computed on each draw and even be based on the values of other properties.

Example:

First, lest create a static vectorfield graph.

//Gets the container div element
const element = document.querrySelector("#my-graph");

//Creates and customize the graph object
const my_graph = graph2D(element);

my_graph.axisDomain({
  x : {start : -3, end : 3},
  y : {start : -3, end : 3}
})
.containerSize({width:400, height:400})
.pointerMove();



//Creates the vectorfield
const vector_field = my_graph.addDataset("vectorfield");

//Creates the mesh
const x_positions = linspace(-3, 3, 23);
const y_positions = linspace(-3, 3, 23);
const [x_mesh, y_mesh] = meshgrid(x_positions, y_positions);

//Creates the data
const x_values = [];
const y_values = [];

for(let i=0; i < x_mesh.length; i++){
  x_values.push([]);
  y_values.push([]);
  for(let j=0; j < x_mesh[i].length; j++){
    const x = x_mesh[i][j];
    const y = y_mesh[i][j];
    
    x_values[i].push(Math.sin(x + y));
    y_values[i].push(Math.cos(x - y));
  }
}

//Add the data to the vectorfield
vector_field.meshX(x_mesh)
.meshY(y_mesh)
.dataX(x_values)
.dataY(y_values);

//Finally draws the graph
my_graph.draw();

Result:

Note: linspace and meshgrid are utility functions, you can learn more about this functions on the extras section.

As shown, the vectorfield position and values are static and remain unchanged.

Now let's make the mesh dynamic. To do that, we need to define each mesh component as a generator function.

The mesh generator function has the form:

generator()
generator(dataset)
generator(dataset, graph)

Where:

dataset: is a reference to the dataset from which the function is call upon.
graph: is a reference of the graph that the dataset is bound to.

These two optional arguments always holds the dataset and graph latest state at the moment of the call.

Note: Unlike the callback that most methods accept, the generator function runs on every draw.

The mesh generator function must return the mesh values.

We will keep the last script up until the data is add to the vectorfield.

//Add the data to the vectorfield
vector_field.meshX((dataset, graph)=>{
  //This function will run on every draw
  //Inside this function, dataset makes reference to vector_field and 
  //graph to my_graph

  const domain = graph.axisDomain();

  const x_positions = linspace(domain.x.start, domain.x.end, 25);
  const y_positions = linspace(domain.y.start, domain.y.end, 25);
  const [x_mesh, y_mesh] = meshgrid(x_positions, y_positions);

  //The return value must be the x mesh component.
  return x_mesh;
})
meshY((dataset, graph)=>{
  const domain = graph.axisDomain();

  const x_positions = linspace(domain.x.start, domain.x.end, 25);
  const y_positions = linspace(domain.y.start, domain.y.end, 25);
  const [x_mesh, y_mesh] = meshgrid(x_positions, y_positions);

  //This time we return the y mesh component.
  return y_mesh;
})
.dataX(x_values)
.dataY(y_values)

//Finally draws the graph
my_graph.draw();

As shown, the mesX and meshY generator function are very similar, so we can condense them into a single function.

//Creates the mesh generator function
function getMesh(graph){
  const domain = graph.axisDomain();

  const x_positions = linspace(domain.x.start, domain.x.end, 23);
  const y_positions = linspace(domain.y.start, domain.y.end, 23);
  const [x_mesh, y_mesh] = meshgrid(x_positions, y_positions);

  return {x_mesh, y_mesh};
}



//Add the data to the vectorfield
vector_field.meshX((dataset, graph)=>getMesh(graph).x_mesh)
meshY((dataset, graph)=>getMesh(graph).y_mesh)
.dataX(x_values)
.dataY(y_values)

//Finally draws the graph
my_graph.draw();

Result:

Warning: You may only read static properties and data from dynamic mesh generators, this is because dynamic properties depend on the x and y mesh values, so calling those from a data generator will create a circular dependency and the program will stop.

Warning: You must not call the meshX() ot draw() methods from the x mesh generator because that will create a circular dependency and the program will stop.

Warning: You must not call the meshY() ot draw() methods from the y mesh generator because that will create a circular dependency and the program will stop.

Note: It is safe to call the meshX() method from within the y mesh generator and vice versa.

Now in this case, the mesh moves along with the axis and appears always at the center of the graph, but the heatmap values are still static.

To change that, the data values must be defined as a generator function as well. This function will be call once for each datapoint position and must return a value for that datapoint.

The vectorfield data generator can accept some optional parameters that must be call in the next order:

generator(x, y, i, j, meshX, meshY, dataset, graph)

Where:

x: is the x position of the datapoint.
y: is the y position of the datapoint.
i: is the i index corresponding to the x and y values.
j: is the j index corresponding to the x and y values.
meshX: is the complete meshX array.
meshY: is the complete meshY array.
dataset: is a reference to the dataset from which the function is call upon.
graph: is a reference of the graph that the dataset is bound to.

Note: All the arguments of the data generator function are optional.

Note: The data generator operates in a similar way of the array methods (map, forEach, etc).

In our example, instead of defining the data statically, we will use a generator:

//vector_field.dataX((x,y)=>{
  //This function will run on every draw
  //In this case we only need the x and y positions.

  const x_value = Math.sin(x + y);

  //The generator must return the x component of the vector
  return x_value;
})
.dataY((x,y)=>{
  const y_value = Math.cos(x - y);

  //In this case the return value will be the y component of the vector
  return y_value;
})

//Finally draws the graph
my_graph.draw();

Result:

Warning: You may only read static properties from dynamic data generators, this is because dynamic properties depend on the mesh values, so calling those from a data generator will create a circular dependency and the program will stop.

Warning: You must not call the dataX() or draw() methods from the x data generator because that will create a circular dependency and the program will stop.

Warning: You must not call the dataY() or draw() methods from the y data generator because that will create a circular dependency and the program will stop.

As shown, the data now moves along with the axis and mesh.

But there is a catch, the vectors appear to change size and rotate as the graph moves. This is because the mesh positions remain constant relative to the graph rect, but no to the axis.

To fix that we need to make shure the mesh values always land on the same position relative to the axis.

The getMesh will be replaced by:

//Creates the mesh generator function
function getMesh(graph){
  const domain = graph.axisDomain();
  const delta = 0.25;
  const x_positions = [];
  const y_positions = [];

  let x_current = Math.floor(domain.x.start);
  while(x_current < Math.ceil(domain.x.end + delta)){
    x_positions.push(x_current);
    x_current += delta;
  }

  let y_current = Math.floor(domain.y.start);
  while(y_current < Math.ceil(domain.y.end + delta)){
    y_positions.push(y_current);
    y_current += delta;
  }

  const [x_mesh, y_mesh] = meshgrid(x_positions, y_positions);

  return {x_mesh, y_mesh};
}

Result:

Finally, some properties can be dynamic too. The vectorfield property generator function in a similar manner than the data generator.

The function will be called once for each datapoint and must return a suitable property value.

The vectorfield property generator can accept some optional parameters that must be call in the next order:

generator(vectorX, vectorY, x, y, i, j, dataX, dataY, meshX, meshY, dataset, graph)

Where:

vectorX: is the value of the datapoint x component.
vectorY: is the value of the datapoint y component.
x: is the x position of the datapoint.
y: is the y position of the datapoint.
i: is the i index corresponding to the x and y values.
j: is the j index corresponding to the x and y values.
dataX: is the complete dataX array.
dataY: is the complete dataY array.
meshX: is the complete meshX array.
meshY: is the complete meshY array.
dataset: is a reference to the dataset from which the function is call upon.
graph: is a reference of the graph that the dataset is bound to.

Note: All the arguments of the data generator function are optional.

Note: The data generator operates in a similar way of the array methodds (map, forEach, etc).

In the last script we can add:

//Create a colormap´
const color = colorMap({
  from : -Math.PI,
  to : Math.PI,
  type : "royal"
});

vector_field.color((x_value, y_value)=>{
  //In this case we can only need the x and y vector values;

  const angle = Math.atan2(y, x);

  //The return value will be assigned to the corresponding datapoint
  return color(angle);
});

my_graph.draw();

Note: colorMap is a utility function, you can learn more about this functions on the extras section.

ID:

This method lets you set or get the id string of the dataset.

Method:

id()
id(option)
id(option, callback)

Where:

option: is a string representing the id of the dataset.
callback: is a function that is run after the id is set but before the next render, this callback accept two optional arguments that represents the dataset object from which the method is called upon and the graph object that is bound to, in that order.

Note: The id is used to identify the dataset, so the string must be unique among other datasets.

By default, the id is generated automatically to guarantee its uniqueness, so in the majority of cases it is best to leave it as it is.

Returns:

A string representing the id of the dataset if no arguments are pass.
A reference to the dataset object from which the method is called upon.

Index:

This method lets you set or get the index of the dataset.

The index is used to determine the order in which the datasets will be drawn. The dataset with the lower index value will be drawn first and appear to be behind other datasets.

Method:

index()
index(option)
index(option, callback)

Where:

option: is a number representing the index value of the dataset.
callback: is a function that is run after the index is set but before the next render, this callback accept two optional arguments that represents the dataset object from which the method is called upon and the graph object that is bound to, in that order.

Note: The draw order of datasets with the same index value will be indeterminate.

Returns:

A number that represents the index of the dataset if no aguments are pass.
A reference to the dataset object from which the method is called upon.

Enable:

This method lets you set or get the enable status of the vectorfield.

Method:

enable()
enable(option)
enable(option, callback)

Where:

option: is a boolean that determines whether the heatmap must be enabled.
callback: is a function that is run after the heatmap enable property is set but before the next render, this callback accept two optional arguments that represents the dataset object from which the method is called upon and the graph object that is bound to, in that order.

Returns:

A bolean representing the enable status of the vectorfield.
A reference to the dataset object from which the method is called upon.

Default Value:

The default values for the enable property of the vectorfield is true.

Dataset Type:

This method returns the vectorfield dataset type.

Method:

datasetType()

Returns:

This method always return the string "vectorfield".

This is usefull when you read the dataset from the graph2D getDatasets() method or the restoreGraph() function.

Vector Field Data

The vectorfield uses a set of four two-dimensional matrices, two of which are used to determine the location of the datapoint, these are call the meshX and meshY arrays and the last two stores the data values. these are the dataX and dataY arrays.

Each matrix must be defined independently.

Mesh X:

This method lets you set or get the vectorfield meshX array.

Method:

meshX()
meshX(mesh)
meshX(mesh, callback)

Where:

mesh: represents the x positions of the vectorfield datapoints. It can be one of the following options:
- A two-dimensional matrix.
- A function that returns a two-dimensional matrix. This function can accept two optional parameters in the following order:
  - An object that represents the dataset from which the method is called upon.
  - An object that represents the graph object that the dataset is bound to.
callback: is a function that is run after the mesh is set but before the next render, this callback accept two optional arguments that represents the dataset object from which the method is called upon and the graph object that is bound to, in that order.

Note: Unlike the callback, If you define the mesh as a function, that function will be executed on each subsequent draw and the arguments will hold the latest state of the dataset and graph at the moment of the call.

Warning: Neither meshX() nor draw() should be called from within the mesh function, because that will cause a circular dependency and the program will stop.

When the mesh is defined as a function, we say that is dynamically generated.

If the mesh is dynamically generated, its values are updated on each draw. It is important to note that the draw() method only updates the graph if a change is made to it or any of its assets, so if you change an external value, even if that value is used inside the mesh function, it will not be detected and the data will not update.

Note: The vectorfield mesh generator functions are discussed in deep here.

Returns:

A two-dimensional matrix representing the x coordinate of the datapoints if no arguments are pass.
A reference to the dataset object from which the method is called upon.

Note: Even when the mesh is defined as a function, this method will return a two-dimensional matrix of numbers.

Mesh Y:

This method lets you set or get the vectorfield meshY array.

Method:

meshY()
meshY(mesh)
meshY(mesh, callback)

Where:

mesh: represents the y positions of the vectorfield datapoints. It can be one of the following options:
- A two-dimensional matrix.
- A function that returns a two-dimensional matrix. This function can accept two optional parameters in the following order:
  - An object that represents the dataset from which the method is called upon.
  - An object that represents the graph object that the dataset is bound to.
callback: is a function that is run after the mesh is set but before the next render, this callback accept two optional arguments that represents the dataset object from which the method is called upon and the graph object that is bound to, in that order.

Note: Unlike the callback, If you define the mesh as a function, that function will be executed on each subsequent draw and the arguments will hold the latest state of the dataset and graph at the moment of the call.

Warning: Neither meshY() nor draw() should be called from within the mesh function, because that will cause a circular dependency and the program will stop.

When the mesh is defined as a function, we say that is dynamically generated.

If the mesh is dynamically generated, its values are updated on each draw. It is important to note that the draw() method only updates the graph if a change is made to it or any of its assets, so if you change an external value, even if that value is used inside the mesh function, it will not be detected and the data will not update.

Note: The vectorfield mesh generator functions are discussed in deep here.

Returns:

A two-dimensional matrix representing the y coordinate of the datapoints if no arguments are pass.
A reference to the dataset object from which the method is called upon.

Note: Even when the mesh is defined as a function, this method will return a two-dimensional matrix of numbers.

Data X:

This method lets you set or get the vectorfield dataX array.

Method:

dataX()
dataX(data)
dataX(data, callback)

Where:

data: represents the values of the vectorfield datapoints. It can be one of the following options:
- A two-dimensional matrix.
- A function that returns a two-dimensional matrix. This function can accept two optional parameters in the following order:
  - An object that represents the dataset from which the method is called upon.
  - An object that represents the graph object that the dataset is bound to.
callback: is a function that is run after the data is set but before the next render, this callback accept two optional arguments that represents the dataset object from which the method is called upon and the graph object that is bound to, in that order.

Note: Unlike the callback, If you define the data as a function, that function will be executed on each subsequent draw and the arguments will hold the latest state of the dataset and graph at the moment of the call.

Warning: Neither dataX() nor draw() should be called from within the mesh function, because that will cause a circular dependency and the program will stop.

When the data is defined as a function, we say that is dynamically generated.

If the data is dynamically generated, its values are updated on each draw. It is important to note that the draw() method only updates the graph if a change is made to it or any of its assets, so if you change an external value, even if that value is used inside the data function, it will not be detected and the data will not update.

Note: The vectorfield data generator functions are discussed in deep here.

Returns:

A two-dimensional matrix representing the value of the datapoints if no arguments are pass.
A reference to the dataset object from which the method is called upon.

Note: Even when the data is defined as a function, this method will return a two-dimensional matrix of numbers.

Data Y:

This method lets you set or get the vectorfield dataY array.

Method:

dataY()
dataY(data)
dataY(data, callback)

Where:

data: represents the values of the vectorfield datapoints. It can be one of the following options:
- A two-dimensional matrix.
- A function that returns a two-dimensional matrix. This function can accept two optional parameters in the following order:
  - An object that represents the dataset from which the method is called upon.
  - An object that represents the graph object that the dataset is bound to.
callback: is a function that is run after the data is set but before the next render, this callback accept two optional arguments that represents the dataset object from which the method is called upon and the graph object that is bound to, in that order.

Note: Unlike the callback, If you define the data as a function, that function will be executed on each subsequent draw and the arguments will hold the latest state of the dataset and graph at the moment of the call.

Warning: Neither dataY() nor draw() should be called from within the mesh function, because that will cause a circular dependency and the program will stop.

When the data is defined as a function, we say that is dynamically generated.

If the data is dynamically generated, its values are updated on each draw. It is important to note that the draw() method only updates the graph if a change is made to it or any of its assets, so if you change an external value, even if that value is used inside the data function, it will not be detected and the data will not update.

Note: The vectorfield data generator functions are discussed in deep here.

Returns:

A two-dimensional matrix representing the value of the datapoints if no arguments are pass.
A reference to the dataset object from which the method is called upon.

Note: Even when the data is defined as a function, this method will return a two-dimensional matrix of numbers.

Axis Used:

This method lets you set or get the axis used by the vectorfield.

Method:

axisUsed()
axisUsed(options)
axisUsed(options, callback)

Where:

options: is an object containing the following properties:
- x: a string representing the x axis that the dataset is goin to use. It can be "primary" or "secondary".
- y: a string representing the y axis that the dataset is goin to use. It can be "primary" or "secondary".
callback: is a function that is run after the axis used is set but before the next render, this callback accept two optional arguments that represents the dataset object from which the method is called upon and the graph object that is bound to, in that order.

Returns:

An object representing the axis being used by the dataset if no arguments are pass.
A reference to the dataset object from which the method is called upon.

Default Value:

The default values for the axis used property are as follow.

{
  x : "primary",
  y : "primary"
}

Vector Field Properties

Color:

This methd lets you set or get the color of the vectorfield.

Method:

color()
color(option)
color(option, callback)

Where:

color: represent the color of the vectorfield. It can be one of the following options:
- A string that represents the color of all datapoints.
- A two-dimensional matrix of strings, each representing the color at each datapoint.
- A generator function that returns a string representing the color at each datapoint.
callback: is a function that is run after the color is set but before the next render, this callback accept two optional arguments that represents the dataset object from which the method is called upon and the graph object that is bound to, in that order.

Note: The color can be in the format "#rrggbb" or be any of the standard color names.

Note: If the color is defined as a marix, its dimensions must be the same as the data arrays.

Note: The vectorfield property generator functions are discussed in deep here.

Returns:

A string or a two-dimensional matrix of strings representing the color at each datapoint if no argument is pass.
A reference to the dataset object from which the method is called upon.

Note: The returned value will be a matrix even if the color is defined as a function.

Default Value:

The default value for vectorfield color is "#303030".

Opacity:

This method lets you set or get the opacity of the vectorfield.

Method:

opacity()
opacity(option)
opacity(option, callback)

Where:

option: represents the opacity of the vectorfield. It can be one of the following options:
- A number that represents the opacity of all datapoints.
- A two-dimensional matrix of numbers, each representing the opacity at each datapoint.
- A generator function that returns a number representing the opacity at each datapoint.
callback: is a function that is run after the opacity is set but before the next render, this callback accept two optional arguments that represents the dataset object from which the method is called upon and the graph object that is bound to, in that order.

Note: The opacity values must be a number between 0 and 1.

Note: If the opacity is defined as a matrix, its dimensions must be the same as the data arrays.

Note: The vectorfield property generator functions are discussed in deep here.

Returns:

A number or a two-dimensional matrix of numbers representing the opacity of the vectorfield if no argument is pass.
A reference to the dataset object from which the method is called upon.

Note: The returned value will be a matrix even if the opacity is defined as a function.

Default Value:

The default value for vectorfield opacity is 1.

Style:

This method lets you set or get the style of the vectorfield.

Method:

style()
style(option)
style(option, callback)

Where:

option: represents the style of the vectorfield. It can be one of the following options:
- A string that represents the style of all datapoints.
- A two-dimensional matrix of strings, each representing the style at each datapoint.
- A generator function that returns a string representing the style at each datapoint.
callback: is a function that is run after the style is set but before the next render, this callback accept two optional arguments that represents the dataset object from which the method is called upon and the graph object that is bound to, in that order.

Note: If the style is defined as an array, its length must be the same as the data arrays.

Note: The vectorfield property generator functions are discussed in deep here.

The style can be represented with one of the following options:

Style	Result
`"solid"`
`"dot"`
`"dash"`
`"long-dash"`
`"dash-dot"`
`"dash-2dot"`

Also, the string can be a list of space separated integers representing line and space length in pixel to form a custom pattern.

For example, the string "3 2 10 2 3" forms a pattern of 3 pixels line, 2 pixels space, 10 pixels line, etc.

Returns:

A string or a two-dimensional matrix of strings representing the style of the vectorfield if no argument is pass.
A reference to the dataset object from which the method is called upon.

Note: The returned value will be a matrix even if the style is defined as a function.

Default Value:

The default value for vectorfield opacity is 1.

Width:

This method lets you set or get the line width of the vectorfield.

Method:

width()
width(option)
width(option, callback)

Where:

option: represents the line width of the vectorfield. It can be one of the following options:
- A number that represents the line width of all datapoints.
- A two-dimensional matrix of numbers, each representing the line width at each datapoint.
- A generator function that returns a number representing the line width at each datapoint.
callback: is a function that is run after the width is set but before the next render, this callback accept two optional arguments that represents the dataset object from which the method is called upon and the graph object that is bound to, in that order.

Note: The width values must be positive integer.

Note: If the width is defined as a matrix, its dimensions must be the same as the data arrays.

Note: The vectorfield property generator functions are discussed in deep here.

Returns:

A number or a two-dimensional matrix of numbers representing the width of the vectorfield if no argument is pass.
A reference to the dataset object from which the method is called upon.

Note: The returned value will be a matrix even if the width is defined as a function.

Default Value:

The default value for vectorfield width is 1.

Normalize:

This method lets you set or get the vectorfield normalize property.

If set, all vectors length will be linearly scale to ensure no one is bigger than maxLength.

Note: This doesn't affect the dataX nor dataY values, only its visual representation.

This facilitates the visualization at the expense of data accuracy.

Method:

normalize()
normalize(option)
normalize(option, callback)

Where:

option: is a boolean that determines whether the normalize property should be enable.
callback: is a function that is run after the normalize property is set but before the next render, this callback accept two optional arguments that represents the dataset object from which the method is called upon and the graph object that is bound to, in that order.

Example:

`normalize(false)`	`normalize(true)`

Returns:

A boolean that represents the normalize property if no arguments are pass.
A reference to the dataset object from which the method is called upon.

Default Value:

The default value for vectorfield normalize is true.

Max Lenght

This method lets you set or get the maxLenght property.

This property represents the max lenght in pixels that any given vector can have.

Method:

maxLength()
maxLength(option)
maxLength(option, callback)

Where:

option: is a number that represents the maxLength property value.
callback: is a function that is run after the normalize property is set but before the next render, this callback accept two optional arguments that represents the dataset object from which the method is called upon and the graph object that is bound to, in that order.

Note: This is only relevant when the normalize property is set to true.

Returns:

A number that represents the maxLength property if no arguments are pass.
A reference to the dataset object from which the method is called upon.

Default Value:

The default value for vectorfield maxLength is 20.

Colorbar

The colorbar is a visual color scale used primarily with the heatmap datasets, but can be used by itself.

It displays a horizontal or vertical bar with a color gradient in it and marks with the values that those colors represent.

For example, consider the following graph.

//Gets the container div element
const element = document.querrySelector("#my-graph");

//Creates and customize the graph object
const my_graph = graph2D(element);

my_graph.axisDomain({
  x : {start : -3, end : 3},
  y : {start : -3, end : 3}
})
.axisPosition("bottom-left")
.containerSize({width:450, height:400});


//Creates a heatmap
const heat_map = my_graph.addDataset("heatmap");

function getMesh(graph){
  const domain = graph.axisDomain();
  
  const x_positions = linspace(domain.x.start, domain.x.end, 100); 
  const y_positions = linspace(domain.y.start, domain.y.end, 100);
  const [x_mesh, y_mesh] = meshgrid(x_positions, y_positions);

  return {x_mesh, y_mesh}; 
}

function peaks(x, y){
  return 3*(1-x)**2 * Math.exp(-(x**2)-(y+1)**2) - 10*(x/5-x**3-y**5) * Math.exp(-(x**2)-(y**2)) - 1/3*Math.exp(-((x+1)**2) - (y**2));
}

//Add the data
heat_map.meshX((dataset, graph)=>getMesh(graph).x_mesh)
.meshY((dataset, graph)=>getMesh(graph).y_mesh)
.data((x,y)=>peaks(x,y))

//Finally, draws the graph.
my_graph.draw();

Result:

To add a color bar to this graph, it's as simple as adding the next code before drawing the graph.

//Creates the colorbar
const color_bar = my_graph.addColorbar();

//Binds the colorbar to the heatmap previously created.
color_bar.data(heat_map.id());

//Because in the default configuration, the margins are
//changed in order to accommodate the colorbar, and we don't want the 
//graph to be distorted.
my_graph.aspectRatio({anchor:0}).draw();

Result:

A title can be easily be added.

color_bar.title({text : "Peaks Function"});

my_graph.aspectRatio({anchor:0}).draw();

Result:

You can change the colorbar position, orientation, font, etc.

It can also be used by itself, without the need to bind it to a heatmap, by setting the colors, position and labels by manually.

ID:

This method lets you set or get the id string of the colorbar.

Method:

id()
id(option)
id(option, callback)

Where:

option: is a string representing the id of the colorbar.
callback: is a function that is run after the id is set but before the next render, this callback accept two optional arguments that represents the colorbar object from which the method is called upon and the graph object that is bound to, in that order.

Note: The id is used to identify the colorbar, so the string must be unique among other colorbars.

By default, the id is generated automatically to guarantee its uniqueness, so in the majority of cases it is best to leave it as it is.

Returns:

A string representing the id of the colorbar if no arguments are pass.
A reference to the colorbar object from which the method is called upon.

Enable:

This method lets you set or get the enable status of the colorbar.

Method:

enable()
enable(option)
enable(option, callback)

Where:

option: is a boolean that determines whether the colorbar must be enabled.
callback: is a function that is run after the colorbar enable property is set but before the next render, this callback accept two optional arguments that represents the colorbar object from which the method is called upon and the graph object that is bound to, in that order.

Returns:

A bolean representing the enable status of the colorbar.
A reference to the colorbar object from which the method is called upon.

Default Value:

The default values for the enable property of the colorbar is true.

Data:

This method lets you set or get the colorbar data.

Method:

data()
data(options)
data(options, callback)

Where:

options: represent the data of the colorbar. It can be one of the following options:
- The id string of a heatmap dataset.
- An array of objects, each of those objects represent one mark in the color bar and must have the following properties:
  - color: a string representing the color of the mark.
  - label: a string with the label of the mark.
  - position: a number represinting the position of the mark in the colorbar.
callback: is a function that is run after the data is set but before the next render, this callback accept two optional arguments that represents the colorbar object from which the method is called upon and the graph object that is bound to, in that order.

Note: The position property must be a number between 0 and 1, being 0 the start of the color bar, and 1 the end.

Note: The color string can be in the format "#rrggbb" or be any of the standard color names.

In case of using an id string, this must belong to a heatmap dataset, and the colorbar will use the entire range of data.

Returns:

An object with the color, label and position of each mark in the colorbar if no argument is pass.
A reference to the colorbar object from which the method is called upon.

Default Value:

There is no default value, if the data is not set, the colorbar will be a blank rectangle.

Position:

This method lets you set or get the colorbar position.

Method:

position()
position(option)
position(option, callback)

Where:

option: represents the colobar position. It can be one of the following options:
- A string with one of the predefined positions:
  - "x-start" will position the colorbar at the left.
  - "x-end" will position the colorbar at the right.
  - "y-start" will position the colorbar at the bottom.
  - "y-end" will position the colorbar at the top.
- An object with the following properties to position the colorbar manually:
  - x: a number with the colorbar x coordinate.
  - y: a number with the colorbar y coordinate.
  - orientation: a string with the colorbar orientation. It can be "vertial" or "horizontal".
callback: is a function that is run after the position is set but before the next render, this callback accept two optional arguments that represents the colorbar object from which the method is called upon and the graph object that is bound to, in that order.

Note: If the position is set to one of the predefined positions, the graph margins will be changed to accommodate the colorbar. This will potentially change the axis aspect ratio.

Note: The x and y values represent the coordinates of the colorbar top left corner relative to the client rect.

Returns:

A string representing the colorbar position if no argument is pass.
A reference to the colorbar object from which the method is called upon.

Note: The returned string will be one of the predefined positions or "floating" if was manually defined.

Default Value:

The default values for the colorbar position is "x-end".

Ticks:

This method lets you set or get the colorbar ticks properties.

Method:

ticks()
ticks(options)
ticks(options, callback)

Where:

options: is an object with the folowing properties:
- density: represents the number of ticks in the colorbar. It can be one of the following options:
  - A number representing the number of ticks.
  - An array of strings, the length of the array will be the number of ticks and the strings the label of each one.
  - An array of objects, each object with the following properties:
    - label: a string representing the label of the tick.
    - position: a number representing the position of the tick.
- color: a string representing the color of the tick.
- opacity: a number representing the opacity of the tick.
- style: a string representing the style of the tick.
- width: a number representing the line width of the tick.
callback: is a function that is run after the ticks values are set but before the next render, this callback accept two optional arguments that represents the colorbar object from which the method is called upon and the graph object that is bound to, in that order.

Note: The density property has no effect if the data is defined manually.

Note: The color can be in the format "#rrggbb" or be any of the standard color names.

Note: The opacity must be a number between 0 and 1.

Note: The width must be a positive integer.

The style can be represented with one of the following options:

Style	Result
`"solid"`
`"dot"`
`"dash"`
`"long-dash"`
`"dash-dot"`
`"dash-2dot"`

Also, the string can be a list of space separated integers representing line and space length in pixel to form a custom pattern.

For example, the string "3 2 10 2 3" forms a pattern of 3 pixels line, 2 pixels space, 10 pixels line, etc.

Returns:

An object with the ticks properties if no argument is pass.
A reference to the colorbar object from which the method is called upon.

Default Values:

The default values for the properties of the ticks method are as follow:

{
  density : 6,
  color : "#000000",
  opacity : 1,
  style : "solid", 
  width : 1
}

Reverse:

This method lets you set or get the colorbar reverse property.

By default, the colorbar shows the values in ascending order starting from the bottom. If the reverse property is set to true, the values will be shown in descending order.

Method:

reverse()
reverse(option)
reverse(option, callback)

Where:

option: is a boolean that determines whether the colorbar should reverse the data.
callback: is a function that is run after the reverse property is set but before the next render, this callback accept two optional arguments that represents the colorbar object from which the method is called upon and the graph object that is bound to, in that order.

Returns:

A bollean that represents the ``colorbar reverse` property if no argument is pass.
A reference to the colorbar object from which the method is called upon.

Default Values:

The default values for the reverse property is false.

Width:

This method lets you set or get the width of the colorbar.

This value affects only the width of the colorbar itself, and not the tick labels or title.

Method:

width()
width(option)
width(option, callback)

Where:

option: is a number that represents the width of the colorbar.
callback: is a function that is run after the width is set but before the next render, this callback accept two optional arguments that represents the colorbar object from which the method is called upon and the graph object that is bound to, in that order.

Note: The width is represented in pixels, so it must be a positive integer.

Note: If the colorbar is in horizontal position, this values will make reference to the colorbar height instead

Returns:

A number that represents the colorbar width if no argument is pass.
A reference to the colorbar object from which the method is called upon.

Default Values:

The default value for the width property is 20.

Size:

This method lets you set or get the size of the colorbar.

This value affects the colorbar height if is in vertical orientation, and the width if is horizontal.

Method:

size()
size(option)
size(option, callback)

Where:

option: is a number representing the colorbar size.
callback: is a function that is run after the size is set but before the next render, this callback accept two optional arguments that represents the colorbar object from which the method is called upon and the graph object that is bound to, in that order.

Note: The size must be a number between 0 and 1.

If the colorbar is in vertical orientation, the size value is relative to the client rect height, being 1 equal to 100% of the client rect height.

If is in horizontal orientation, the value is relative to the cient rect width.

Returns:

A number that represents the colorbar size if no argument is pass.
A reference to the colorbar object from which the method is called upon.

Default Values:

The default value for the size property is 0.93.

Opacity:

This method lets you set or get the opacity of the colorbar.

This value only affects the bar itself and not other elements.

Method:

opacity()
opacity(option)
opacity(option, callback)

Where:

option: is a number that represents the colorbar opacity.
callback: is a function that is run after the opacity is set but before the next render, this callback accept two optional arguments that represents the colorbar object from which the method is called upon and the graph object that is bound to, in that order.

Note: The opacity must be a number between 0 and 1.

Returns:

A number that represents the colorbar opacity if no argument is pass.
A reference to the colorbar object from which the method is called upon.

Default Values:

The default value for the opacity property is 1.

Border:

This method lets you set or get the border properties of the colorbar.

It is only necessary to define the values that you want to change and only that values will be updated, leaving the rest as they are.

Method:

border()
border(options)
border(options, callback)

Where:

options: is an object with the following properties:
- color: a string representing the color of the border.
- opacity: a number representing the opacity of the border.
- style: a string representing the style of the border.
- width: a number representing the line width of the border.
callback: is a function that is run after the border properties are set but before the next render, this callback accept two optional arguments that represents the colorbar object from which the method is called upon and the graph object that is bound to, in that order.

Note: The color can be in the format "#rrggbb" or be any of the standard color names.

Note: The opacity must be a number between 0 and 1.

Note: The width must be a positive integer.

The style can be represented with one of the following options:

Style	Result
`"solid"`
`"dot"`
`"dash"`
`"long-dash"`
`"dash-dot"`
`"dash-2dot"`

Also, the string can be a list of space separated integers representing line and space length in pixel to form a custom pattern.

For example, the string "3 2 10 2 3" forms a pattern of 3 pixels line, 2 pixels space, 10 pixels line, etc.

Returns:

An object with the border properties if no argument is pass.
A reference to the colorbar object from which the method is called upon.

Default Values:

The default values for the properties of the border method are as follow:

{
  color : "#000000",
  opacity : 1,
  style : "solid", 
  width : 1
}

Label:

This method lets you set or get the label properties of the colorbar.

The values set with this method will only affect the text on each tick and not the title.

It is only necessary to define the values that you want to change and only that values will be updated, leaving the rest as they are.

Method:

label()
label(options)
label(options, callback)

Where:

options: is an object containing the following properties:
- font: a string representing the font of the label.
- size: a string representing the size of the label.
- specifier: a string representing the font specifier of the label.
- color: a string representing the color of the label.
- opacity: a number between 0 and 1 representing the opacity of the label.
- position: a string representing the positioning of the label. It can be one of the following values:
  - "start".
  - "end".
callback: is a function that is run after the label is set but before the next render, this callback accept two optional arguments that represents the colorbar object from which the method is called upon and the graph object that is bound to, in that order.

Note: The color can be in the format "#rrggbb" or be any of the standard color names.

Note: The opacity must be a number between 0 and 1

Note: The font value can be any font or stack of fonts available in the browser. Its advised to use safe web fonts.

Note: The size value can be any valid css size including em, rem, etc.

Note: The specifier can be any combination of the following css font properties.

font-style.

font-variant.

font-weight.

font-stretch.

line-height.

Some fonts may not support all specifier options.

The position property has different meaning depending upon the colorbar orientation.

If the colorbar is vertical:

"start" will position the labels at the left of the colorbar.
"end" will position the labels at the right of the colorbar.

If the colorbar is horizontal:

"start" will position the labels at the bottom of the colorbar.
"end" will position the labels at the top of the colorbar.

Returns:

An object with the label properties if no argument is pass.
A reference to the colorbar object from which the method is called upon.

Default Values:

The default values for the properties of the label method are as follow:

{
  color : "#000000",
  font : "Arial, Helvetica Neue, Helvetica, sans-serif",
  size : "10px",
  specifier : "",
  opacity : 1,
  position : "end"
}

Title:

This method lets you set or get the title properties of the colorbar.

It is only necessary to define the values that you want to change and only that values will be updated, leaving the rest as they are.

Method:

 title()
 title(options)
 title(options, callback)

Where:

options: is an object containing the following properties:
- text: a string representing the text of the title.
- font: a string representing the font of the title.
- size: a string representing the size of the title.
- specifier: a string representing the font specifier of the title.
- color: a string representing the color of the title.
- opacity: a number between 0 and 1 representing the opacity of the title.
- position: a string representing the positioning of the title. It can be one of the following values:
  - "start".
  - "end".
- reverse: a boolean that determines whether the text should be reversed.
callback: is a function that is run after the title is set but before the next render, this callback accept two optional arguments that represents the colorbar object from which the method is called upon and the graph object that is bound to, in that order.

Note: The color can be in the format "#rrggbb" or be any of the standard color names.

Note: The opacity must be a number between 0 and 1

Note: The font value can be any font or stack of fonts available in the browser. Its advised to use safe web fonts.

Note: The size value can be any valid css size including em, rem, etc.

Note: The specifier can be any combination of the following css font properties.

font-style.

font-variant.

font-weight.

font-stretch.

line-height.

Some fonts may not support all specifier options.

The position property has different meaning depending upon the colorbar orientation.

If the colorbar is vertical:

"start" will position the title at the left of the colorbar.
"end" will position the title at the right of the colorbar.

If the colorbar is horizontal:

"start" will position the title at the bottom of the colorbar.
"end" will position the title at the top of the colorbar.

By default, the title text is read from bottom to top, the reverse property will reverse that orientation.

Note: The reverse property is only releventa when the colorbar is in vertical orientation.

Returns:

An object with the title properties if no argument is pass.
A reference to the colorbar object from which the method is called upon.

Default Values:

The default values for the properties of the title method are as follow:

{
  text : "",
  color : "#000000",
  font : "Arial, Helvetica Neue, Helvetica, sans-serif",
  size : "12px",
  specifier : "",
  opacity : 1,
  position : "end",
  reverse : false
}

Text:

This method let you set or get the shared text properties from the label and text.

The values set by this method will affect equally the colorbar labels and title.

It is only necessary to define the values that you want to change and only that values will be updated, leaving the rest as they are.

Method:

text()
text(options)
text(options, callback)

Where:

options: is an object containing the following properties:
- font: a string representing the font of both text.
- size: a string representing the size of both text.
- specifier: a string representing the font specifier of both text.
- color: a string representing the color of both text.
- opacity: a number between 0 and 1 representing the opacity of both text.
- position: a string representing the positioning of both text. It can be one of the following values:
  - "start".
  - "end".
callback: is a function that is run after the text properties are set but before the next render, this callback accept two optional arguments that represents the colorbar object from which the method is called upon and the graph object that is bound to, in that order.

Note: The color can be in the format "#rrggbb" or be any of the standard color names.

Note: The opacity must be a number between 0 and 1

Note: The font value can be any font or stack of fonts available in the browser. Its advised to use safe web fonts.

Note: The size value can be any valid css size including em, rem, etc.

Note: The specifier can be any combination of the following css font properties.

font-style.

font-variant.

font-weight.

font-stretch.

line-height.

Some fonts may not support all specifier options.

The position property has different meaning depending upon the colorbar orientation.

If the colorbar is vertical:

"start" will position the text at the left of the colorbar.
"end" will position the text at the right of the colorbar.

If the colorbar is horizontal:

"start" will position the text at the bottom of the colorbar.
"end" will position the text at the top of the colorbar.

Returns:

An object with the text properties if no argument is pass.
A reference to the colorbar object from which the method is called upon.

Default Values:

The default values for the properties of the text method are as follows:

{
  label : {
    color : "#000000",
    font : "Arial, Helvetica Neue, Helvetica, sans-serif",
    size : "10px",
    specifier : "",
    opacity : 1,
    position : "end"
  },
  title : {
    color : "#000000",
    font : "Arial, Helvetica Neue, Helvetica, sans-serif",
    size : "12px",
    specifier : "",
    opacity : 1,
    position : "end"
  }
}

Unit:

This method lets you set or get the unit of the colorbar

The unit is a string that is appended to each label at the right.

Method:

unit()
unit(option)
unit(option, callback)

Where:

option: is a string representing the colorbar unit.
callback: is a function that is run after the unit is set but before the next render, this callback accept two optional arguments that represents the colorbar object from which the method is called upon and the graph object that is bound to, in that order.

Returns:

A string representing the colorbar unit if no argument is pass.
A reference to the colorbar object from which the method is called upon.

Default Value:

The default value for the unit property is "".

Metrics:

This method returns the metrics of the colorbar.

Method:

metrics()

Returns:

An object with the following properties:
- x: The x coordinate of the colorbar.
- y: The y coordinate of the colorbar.
- width: The width of the colorbar.
- height: The height of the colorbar.

Note: The x and y coordinates make reference to the top left corner of the whole colorbar, including the labels and title.

Note: The x and y coordinates are relatives to the client rect.

Note: The width and height values make reference to the width and height of the whole colorbar, including the labels and title.

Legend

The legends are little banners, render at the top of all other information. It shows a legend for each dataset and a little marker to help to identify that dataset.

Each dataset type have a distinct marker, and that marker uses the same styling as the represented dataset.

//Gets the container div element
const element = document.querrySelector("#my-graph");

//Creates and customize the graph object
const my_graph = graph2D(element);

my_graph.axisDomain({
  x : {start : -12, end : 12},
  y : {start : -0.3, end : 1.1}
})
.containerSize({width : 800,  height : 300})
.pointerMove();


//Creates a simple linechart
const line_chart_1 = my_graph.addDataset("linechart");

const data_x_1 = linspace(-12, 12, 150);
const data_y_1 = data_x_1.map(x => Math.sin(x)/x);

line_chart_1.dataX(data_x_1).dataY(data_y_1);


//Now creates the legend
const legend = my_graph.addLegend();

//Adds the datasets to the legend
legend.data([
  {dataset : line_chart_1.id(), text : "sin(x)/x"}
]);

//Finally draws the graph
my_graph.draw();

Result:

As shown, the legend appear at the top right corner of the graph and contain only the linechart mark and label.

We can add as many datasets as we need on the legend. For example:

//Create another linechart
const line_chart_2 = my_graph.addDataset("linechart");

const data_x_2 = linspace(1e-5, 12, 100);
const data_y_2 = data_x_2.map(x => 1/x);

line_chart_2.dataX(data_x_2).dataY(data_y_2).lineColor("#a000eb");


//And adds both datasets to the legend
legend.data([
  {dataset : line_chart_1.id(), text : "sin(x)/x"},
  {dataset : line_chart_2.id(), text : "1/x"}
]);

//Draws the graph
my_graph.draw();

Result

A disabled dataset will not appear in a legend even if is part of its data.

Note: A linechart will not appear in a legend if both the line and markers are disabled. The error bars are not shown in the legend.

Each dataset type has a unique marker.

Type	Marker	Type	Marker
`"linechart"`		`"linechart"`
`"area"`		`"heatmap"`
`"vectorfield"`

The marker takes the color and style from the corresponding dataset.

Note: If the dataset has a dynamic property, the marker will take the first value of that property.

ID:

This method lets you set or get the id string of the legend.

Method:

id()
id(option)
id(option, callback)

Where:

option: is a string representing the id of the legend.
callback: is a function that is run after the id is set but before the next render, this callback accept two optional arguments that represents the legend object from which the method is called upon and the graph object that is bound to, in that order.

Note: The id is used to identify the legend, so the string must be unique among other legends.

By default, the id is generated automatically to guarantee its uniqueness, so in the majority of cases it is best to leave it as it is.

Returns:

A string representing the id of the legend if no arguments are pass.
A reference to the legend object from which the method is called upon.

Enable:

This method lets you set or get the enable status of the legend.

Method:

enable()
enable(option)
enable(option, callback)

Where:

option: is a boolean that determines whether the legend must be enabled.
callback: is a function that is run after the enable property is set but before the next render, this callback accept two optional arguments that represents the legend object from which the method is called upon and the graph object that is bound to, in that order.

Returns:

A bolean representing the enable status of the legend.
A reference to the legend object from which the method is called upon.

Default Value:

The default values for the enable property of the legend is true.

Data:

This method lets you set or get the legend data.

Method:

data()
data(options)
data(options, callback)

Where:

options: is an array of object, each of those representig one entry in the legend. The objects have the following properties:
- dataset: is the id string of the dataset.
- label: is a string representing the label of the dataset.
- text: an object with the text properties of the labels:
  - font: a string representing the font of the label.
  - size: a string representing the size of the label.
  - specifier: a string representing the font specifier of the label.
  - color: a string representing the color of the label.
  - opacity: a number between 0 and 1 representing the opacity of the label.
callback: is a function that is run after the data is set but before the next render, this callback accept two optional arguments that represents the legend object from which the method is called upon and the graph object that is bound to, in that order.

Returns:

An array of object, with the data properties of each dataset if no argument is pass.
A reference to the legend object from which the method is called upon.

Default Values:

The default value for the data is an empty array, but the entries do have default values.

{
  dataset : "",
  label : "",
  text : {
    color : "#000000",
    opacity : 1,
    font : "Arial, Helvetica Neue, Helvetica, sans-serif",
    size : "12px",
    specifier : ""
  }
}

Columns:

This method lets you set or get the columns property of the legend.

All the dataset entries associated with the legend will be display in the amount of columns defined by this method.

Method:

columns()
columns(option)
columns(option, callback)

Where:

option: is a number with the amount of columns in the legend.
callback: is a function that is run after the columns are set but before the next render, this callback accept two optional arguments that represents the legend object from which the method is called upon and the graph object that is bound to, in that order.

Returns:

A number representing the amount of columns in the legend if no argument is pass.
A reference to the legend object from which the method is called upon.

Default Value:

The default value for the columns property is 1.

Position:

This method lets you set or get the legend position.

Method:

position()
position(option)
position(option, callback)

Where:

option: represents the legend position. It can be one of the following options:
- A string with one of the predefined positions:
  - "top-right".
  - "top-left".
  - "bottom-right".
  - "bottom-left".
  - "center".
- An object with the following properties to position the legend manually:
  - x: a number with the legend x coordinate.
  - y: a number with the legend y coordinate.
callback: is a function that is run after the position is set but before the next render, this callback accept two optional arguments that represents the colorbar object from which the method is called upon and the graph object that is bound to, in that order.

Note: The x and y values represent the coordinates of the legend top left corner relative to the graph rect.

Returns:

A string representing the legend position if no argument is pass.
A reference to the legend object from which the method is called upon.

Note: The returned string will be one of the predefined positions or "floating" if was manually defined.

Default Value:

The default values for the legend position is "top-right".

Width:

This method lets you set or get the width property of the legend.

The width value only affects the size of the dataset marker and not the entire legend.

Method:

width()
width(option)
width(option, callback)

Where:

option: is a number representing the width in pixels of the legend markers.
callback: is a function that is run after the width is set but before the next render, this callback accept two optional arguments that represents the legend object from which the method is called upon and the graph object that is bound to, in that order.

Returns:

A number representing the width of the legend markers if no argument is pass.
A reference to the legend object from which the method is called upon.

Default Value:

The default value for the width property is 20.

Title:

This method lets you set or get the title of the legned.

The title will apear at the top of the legend.

Method:

title()
title(options)
title(options, callback)

Where:

options: is an object containing the following properties:
- text: a string representing the text of the title.
- font: a string representing the font of the title.
- size: a string representing the size of the title.
- specifier: a string representing the font specifier of the title.
- color: a string representing the color of the title.
- opacity: a number between 0 and 1 representing the opacity of the title.
- position: a string representing the position of the legend. It can be one of the following options:
  - "start".
  - "center".
  - "end".
callback: is a function that is run after the title is set but before the next render, this callback accept two optional arguments that represents the legend object from which the method is called upon and the graph object that is bound to, in that order.

Returns:

An object with the value of the title properties if no argument is pass.
A reference to the legend object from which the method is called upon.

Default Value:

The default values for the properties of the title method are as follow:

{
  text : "",
  color : "#000000",
  font : "Arial, Helvetica Neue, Helvetica, sans-serif",
  size : "12px",
  specifier : "bold",
  opacity : 1,
  position : "start"
}

Background:

This method lets you set or get the background properties of the legend.

It is only necessary to define the values that you want to change and only that values will be updated, leaving the rest as they are.

Method:

background()
background(options)
background(options, callback)

Where:

options: is an object containing the following properties:
- color: a string representing the background color.
- opacity: a number representing the background opacity.
callback: is a function that is run after the background is set but before the next render, this callback accept two optional arguments that represents the legend object from which the method is called upon and the graph object that is bound to, in that order.

Note: The color can be in the format "#rrggbb" or be any of the standard color names.

Note: The opacity must be a number between 0 and 1.

Returns:

An object with the background property values of the legend if no argument is pass.
A reference to the legend object from which the method is called upon.

Default Value:

The default values for the properties of the background method are as follow:

{
  color : "#ffffff",
  opacity : 1
}

Border:

This method lets you set or get the border properties of the legend.

It is only necessary to define the values that you want to change and only that values will be updated, leaving the rest as they are.

Method:

border()
border(options)
border(options, callback)

Where:

options: is an object with the following properties:
- color: a string representing the color of the border.
- opacity: a number representing the opacity of the border.
- style: a string representing the style of the border.
- width: a number representing the line width of the border.
callback: is a function that is run after the border properties are set but before the next render, this callback accept two optional arguments that represents the colorbar object from which the method is called upon and the graph object that is bound to, in that order.

Note: The color can be in the format "#rrggbb" or be any of the standard color names.

Note: The opacity must be a number between 0 and 1.

Note: The width must be a positive integer.

The style can be represented with one of the following options:

Style	Result
`"solid"`
`"dot"`
`"dash"`
`"long-dash"`
`"dash-dot"`
`"dash-2dot"`

Also, the string can be a list of space separated integers representing line and space length in pixel to form a custom pattern.

For example, the string "3 2 10 2 3" forms a pattern of 3 pixels line, 2 pixels space, 10 pixels line, etc.

Returns:

An object with the border properties if no argument is pass.
A reference to the legend object from which the method is called upon.

Default Values:

The default values for the properties of the border method are as follow:

{
  color : "#000000",
  opacity : 1,
  style : "solid", 
  width : 1
}

Metrics:

This method returns the metrics of the legend.

Method:

metrics()

Returns:

An object with the following properties:
- x: The x coordinate of the legend.
- y: The y coordinate of the legend.
- width: The width of the legend.
- height: The height of the legend.

Note: The x and y coordinates make reference to the top left corner of the legend.

Note: The x and y coordinates are relatives to the graph rect.

Note: The width and height values make reference to the width and height of the legend.

Extras

This library includes some extra functionality to make the use of the graphs easier.

Restore Graph

This function allows you to recreate any graph saved with the graph2D save() method.

Function:

restoreGraph(options)

Where:

options: is an object containing the following properties:
- container: a div element.
- data: the object returned by save().

The container is the div element that is going to host the new graph. It acts as the element argument when creating a graph using the graph2D() function.

Returns:

An object with the following properties:

graph: the new graph2D object.
linechart: An array with all linechart objects present in the graph.
area: An array with all area objects present in the graph.
heatmap: An array with all heatmap objects present in the graph.
vectorfield: An array with all vectorfield objects present in the graph.
colorbar: An array with all colorbar objects present in the graph.
legend: An array with all legend objects present in the graph.

All these objects are ready to go. So you can call the draw() method on the graph object to show the graph.

linspace:

This function creates an array of numbers with n elements from start to end (inclusive).

The resulting values will be equally (linearly) spaced, hence the name.

Function:

linspace(`start`, `end`, `n`)

Note: n must be a positive integer.

Note: The start and end arguments can hold the same vale, the result will be an array with n copies of that value.

Returns:

An array of numbers.

Examples:

linspace(1, 10, 10)  //[1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
linspace(-6, 6, 9)   //[-6, -4.5, -3, -1.5, 0, 1.5, 3, 4.5, 6]
linspace(10, 1, 10)  //[10, 9, 8, 7, 6, 5, 4, 3, 2, 1]
linspace(1, 1, 5)    //[1, 1, 1, 1, 1]

Meshgrid:

This function generates two matrices of numbers representing the rectangular two-dimensional domain given by the x and y arguments.

The values returned by this function are compatible with the meshX() and meshY() methods.

Function:

meshgrid(x, y)

Where:

x: represents the x domain. It can be one of the following options:
- An array of numbers, with each value representing one x coordinate.
- An object with the properties:
  - start: a number representing the start of the x domain.
  - end: a number representing the end of the x domain.
  - n: a number representing the number of times the x domain will be divided into.
y: represents the y domain. It can be one of the following options:
- An array of numbers, with each value representing one y coordinate.
- An object with the properties:
  - start: a number representing the start of the y domain.
  - end: a number representing the end of the y domain.
  - n: a number representing the number of times the y domain will be divided into.

Note: If the x or y arguments are defined as an object, the linspace() function will be used to generate the domain.

A two-dimensional matrix can be acces by two indices M[i][j].

For example:

M = [
      [M11, M12, M13],
      [M21, M22, M23],
      [M31, M32, M33],
    ]

Where i represents the row and j the column of the value.

Returns:

An array with two values, the first being the meshX matrix and the second the meshY.

Example:

const x = linspace(1, 5, 5);    //[1, 2, 3, 4, 5]
const y = linspace(6, 10, 5);   //[6, 7, 8, 9, 10]

const [x_mesh, y_mesh] = meshgrid(x, y);

The resulting values will be:

x_Mesh = [
  [1, 2, 3, 4, 5],
  [1, 2, 3, 4, 5],
  [1, 2, 3, 4, 5],
]

y_Mesh = [
  [10, 10, 10, 10, 10],
  [9, 9, 9, 9, 9], 
  [8, 8, 8, 8, 8], 
  [7, 7, 7, 7, 7], 
  [6, 6, 6, 6, 6],
]

As shown, the meshX matrix contains the x array as its rows and the meshY contains the y array as its columns.

Note: The final dimension of meshX and meshY depend directly on the lenght of x and y.

Mappign:

This function lets you create a mapping object. These objects are primarily used to translate screen coordinates to inner graph coordinates.

This offers a way to pass values from one domain to another using some transformation.

Function:

mapping(options)

Where:

options: is an object that contains the following properties:
- from: an array of two numbers representing the mapping domain.
- to: an array of two numbers representing the mapping range.
- type: a string representing the mapping type. It can be one of the following options:
  - "linear".
  - "log".
  - "sqr".
- base: a number representing the base if using a log transformation.

Returns:

A mapping object with the following properties:

map: a funtion that takes a number from the domain and returns the corresponding range value.
invert: a function that takes a number from the range and returns the corresponding domain value.
domain: an array of two numbes reprenting the domain.
range: an array of two numbes reprenting the range.
type: a string representing the mapping type.
base: a number representing the mapping base.

Example:

const linear_map = mapping({
  from : [0, 1],
  to : [0, 10]
});

console.log( linear_map.map(0) );
console.log( linear_map.map(1) );
console.log( linear_map.map(2) );

console.log( linear_map.invert(10) );
console.log( linear_map.invert(5) );
console.log( linear_map.invert(-5) );

Result:

As shown, values outside the damain (and range) are extrapolated correctly.

Warning: When using the log type the domain must be strictly positive or negative and dont contain the zero.

Warning: When using the str type, the domain must be strictly positive or negative but in this case the zero is allow.

Default Values:

Only the type and base have default values, those values are:

{
  type : "linear",
  base : 10
}

Color Interpolator:

This function creates a simple color interpolator between two color.

This object functions similarly as the mapping object, but this time it maps a number to a color.

Note: Unlike the mapping, the inverse function is not implemented.

Function:

colorInterpolator(options)

Where:

options: is an object with the following properties:
- from: an array of two numbers representing the domain.
- to: an array of two color strings representing the range.
- space: the color space in which the interpolation will be made. Ir can be one of the following options:
  - "rgb".
  - "hsv".
  - "xyx".
  - "lab".
  - "lch".

Warning: Interpolation of numbers outside the domain will be indeterminate.

Note: The colors defined in the range must be in the format "#rrggbb". Standard color names are not supported.

Returns:

A interpolator object with the following properties:

map: a funtion that takes a number from the domain and returns the corresponding color.
domain: an array of two numbes reprenting the domain.
range: an array of two color strings reprenting the range.
space: a string representing the color space used.

Example:

const interpolator = colorInterpolator({
  from : [0, 1],
  to : ["#000000", "#ffffff"]
});

console.log(interpolator.map(0));
console.log(interpolator.map(0.25));
console.log(interpolator.map(0.5));
console.log(interpolator.map(1));

Result:

#000000
#3b3b3b
#777777
#ffffff

The color space used determines the path follow by the interpolator.

For example, consider the interpolation between "#440154" and "#fde724":

space	Interpolation
`"rgb"`
`"hsv"`
`"xyz"`
`"lab"`
`"lch"`

Computation in the rgb space is less expensive than those made in lch space. In general, the complexity follows the last table, being the most 'expensive' spaces at the bottom.

Default Values:

Only the space have default value, this value are:

{
  space : "lch",
}

Color Map:

This function creates a ready to use general purpose color interpolator.

Function:

colorMap(options)

Where:

options: is an object containing the following properties:
- from: a number indicating the domain start.
- to: a number indicating the domain end.
- type: a string representing the colorMap type. It can be one of the following options:
  - "viridis".
  - "plasma".
  - "magma".
  - "magnet".
  - "inv_magnet".
  - "fairy".
  - "inv_fairy".
  - "swamp".
  - "inv_swamp".
  - "fire".
  - "royal".
  - "hsv".

Warning: Interpolation of numbers outside the domain will be indeterminate.

Returns:

A function that takes a number from the domain and returns the corresponding color.

Example:

const color_map = colorMap({
  from : 0,
  to : 1,
  type : "plasma"
});

console.log(color_map(0));
console.log(color_map(0.25));
console.log(color_map(0.5));
console.log(color_map(1));

Result:

#440154
#9e0059
#e24648
#fde724

The colormap types are organized in the following categories.

Sequential

type	Result
`"viridis"`
`"plasma"`
`"magma"`

Diverging

type	Result
`"magnet"`
`"swamp"`
`"fairy"`
`"inv-magnet"`
`"inv-swamp"`
`"inv-fairy"`

Cyclic

type	Result
`"fire"`
`"royal"`
`"hsv"`

License

MIT License

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Name		Name	Last commit message	Last commit date
Latest commit History 210 Commits
assets		assets
dist		dist
src		src
user-test		user-test
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
README.md		README.md
graph_image.jpg		graph_image.jpg
package-lock.json		package-lock.json
package.json		package.json
tsconfig.es5.json		tsconfig.es5.json
tsconfig.json		tsconfig.json

JhoselinRam/scigrapher

Folders and files

Latest commit

History

Repository files navigation

SciGrapher.js

What do I mean with "scientific oriented"?

Table of Contents

Installation

Usage

Graph Methods

Background

Color:

Opacity:

Axis

Position:

Type:

Domain:

Color:

Opacity:

Units:

Base:

Ticks:

Text:

Dynamic

Overlap

Secondary Enable:

Seocndary Domain:

Secondary Color:

Secondary Opacity:

Secondary Units:

Secondary Base:

Secondary Ticks:

Secondary Text:

Secondary Type:

Grid

Color:

Opacity:

Style:

Width:

Primary:

Secondary:

Polar:

Labels

Title:

Subtitle:

x Label:

y Label:

Secondary x Label:

Secondary y Label:

Utilities

Pointer Move:

Pointer Zoom:

Container Resize:

Aspect Ratio:

Graph Properties

Margin:

Border:

Container Size:

Readonly Methods

Draw:

Canvas Elements:

Client Rect:

Graph Rect:

Coordinate Maps:

Save:

Assets:

Add Dataset:

Get Datasets

Remove Dataset

Add Colorbar:

Get Colorbars

Remove Colorbar

Add Legend:

Get Legends

Remove Legend

Datasets

Line Chart:

ID:

Index: