emerald-plotly-react v1.0.14

emerald-plotly-react

emerald-plotly-react is an extension to the renowned data visualization library, Plotly. Our module is designed to enhance and simplify your data visualization experience by offering additional functionality that seamlessly integrates with Plotly's core features.

Key Features

• Separation of concerns: We've innovated the way you handle plot specifications and data transformations. With emerald-plotly-react, you can independently define what to plot and how to plot it, streamlining the process of creating complex visualizations with multiple subplots.
• Flexible layout: Customize your plot layouts with ease. Our enhanced layout configurations offering additional flexibility, giving you more control over your visualization's appearance.
• Zoom management: Additional zoom functionality.
• Subplot editor: Allowing to plot multiple subplots with an editor based on json-editor that makes it possible to edit the subplot traces on the fly.
• Customisable subplot menu: Each subplot has a custom menu which you can add as many custom items you want to.

Installation guide

Installing emerald-plotly-react is straightforward using npm. Here's how you can add it to your project:

Navigate to your project directory

• Use the cd command to go to the directory where you want to install emerald-plotly-react.

Install

npm install emerald-plotly-react

Verify the Installation

• After installation, you can check your node_modules folder to see if emerald-plotly-react and its dependencies have been installed correctly.

Getting Started

Here is a full Example Project

To help you get started with emerald-plotly-react, here's an example of how you can use the BasePlot component within a React application:

import React, { useState } from "react";
import { BasePlot } from "emerald-plotly-react";

const element_radtemp = {
  fn: function (context, args) {
    return [
      {
        type: "scattergl",
        x: context.radial.dist,
        y: context.radial.temp,
      },
    ];
  },
  xaxis: "dist",
  yaxis: "temp",
  schema: (context) => {
    // Json-schema for `args` parameter to `fn` above, used to generate a form in the edit menu.
    return {
      type: "object",
      required: [],
      properties: {},
      additionalProperties: false,
    };
  },
};

export const elements = {
  traces: { "Radial temperature": element_radtemp },
  xaxis: {
    // Units used on x-axes
    dist: {
      title: { text: "distance (m)" },
    },
  },
  yaxis: {
    // Units used on y-axes
    temp: {
      title: {
        text: "temperature (deg c)",
      },
    },
  },
};

const initial_layout = {
  layout: {
    grid: {
      columns: 2,
      pattern: "independent",
      roworder: "bottom to top",
      rows: 2,
      subplots: [
        ["xy", "x2y2"],
        ["x3y3", "x4y4"],
      ],
      xgap: 0,
      ygap: 0.0,
    },
  },
  traces: [{ "Radial temperature": { xaxis: "x", yaxis: "y" } }],
};

const PlotContainer = () => {
  const [plotLayout, setPlotLayout] = useState(initial_layout);

  // Data that can be plotted; typically you'd use typed arrays here
  let context = {
    radial: {
      dist: [1, 2, 3],
      temp: [30.2, 31.3, 30.9],
    },
  };

  return (
    <div style={{ width: "100%", height: "100%" }}>
      <BasePlot
        context={context}
        plot={structuredClone(plotLayout)} // Deep copy of plot layout to avoid direct state mutation
        setPlot={setPlotLayout}
        elements={elements}
      />
    </div>
  );
};

export default PlotContainer;

Architecture

A plot layout consists of plot a set of subplots, each subplot holding any number of plot elements. Each plot element (e.g. element_radtemp in the example above) can be used multiple times in the same subplot with different parameters. Data used by the plot elements is stored in a context object. Each plot element has a specific unit of measure for their x and y axis, and only plot elements that share the same units for their axes can be plotted in the same subplot (or, if subplots share axes, in subplots that share that axis).

Plot elements

A plot element defines how to plot some data. It consist of an object with a few required (and some optional) properties and methods: xaxis, yaxis, fn, schema. xaxis and yaxis give the units of measure for the two axes (note: not the actual axes of whatever subplot this is used in). fn generates a list of plotly traces to be plotted given a context object and optional arguments. schema finally gives a JSON-schema for the optional arguments of fn.

Plot context

The plot context is an object that holds all data that can be plotted. No particular structure is enforced for the plot context object. It is available to all plot element methods.

Units

As mentioned above, plot elements need to specify the units of measure of the two axes. No special syntax is enforced for this, and you can just make up names. They are matched against the unit names of other elements the user tries to add to the same subplot, and only elements with the same units are allowed to share the same axis. Additionally, plotly axis configuration (such as text styling, title, tick marks etc) can be applied to each unit.

Layouts

A layout is an object that specifies a plotly layout and a set of plot element instances to plot. The layout can be modified by the use using the cogwheel menu on each subplot and colorbar. It therefore needs to live in a react state, and you can easily implement save/load functionality for the user as it is a pure JS object that can be serialized to JSON.

BasePlot Component API Reference

The BasePlot component is a wrapper around Plotly's Plot component, integrating custom subplot management, zoom control, and dynamic plot updating.

Additional Menu Items Example

The BasePlot component allows for the addition of custom menu items. Below is an example demonstrating how to define and use additionalMenuItems:

Defining Custom Menu Items

First, define your custom menu items. You can include icons and specify click event handlers:

const extraMenuItems = [
  {
    icon: <ion-icon name="heart-outline"></ion-icon>, // Icon for the menu item
    label: "Custom Item 1", // Label for the menu item
    onClick: () => console.log("Custom Item 1 clicked"), // Click handler for the menu item, add functionality that you want
  },
];

To use these extraMenuItems, simply pass them as a prop to the BasePlot component:

<BasePlot
  // ... other props
  additionalMenuItems={extraMenuItems}
/>

CustomMenu Component API Reference

The CustomMenu component provides a custom context menu interface, allowing for additional interaction with plot elements. It supports custom menu items and editors for subplot and color axis customization.

Props

Note: When using customSubplotEditor or customColoraxisEditor, ensure that the custom components you provide are designed to interact with the plot's data structure and update functions as the default editors do. If no custom editors are provided, CustomMenu utilizes its built-in editors that are already equipped to handle the necessary props and provide the appropriate UI for editing subplot and color axis details.

CustomMenuPopup Component API Reference

The CustomMenuPopup component displays a contextual popup with dynamic content. It is versatile and can adapt its position to prevent edge overflow, providing a smooth user experience.

Props

Example of state update

setPopupPosition({
  x: element.x,
  y: element.y,
  clientWidth: element.clientWidth,
  clientHeight: element.clientHeight,
});

Import

import { CustomMenuPopup } from "emerald-plotly-react";

elementPlotting API Reference

Usage

These functions are used in building dynamic plotting applications with Plotly, allowing for customization and interaction based on user input or data changes.

License

MIT