EMDB Chart Builder - Standalone Package

A standalone JavaScript module for creating dynamic, customizable charts that visualize EMDB (Electron Microscopy Data Bank) and EMPIAR archive data. This package connects directly to the production EMDB APIs.

Overview

The EMDB Chart Builder is a charting library that enables users to create informative charts analyzing the holdings and trends of the EMDB and EMPIAR archives. It is powered by the EMDB search engine and uses Highcharts for visualization.

Live version: https://www.ebi.ac.uk/emdb/statistics/builder

Features

• Programmatic API: Create charts with simple JavaScript objects - no form inputs required
• ES Module Support: Use modern import/export syntax
• CommonJS Support: Works with Node.js require()
• Multiple Chart Types: Line, Area, Bar, Pie, Stream, Histogram, Scatter (2D/3D), Bubble, Venn diagrams, and Geographic Maps
• Dual Database Support: Query both EMDB and EMPIAR archives
• Flexible Filtering: Use global filters and custom queries to focus on specific data subsets
• Multiple Data Series: Compare different categories with multiple data series
• Interactive Charts: Zoom, export, and download generated charts
• TypeScript Support: Includes TypeScript definitions

Installation

npm Package

npm install @emdb-ebi/chart-builder

Browser (CDN)

<!-- Highcharts (required) -->
<script src="https://code.highcharts.com/highcharts.js"></script>
<script src="https://code.highcharts.com/highcharts-more.js"></script>
<script src="https://code.highcharts.com/modules/exporting.js"></script>

<!-- Chart Builder -->
<script src="path/to/chart-builder.js"></script>
<script src="path/to/lists.js"></script>

Quick Start

ES Module Import (Recommended)

// Default import
import EMDBChartBuilder from '@emdb-ebi/chart-builder';

const builder = new EMDBChartBuilder();
await builder.build('chart-container', {
    chartType: 'line',
    title: 'EMDB Entries Per Year',
    initialYear: 2015,
    series: [{ label: 'All entries', color: '#2f7ed8' }]
});

CommonJS (Node.js)

const EMDBChartBuilder = require('@emdb-ebi/chart-builder');

const builder = new EMDBChartBuilder();
builder.build('chart-container', {
    chartType: 'line',
    title: 'EMDB Entries Per Year'
});

One-Liner Static Method

EMDBChartBuilder.create('chart-container', {
    chartType: 'area',
    title: 'EMDB Growth',
    stacking: 'normal'
});

API Reference

Constructor

const builder = new EMDBChartBuilder(config);

Config Options:

Option	Type	Default	Description
project_root	string	https://www.ebi.ac.uk	Base URL for APIs
emdb_root	string	https://www.ebi.ac.uk/emdb	EMDB root URL

build(containerId, options)

Builds and renders a chart in the specified container.

const chart = await builder.build('my-chart', options);

Chart Options:

Option	Type	Default	Description
database	'emdb' | 'empiar'	'emdb'	Database to query
chartType	string	'line'	Chart type (see below)
title	string	''	Chart title
subtitle	string	''	Chart subtitle
globalFilter	string	''	Global query filter
xDataMode	'yearly' | 'facets' | 'custom'	'yearly'	X-axis data mode
yDataMode	string	'emdb_id'	Y-axis field
xLabel	string	''	X-axis label
yLabel	string	'Number of entries'	Y-axis label
initialYear	number	2002	Start year (yearly mode)
finalYear	number	current year	End year (yearly mode)
stacking	'normal' | 'percent' | 'unstacked'	varies	Stacking mode
mathType	'linear' | 'logarithmic'	'linear'	Y-axis scale
showTable	boolean	true	Show data table
series	SeriesOptions[]	-	Data series configuration
customQueries	CustomQuery[]	-	Custom X-axis queries

Series Options:

{
    label: 'Series name',
    operator: 'unique',  // 'unique', 'cumulative', 'avg', 'max', 'min', 'sum'
    color: '#2f7ed8',
    query: 'structure_determination_method:"singleParticle"'
}

Custom Queries (for xDataMode: 'custom'):

{
    label: 'Category name',
    query: 'resolution:[0 TO 2]',
    color: '#2f7ed8'  // optional, for pie charts
}

Chart Types

Type	Description
line	Line chart for trends over time
area	Area chart with optional stacking
column	Bar chart for comparing categories
pie	Pie chart for proportions
streamgraph	Stream graph visualization
histogram	Distribution histogram
scatter	2D scatter plot
3dscatter	3D scatter with color axis
bubble	Bubble chart
venn	Venn diagram
geo	Geographic map

Examples

Line Chart - Yearly Data

builder.build('chart', {
    chartType: 'line',
    title: 'EMDB Entries Per Year',
    initialYear: 2010,
    series: [{ label: 'Entries' }]
});

Area Chart - Multiple Series

builder.build('chart', {
    chartType: 'area',
    title: 'Entries by EM Method',
    stacking: 'normal',
    series: [
        { 
            label: 'Single-particle', 
            query: 'structure_determination_method:"singleParticle"',
            color: '#2f7ed8'
        },
        { 
            label: 'Tomography', 
            query: 'structure_determination_method:"tomography"',
            color: '#8bbc21'
        }
    ]
});

Bar Chart - Custom Categories

builder.build('chart', {
    chartType: 'column',
    xDataMode: 'custom',
    title: 'Entries by Resolution',
    customQueries: [
        { label: '<2Å', query: 'resolution:[0 TO 2]' },
        { label: '2-3Å', query: 'resolution:[2 TO 3]' },
        { label: '3-4Å', query: 'resolution:[3 TO 4]' }
    ],
    series: [{ label: 'Count' }]
});

Histogram

builder.build('chart', {
    chartType: 'histogram',
    title: 'Resolution Distribution',
    xField: 'resolution',
    xLabel: 'Resolution (Å)',
    histogramStart: 0,
    histogramEnd: 10,
    histogramGap: 0.5
});

Scatter Plot

builder.build('chart', {
    chartType: 'scatter',
    title: 'Resolution vs Molecular Weight',
    xField: 'resolution',
    yField: 'assembly_molecular_weight',
    xLabel: 'Resolution (Å)',
    yLabel: 'Molecular Weight (Da)'
});

Demo Files

• examples/programmatic-api.html - Shows the programmatic API usage
• examples/demo.html - Interactive form-based demo
• examples/embed-example.html - Pre-configured embedded chart

License

Apache-2.0

Links

• EMDB Statistics

• Chart Builder Documentation

• EMDB Search Documentation

    <!-- Data series configuration -->
    <div class="data-series">
        <input type="color" value="#2f7ed8" class="color-series" />
        <select class="seriesOp"><option value="unique" selected>Count (unique)</option></select>
        <input type="text" class="seriesQ" value="">
        <input type="text" class="seriesLabel" value="All entries">
    </div>
  

  <script> $(document).ready(function() { buildStats("unstacked", "linear", true); }); </script>

```

Interactive Chart Builder

See examples/demo.html for a full interactive chart builder interface.

Using URL Parameters

You can also generate charts by providing URL parameters. This is useful for sharing or embedding specific chart configurations:

demo.html?db=emdb&type=line&x_data=yearly&y_data=emdb_id&x_year1=2015&x_year2=2024&s_label1=All+entries&s_op1=unique

Configuration

The src/config.js file contains the API endpoints configuration:

const EMDBChartBuilderConfig = {
    project_root: "https://www.ebi.ac.uk",
    emdb_root: "https://www.ebi.ac.uk/emdb",
    static_root: "https://www.ebi.ac.uk/emdb/static",
    
    api: {
        facet_stats: "https://www.ebi.ac.uk/emdb/api/facet_stats",
        facet_stats_affiliation: "https://www.ebi.ac.uk/emdb/api/facet_stats_affiliation",
        search: "https://www.ebi.ac.uk/emdb/api/search"
    },
    
    highchartsAssetsPath: "https://www.ebi.ac.uk/emdb/static/highchartsv8.22",
    csrf_token: ""
};

Chart Types

Type	Description
line	Line chart for visualizing trends over time
area	Area chart with optional stacking
column	Bar chart for comparing categories
pie	Pie chart for proportions
streamgraph	Stream graph visualization
histogram	Histogram for distribution analysis
scatter	2D scatter plot
3dscatter	3D scatter plot with color axis
bubble	Bubble chart
venn	Venn diagram
geo	Geographic map visualization

Data Y Options

Field	Description	Database
emdb_id	EMDB entries count	EMDB
empiar_id	EMPIAR entries count	EMPIAR
author_name	Authors count	Both
resolution	Resolution values	EMDB
fitted_pdbs	Fitted models count	EMDB
xref_EMPIAR	Raw data links	EMDB
xref_PUBMED	Publications count	Both
...	See full list in demo

Series Operators

Operator	Description	Data Type
unique	Count unique values	Text
cumulative	Cumulative count	Text
avg	Average value	Numeric
max	Maximum value	Numeric
min	Minimum value	Numeric
sum	Sum of values	Numeric

API Reference

Main Functions

• buildStats(chartStacking, chartMath, showTable) - Generate the chart
• initForm() - Initialize form from URL parameters
• addDataSeries() - Add a new data series
• removeDataSeries() - Remove the last data series

Global Variables (set by config.js)

• project_root - Base URL for the project
• emdb_root - EMDB root URL
• static_root - Static assets path
• crsf_token - CSRF token (empty for production API)

Dependencies

• jQuery >= 3.0.0
• jQuery UI >= 1.12.0
• Highcharts (with required modules for chart types you use)

Browser Support

The chart builder works in all modern browsers:

• Chrome (recommended)
• Firefox
• Safari
• Edge

License

Apache-2.0

Links

• EMDB Statistics
• Chart Builder Documentation
• EMDB Search Documentation
• EMDB Search Fields

Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

Support

For support, please:

1. Check the official documentation
2. Open an issue on GitHub
3. Contact the EMDB-EMPIAR team