svelte-plots-basic 1.1.4 → 2.1.0

package/README.md

@@ -1,8 +1,22 @@
-# Svelte plots
+# Svelte components for creating plots
+
+The library is under development and breaking changes may occur in the coming versions.
+
+## News
+
+New major release (v. 2.0.0) introduces many breaking changes as the library was completely re-written. If you use previous versions of `svelte-plots-basic` in your projects, and do not want to change anything, stick to the latest 1.x.x version (v. 1.1.4).
+
+### 2.1.0
+
+* Added new elements, `Heatmap` and `ColormapLegend`.
+* Improvements to tick labels, in particular if values are too small (< 0.01) or too large (>99) the values are adjusted and a common factor is shown at the end of axis. This is applied only to automatic ticks, manually provided ticks and tick labels are shown as is.
+* Small improvements and bug fixes.
 
 ## Description
 
-`svelte-plots-basic` is a [Svelte](https://svelte.dev) component library for creating very simple 2D plots/charts. It is currently under active development and breaking changes may occur. In its current state (v. 1.1.4) it allows to create bar, scatter, area and line charts as well as any combination of the four. The charts are created using [SVG](https://en.wikipedia.org/wiki/Scalable_Vector_Graphics) and are re-scalable.
+`svelte-plots-basic` is a [Svelte](https://svelte.dev) component library for creating simple 2D and 3D plots/charts. The plots are created by generating [SVG](https://en.wikipedia.org/wiki/Scalable_Vector_Graphics) inside HTML document and are re-scalable.
+
+The library provides building blocks for creating plots, one can think of this library as "Lego" bricks for plots. It has two groups of components: for 2D and for 3D plots. In addition to `svelte` the library has one direct dependence, [mdatools-js](https://github.com/svkucheryavski/mdatools-js) library which is used for vector/matrix operations, statistics, and other manipulations with data values.
 
 
 ## Installation
@@ -19,113 +33,91 @@ or, to install it with yarn:
 yarn add -D svelte-plots-basic
 ```
 
+## Demo
 
+There is on-line demo site with some examples of what you can do with the library: [https://mda.tools/svelteplotsdemo/](https://mda.tools/svelteplotsdemo/). All examples from this demo are available in corresponding GitHub repo: [](). Use code of the examples for inspiration and as a tutorial, although some basic information is also available below.
 
-## Quick start
+## Quick start (2D plots)
 
 It is assumed that you already know the basics of Svelte.
 
-Just create a new Svelte app following the [quick start guide](https://svelte.dev/blog/the-easiest-way-to-get-started). Then open `App.svelte` file, delete everything and write the following code, which creates a simple bar chart:
+Just create a new Svelte app following the [quick start guide](https://svelte.dev/blog/the-easiest-way-to-get-started). Then open `App.svelte` file, delete everything and write the following code, which creates a simple 2D bar chart:
 
-```js
+```svelte
 <script>
-   import {Axes, BarSeries} from 'svelte-plots';
+   import {Axes, XAxis, YAxis, Box, BarSeries} from 'svelte-plots-basic';
 
    // test data for the plot
    const years = [2010, 2020, 2030, 2040, 2050];
    const amount = [100, 200, 150, 300, -100];
 </script>
 
-<div class="plot">
-   <Axes>
+<div class="plot-container">
+<Axes limX={[2005, 2055]} limY={[-150, 350]} margins={[1, 1, 0.5, 0.5]}xLabel="Years" yLabel="Income">
+
       <BarSeries
-         title="Economy"
-         showLabels="no"
          faceColor="#e0e0e0"
-         edgeColor="#e0e0e0"
-         labels={years}
+         edgeColor="#909090"
          xValues={years}
          yValues={amount}
       />
+
+      // x and y axis with automatic ticks and grid lines
+      <XAxis slot="xaxis" />
+      <YAxis slot="yaxis" />
+
+      // box around the axes
+      <Box slot="box" />
+
    </Axes>
 </div>
+
+<style>
+   .plot-container {
+      width: 100%;
+      height: 100%;
+      min-width: 200px;
+      min-height: 200px;
+   }
+</style>
 ```
 
 Then run `npm run dev` in terminal and open the URL provided by npm in browser. That is it.
 
-Example below shows how to create a plot with axis, box and grid as well as how to combine several plot series together.
+You can also use all capabilities of the `mdatools` package, e.g. generated random numbers:
 
-```js
+```svelte
 <script>
-   import {Axes, BarSeries} from 'svelte-plots';
+   import { Axes, BarSeries } from 'svelte-plots-basic';
+   import { Vector } from 'mdatools/arrays';
 
-   // test data for the plot
-   const years = [2010, 2020, 2030, 2040, 2050];
-   const amount = [100, 200, 150, 300, -100];
+   // generate random values from normal distribution
+   const x = Vector.randn(200, 0, 1);
+   const y = Vector.randn(200, 0, 2);
 </script>
 
-<div class="plot">
-   <Axes>
+<div class="plot-container">
+   <Axes limX={[-6, 6]} limY={[-5, 6]} xLabel="x" yLabel="y">
 
-      // bar, line and marker series with the same data values
-      <BarSeries
-         showLabels="no"
-         faceColor="#eee"
-         edgeColor="#eee"
-         xValues={years}
-         yValues={amount}
-      />
-      <LineSeries
-         lineColor="blue"
-         lineWidth={2}
-         xValues={years}
-         yValues={amount}
-      />
       <ScatterSeries
-         marker="✺"
-         showLabels="hover"
-         markerColor="blue"
-         labels={years}
-         xValues={years}
-         yValues={amount}
+         xValues={x}
+         yValues={y}
       />
 
       // x and y axis with automatic ticks and grid lines
-      <XAxis showGrid={true} slot="xaxis" />
-      <YAxis showGrid={true} slot="yaxis" />
+      <XAxis slot="xaxis" />
+      <YAxis slot="yaxis" />
 
       // box around the axes
       <Box slot="box" />
+
    </Axes>
 </div>
 ```
 
-## Details
-
-The library has following components:
-
-### Axes
-
-`Axes` this is a main component, which is responsible for showing all other plot elements (axis, labels, titles, primitives, series, etc.). The `Axes` component must be always a parent for all other components. It has four optional parameters:
-
-* `limX`  — vector with two values - x-axis limits (min and max) in plot units.
-* `limY`  — vector with two values - y-axis limits (min and max) in plot units.
-* `title` — a text to be shown as a plot title (on top of the plot).
-* `xLabel` — a label for x-axis (shown under the axis).
-* `yLabel` — a label for y-axis (shown on the right side of the axis).
-
-If limits are not provided, the component will compute them automatically when/if you add one or several plot series. If you want to show axes without any series or use primitives instead, you need to provide the values for limits explicitly.
-
-The `Axes` operates in two coordinate systems. One is related to plot units. For example if you make a scatter plot for Height vs Weight of people, then the x-units will be cm and y-units will be kg. The x-axis will be directed from left to right and y-axis from bottom to up, like in conventional plots. The component then will automatically recompute the coordinates of all plot elements from the plot units to pixels, depending on the current size of the plot shown in browser.
-
-### XAxis and YAxis
+See demo for more details.
 
-Each component is responsible for visualization of the corresponding axis. The axis is shown in form of a line with outer ticks and related labels. Number of ticks and their values are computed automatically until you do not specify them as a component parameter. Each component has two optional parameters:
+## Quick start (3D plots)
 
-* `ticks` — vector with ticks
-* `tickLabels` — vector with values to be shown as labels beside each tick
-* `showGrid` — a logical parameter, which allows to show grid lines on the plot
-* `slot` — name of the slot, `"xaxis"` or `"yaxis"`
 
-The components must be placed in a particular slot of the parent `Axes` component.
 

package/package.json

@@ -1,17 +1,23 @@
 {
    "name": "svelte-plots-basic",
    "description": "Svelte components for creating simple plots",
-   "version": "1.1.4",
+   "version": "2.1.0",
    "author": "Sergey Kucheryavskiy",
    "license": "MIT",
    "private": false,
-   "main": "src/index.js",
-
+   "exports": {
+      "./2d":  "./src/2d/index.js",
+      "./2d/*.svelte":  "./src/2d/*.svelte",
+      "./3d":  "./src/3d/index.js",
+      "./3d/*.svelte":  "./src/3d/*.svelte"
+   },
    "dependencies": {
-      "mdatools": "^0.6.1"
+      "mdatools": "^1.x.x"
    },
    "keywords": [
       "svelte",
+      "plots",
+      "charts",
       "svelte plots"
    ],
    "files": [

package/src/2d/Area.svelte

@@ -0,0 +1,61 @@
+<script>
+   /****************************************************
+   * Area                                              *
+   * --------------------                              *
+   * shows area of a polygon defined by set of points  *
+   *****************************************************/
+
+   import { getContext } from 'svelte';
+   import { vector } from 'mdatools/arrays';
+   import { Colors } from '../Colors';
+   import { checkCoords, val2p } from '../Utils';
+
+
+   /*****************************************/
+   /* Input parameters                      */
+   /*****************************************/
+
+	export let xValues;                       // x-coordinates of polygon (array or vector)
+   export let yValues;                       // y-coordinates of polygon (array or vector)
+   export let lineWidth = 1;                 // width of polygon lines
+   export let lineColor = Colors.PRIMARY;    // color for polygon lines
+   export let fillColor = Colors.PRIMARY;    // color of area inside polygon
+   export let opacity = 1;                   // opacity of the area color
+   export let lineType = 1;                  // type of lines connected the points (1 - solid, 2 - dashed, 3 - dotted)
+   export let title = '';                    // title of this element (reserved for future use)
+
+
+   /*****************************************/
+   /* Component code                        */
+   /*****************************************/
+
+   // get axes context
+   const axes = getContext('axes');
+
+   const scale = axes.scale;
+   const isOk = axes.isOk;
+   const tX = axes.tX;
+   const tY = axes.tY;
+
+   // reactive variables for coordinates of data points in pixels
+   let p, xs, y0, xe = undefined;
+   $: {
+
+      if ($isOk) {
+         const xv = checkCoords(xValues, 'AreaSeries');
+         p = val2p(xv, yValues, $tX, $tY, axes);
+         y0 = axes.transform(vector([0]), $tY.coords)[0];
+         xs = axes.transform(xv.subset(1), $tX.coords)[0];
+         xe = axes.transform(xv.subset(xValues.length), $tX.coords)[0];
+      }
+   }
+
+   $: areaStyleStr = `opacity:${opacity};fill:${fillColor};stroke:${lineColor};stroke-width: ${lineWidth}px;stroke-dasharray:${axes.LINE_STYLES[$scale][lineType - 1]}`;
+</script>
+
+{#if $isOk && p !== undefined}
+   <g class="series series_area" style={areaStyleStr} title={title}>
+   <polygon points="{xs + "," + y0 + " " + p + " " + xs + "," + y0}"/>
+   </g>
+{/if}
+