src/overview.ts

   1/**

   2# hsGraph

   3

   4Helpful Scripts Graph plotting functions. 

   5[`[Github page]`](https://github.com/HelpfulScripts/hsGraph)

   6[`[Coverage Info]`](./data/src/hsGraph/coverage/)

   7___

   8

   9hsGraph is a simple graphing utility written in JavaScript and based on the [Mithril](https://mithril.js.org) framework.

  10It supports various chart types and scales and provides a convenient programmatic configuration mechanism. 

  11

  12## Usage

  13In mithril, simply render or mount a {@link Graph Graph} Component object and provide a `cfg`

  14attribute with the graph's configuration.

  15

  16## Setting the data to render

  17 Data is provided in a rows-of-columns style array: `data[row][column]`.

  18 The first row in the data array contains column names by which the series can be identified.

  19 There is no conceptual limit to the number of rows or columns provided to `hsGraph`.

  20 In the configuration, 

  21 - set the array containing the data: `series.data = data;`  

  22 - and specify the x- and y-columns to render, by name: `series.series = [{xHeader:, yHeader:}]`

  23

  24## Configuration

  25All graph components are highly configurable. `hsGraph` uses default values for all configurable fields 

  26that can easily be changed, either programmatically or via a custom stylesheet.

  27

  28There are two ways to programmatically set rendering parameters.

  291. change the deafult configuration style or color. This will change the default for all 

  30subsequently drawn graphs

  31```

  32hsgraph.Series.defaultStyle.line.width  = 10;

  33```

  342. provide a configuration function `cfg => {}` to the `cfgFn` attribute 

  35when setting up the mithril mount call - see example below. The `cfgFn` 

  36receives a configuration object that is fully initialized with default values, 

  37and should overwrite parameters as needed. See the overview for each component 

  38for configurable parameters. Example:

  39```

  40* cfg => {

  41*     ...

  42*     cfg.series.series[0].style.line.width = 10;

  43* }

  44```

  45

  46

  47

  48Available configuration options and their default settings are documented in:

  49-   {@link Graph.Graph.defaultConfig Graph.defaultConfig }

  50-   {@link Canvas.Canvas.defaultConfig Canvas.defaultConfig}

  51-   {@link Chart.Chart.defaultConfig Chart.defaultConfig}

  52-   {@link Axes.Axes.defaultConfig Axes.defaultConfig}

  53-   {@link Grid.Grid.defaultConfig Grid.defaultConfig}

  54-   {@link Series.Series.defaultConfig Series.defaultConfig}

  55-   {@link Legend.Legend.defaultConfig Legend.defaultConfig}

  56

  57## Graph Components

  58The rendered graph is organized in a layered structure of components:

  59-   {@link Canvas Canvas}:  the background canvas on which all components are rendered

  60-   {@link Chart Chart}: the chart area and title

  61-   {@link Axes Axes}: the x- and y-axes, tick marks and labels, and axis title

  62-   {@link Grid Grid}: the major and minor gridlines

  63-   {@link Series Series}: the one or more data series to render

  64-   {@link Legend Legend}: the legend for the shown series

  65

  66## Supported Plot Types

  67 * 

  68 * script.js'>

  69 * // set a few defaults:

  70 * hsgraph.Series.defaultStyle.line.width = 6;

  71 * hsgraph.Series.defaultStyle.bar.width  = 20;

  72 * hsgraph.Series.defaultStyle.bar.offset = 25;

  73 * hsgraph.Series.defaultColors[0] = 'rgba(255, 0, 0, 0.5)';

  74 * hsgraph.Series.defaultColors[1] = 'rgba(0, 255, 0, 0.5)';

  75 * 

  76 * // define a data sest:

  77 * let series = {

  78 *    colNames:['date', 'time', 'volume', 'costs'],

  79 *    rows:[['1/1/14', -1,  0.2, 0.3], ['1/1/16', 0.2, 0.7, 0.2], ['9/1/16', 0.4, 0.1, 0.3],

  80 *          ['5/1/17', 0.6, 0,   0.1], ['7/1/18', 0.8, 0.3, 0.5], ['1/1/19', 1,   0.2, 0.4]]

  81 * };

  82 * 

  83 * // configure the plot:

  84 * const config = (cfg, x_values, type) => {

  85 *      cfg.axes.primary.x.title.text = x_values || 'index';

  86 *      cfg.axes.primary.x.title.vOffset = -1;

  87 *      cfg.series.data      = [series];

  88 *      cfg.series.series    = [

  89 *         { x:x_values, y:'volume', type:type },

  90 *         { x:x_values, y:'costs', type:type }

  91 *      ];

  92 *      if (type==='marker') { // show labels

  93 *         cfg.series.series[0].l = 'volume'; 

  94 *         cfg.series.series[1].l = 'costs'; 

  95 *      }

  96 * }

  97 * 

  98 * // layout each plot with title and graph:

  99 * const plot = (x_values, type, link) => m(hslayout.Layout, {

 100 *    rows: ['40px', 'fill'], 

 101 *    content: [

 102 *       m('h4', [m('a', {href:`#!/api/hsGraph/hsGraph.${link}`}, `${type} plot:`)]), 

 103 *       m(hsgraph.Graph, {cfgFn: cfg => config(cfg, x_values, type)

 104 *       }),

 105 * ]});

 106 *  

 107 * // mount view and layout examples:

 108 * m.mount(root, { view:() => m('.hs-white', m(hslayout.Layout, {

 109 *    rows: [], content: [

 110 *       plot('time',    'marker', 'PlotMarkers'), 

 111 *       plot('date',    'line',   'PlotLine'), 

 112 *       plot('time',    'area',   'PlotArea'), 

 113 *       plot('time',    'bar',    'PlotBar'),

 114 *       plot(undefined, 'bar',    'PlotBar')

 115 * ]}))});

 116 * 

 117 * style.css'>

 118 * 

 119 * 

 120*/

 121

 122/** */