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.

Key	Description	Type	Default	Required
context	The context object containing environmental data or configurations.	Object	None	Yes
plot	The plot configuration object, specifying how the plot should be rendered.	Object	None	Yes
setPlot	Function to update the plot configuration.	Function	None	Yes
elements	Array of elements or data points for the plot.	Array	None	Yes
subplotZooms	A state or context-managed object that retains zoom levels for subplots, enabling their use for further optimizations. If not provided, a local state within the component manages the zoom levels by default.	Object	localSubplotZooms	No
setSubplotZooms	Function to update the zoom levels of subplots.	Function	handleSetSubplotZooms	No
currentDragMode	Specifies the current drag mode for plot interaction.	String	null	No
selections	A state object that holds the selection details which can be utilized for further actions or processing within the plot. This state can be managed by a parent component or through a context to enable interaction with selected elements.	Object	null	No
setSelections	Function to update the selections on the plot.	Function	None	No
ignore_errors	Determines whether to ignore errors during plotting.	Boolean	true	No
onPlotUpdate	Callback function for plot updates.	Function	null	No
useDefaultModebar	Controls visibility of the default Plotly modebar.	Boolean	true	No
additionalMenuItems	Additional items for the custom menu.	Array	[]	No
customSubplotEditor	Custom component for editing subplots.	React.Component	null	No
customColoraxisEditor	Custom component for editing color axis.	React.Component	null	No
useDefaultSchema	Whether to use the full Plotly schema.	Boolean	true	No
children	JSX or components to display when no plot is shown.	React.Node	None	No
...restProps	Additional props passed to the underlying Plot component.	Object	None	No

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

Key	Description	Type	Default	Required
plot	The current plot configuration.	Object	None	Yes
setPlot	Function to update the plot configuration.	Function	None	Yes
elements	Array of elements or data points for the plot.	Array	None	Yes
element	The element object representing the target plot area.	Object	None	Yes
context	The context object containing environmental data or configurations.	Object	None	Yes
setShowLegend	Function to toggle the visibility of the legend.	Function	None	Yes
setSelectedElement	Function to set the currently selected plot element.	Function	None	Yes
additionalMenuItems	Additional items to be added to the custom menu.	Array	[]	No
customSubplotEditor	A custom component for editing subplot details. If provided, this component replaces the default editor and must be capable of handling props for plot, setPlot, elements, context, and subplotName to interact with the plot's configuration.	React.Component	DefaultSubplotEditor	No
customColoraxisEditor	A custom component for editing the color axis details. Similar to customSubplotEditor, this replaces the default color axis editor and must interface with the same props expected by the default editor.	React.Component	DefaultColoraxisEditor	No
useDefaultSchema	Determines if the default or full Plotly schema should be used for the color axis editor.	Boolean	true	No

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

Key	Description	Type	Default	Required
content	The content displayed inside the popup. This is typically a component or HTML elements.	React.Node	None	Yes
clickPosition	An object detailing the popup's position, which should be a state updated upon a click. Refer to the CustomMenu source for implementation details. It needs to contain x and y coordinates, along with clientWidth and clientHeight for positioning calculations.	Object	None	Yes
setShowPopup	A function that updates the visibility state of the popup, typically used to hide the popup when a click occurs outside of it.	Function	None	Yes

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

Function	Description	Parameters	Returns
merge(a, b)	Merges two objects, handling data types and combining arrays.	a: Object, b: Object	Merged Object
axis_tracename2layoutname(tracename)	Converts a trace name to a layout name as per Plotly's convention.	tracename: String	Layout Name String
split_axis_tracename(tracename)	Splits a combined axis trace name into separate xaxis and yaxis.	tracename: String	Object with xaxis and yaxis
underlaying_subplot(axis_tracename, plot)	Determines the underlying subplot for a given axis trace name.	axis_tracename: String, plot: Object	Subplot Name String
instantiate_plot(plot, elements, context, ignore_errors)	Instantiates a plot configuration with user-defined specs.	plot, elements, context, ignore_errors: Boolean	Enhanced Plot Object
subplot_specification(axis, plot_specification)	Retrieves specification for a subplot based on axis names.	axis: String, plot_specification: Object	Subplot Specification Object
subplot_elements(axis, plot_specification, elements, context)	Determines applicable plot elements for a given subplot.	axis: String, plot_specification, elements, context: Object	Subplot Elements Object
component_schema(name, elements, context)	Generates a JSON schema for a specified component.	name: String, elements, context: Object	JSON Schema Object
subplot_schema(axis, plot_specification, elements, context)	Creates a JSON schema for subplots with axis unit compatibility.	axis: String, plot_specification, elements, context: Object	JSON Schema Object
apply_selections(elements, context, eventData, action)	Applies a selection action to components in a plot.	elements, context: Object, eventData: Event, action: Function	None

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