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' }]
});

// Named imports
import { create, DEFAULT_CONFIG } from '@emdb-ebi/chart-builder';

await create('chart-container', { chartType: 'area' });

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>

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