A general purpose, real-time visualization library.



By Ryan Sandor Richards

Build Status Dependency Status devDependency Status

Epoch is a general purpose charting library for application developers and visualization designers. It focuses on two different aspects of visualization programming: basic charts for creating historical reports, and real-time charts for displaying frequently updating timeseries data.

To get started using Epoch, please refer to the Epoch Project Site. There you can find full documentation and guides to help you start using Epoch right away.


Epoch can be easily installed via the following package managers:

If you don't see your favorite package manager in the list above feel free to open up an issue and let us know. Finally, you can download any release of the library from the project releases page.

Important: Epoch requires d3. In order to work properly your page must load d3 before epoch.

Public CDN URLs

If you don't want to host the files yourself, you can use jsDelivr to serve the files:

  1. Visit epoch page on jsDelvr.
  2. Copy the provided URL's and link to them in your project.

Developing Epoch

Developing Epoch is a reasonably straight forward process. In this section we'll cover the basic on how to develop Epoch by detailing common build task, exploring how the source is arranged, and finally show how to use rendering tests to aid development.

Configuring Development Environment

Epoch requires the following for development:

  1. Node.js (v4.1.1+)
  2. NPM (v2.1.0+)

Once both are installed on your machine you will need to run npm install from the repository's root directory in order to install the npm packages required to develop epoch.

Once you have installed the required npm packages you can use gulp build to fully rebuild the source (see more information about gulp tasks below).

Basic Development Process

The best way to start contributing to Epoch is to follow these steps:

  1. Change to the source directory for the project
  2. Run gulp watch to recompile the project after source files change
  3. Make changes in a source file (either in src/ or sass/)
  4. In a web browser open the test/index.html and browse the rendering tests
  5. Use the rendering tests to see if your changes had the desired result
  6. Ensure unit tests with pass npm test


Epoch uses two types of testing to ensure that changes do not cause unintended side effects. The first, unit tests, ensure that the core functional components of the library work as expected. The second, rendering tests, allow you to ensure that charts and graphs are correctly rendered.

It is important to keep both unit test and rendering tests up-to-date! When developing, use the following guidelines:

  • When adding new features make sure to add new tests
  • When changing existing functionality, ensure that the appropriate both types of tests still pass
  • If you want to make a new type of chart, add a whole new test suite for that chart!

Keeping the tests current makes it easier for others to review your code and spot issues. Also, pull requests without appropriate testing will not be merged.

Gulp Tasks

Epoch uses gulp to perform various tasks. The gulpfile.js file defines the following tasks:

  • gulp clean - Cleans the dist/ directory.
  • gulp build - Builds the CoffeeScript and Sass source into the dist/ directory.
  • gulp watch - Starts a watch script to recompile CoffeeScript and Sass when any files change.

Source Structure

The directory structure for the Epoch project follows some basic guidelines, here's an overview of how it is structured:

dist/                  - Compiled JavaScript and CSS source
src/                   - Main source directory
  core/                - Core Epoch Library Files
    util.coffee        - Library Utility Routines
    d3.coffee          - d3 Extensions
    format.coffee      - Data formatters
    chart.coffee       - Base Chart Classes
    css.coffee         - CSS Querying Engine
  adapters/            - 3rd Party Library Adapters (currently only jQuery)
  basic/               - Basic Chart Classes
  time/                - Real-time Chart Classes
  adapters.coffee      - Options / Global Classes for Adapter Implementations
  basic.coffee         - Base Classes for Basic Charts
  data.coffee          - Data Formatting
  epoch.coffee         - Main source file, defines name spaces, etc.
  model.coffee         - Data Model
  time.coffee          - Base Classes for Real-Time Charts
sass/                  - Scss source for the default epoch stylesheet
  render/              - Rendering tests
    basic/             - Basic chart rendering tests
    real-time/         - Real-time rendering tests
  unit/                - Unit tests

Release Checklist

  • Run npm test and ensure all tests pass
  • Run npm version [major|minor|patch]
  • Run npm publish
  • Update CHANGELOG.md with the changes since last release
  • Update the gh-pages branch's library version in _config.yml
  • Fixes #23; Better Rendering Tests

    Fixes #23; Better Rendering Tests

    Need better rendering tests for each of the chart types. Specifically I'd like to do the following:

    • [x] Break test/static.html out into a single html page for each type of chart under the directory test/basic/*.html
    • [x] Break test/time.html out into a single html page for each type of chart under the directory test/realtime/*.html
    • [x] Provide a test landing page at test/index.html where you can move back and forth between tests

    To test these changes checkout the rsandor/better-tests branch, run cake build, and open test/index.html in a browser.

    opened by rsandor 14
  • Allow Simple Data Formats

    Allow Simple Data Formats

    For ease of implementation we chose to have set data formats for each of the types of plot. This can be a bit painful for simpler data (especially for time series data). Consider allowing each of the plots to accept multiple formats for the data.

    I'd like to allow for more "flat" data to be used without having to explicitly specify the layer structure. For instance, instead of having to do this:

    data = [
        { label: 'Layer 1', values: [ {time: 0, y: 0}, ... ] }

    one could simply define the same single layer data set like so:

    data = [ {time: 0, y: 0}, ... ]

    Additionally it would be nice to allow for a series of basic numbers:

    data = [ 0, 1, 2, 3, 20302 ]

    For basic plots we could simply use the index as the x value. For real-time plots it's less nice since the time parameter expects a unix timestamp. Perhaps we could just count back from the current second in the browser?

    Either way having simpler data formats should make it easier to get up and running with the library. And one can always use a more formal format as needed.

    opened by rsandor 14
  • tickFormat.right not working for time charts

    tickFormat.right not working for time charts

    tickFormat.left in this case works, however.

    This is with v0.6.0


      type: 'time.line',
      axes: ['right', 'bottom'],
      data: data,
      tickFormats: {
        right: function(d) {
          return '$' + (d / 100000).toFixed(3);
    opened by woozyking 13
  • Needs Updated Dependencies

    Needs Updated Dependencies

    The homepage of this package lists only d3 as a dependency. However, every example seems to use jQuery. I see that Issue #62 seems to be complete, but I am unable to get it completely working with only d3. It looks as though an adapter (jQuery, MooTools, zepto) is needed.

    One example:

    new Epoch.Time.Line({el: '#graph', data: []})

    If I try to declare a real-time line chart (without including width and height), I see failures due to this line: https://github.com/fastly/epoch/blob/master/src/core/chart.coffee#L41 This is because d3 selectors do not have a width function like jQuery does. Doing this prevents the issue, but I would like to be able to use the auto width/height functionality.

    new Epoch.Time.Line({el: '#graph', data: [], width: 300, height: 300})

    This may just be a documentation issue, or it may be a bug, depending on the goal of the library. If the goal is to only have d3 as a dependency, there are some spots where the code needs fixing. If the goal is to have one of the provided adapters be a dependency, this probably needs to be reflected in the docs somehow

    opened by mattdodge 13
  • Closes #68; Added option accessor / mutator

    Closes #68; Added option accessor / mutator

    I am fairly confident that this will work, but I would feel a lot better if we had unit tests in place to make sure it continues to do so. For the time being I'd like to get it in as an experimental / untested feature. Might think about bumping up #24 into release 0.6.0.

    @bontibon - Can you give this a quick look for me?

    opened by rsandor 11
  • Closes #157; Add Multi-axis Support

    Closes #157; Add Multi-axis Support


    screen shot 2015-10-07 at 2 20 10 am

    This adds left/right multi-axis support to all real-time plots, and specific support for the real-time line chart. We abstract the range option to allow the programmer to supply a left and right range if they so desire.


    • [x] Add support for basic line charts with multi-axes
    • [x] Test: Epoch.Time.Plot
    • [x] Test: Epoch.Time.Line
    • [x] Test: Epoch.Util.flatten

    Code Example

    // Specify the left and right ranges
    var leftRange = [0, 100];
    var rightRange = [-10, 10];
    // Setup two series, each using a different range
    var data = [
        label: 'Left Ranged Series',
        values: [
          { time: 0, y: 0 },
          { time: 1, y: 10 },
          { time: 2, y: 99 },
        // This is how your tell a layer to use a specific range...
        range: leftRange
        label: 'Right Ranged Series',
        values: [
          { time: 0, y: -9.8 },
          { time: 1, y: 2.4 },
          { time: 2, y: -0.5 },
        // Again, we must define the range for this particular series...
        range: rightRange
    // Create the real-time line plot with two ranges
    var chart = new Epoch.Time.Line({
      range: {
        left: leftRange,
        right: rightRange
      data: data,
      axes: ['left', 'right', 'bottom']
    opened by rsandor 10
  • package.json: Updated for npm

    package.json: Updated for npm

    • Renamed package to epoch-charting to avoid clashing with existing node module epoch.
    • Added description, keywords, homepage, author, licenses, repository.
    • Changed dependencies to devDependencies, changed the version prefixes to caret ^ (i.e. compatible).
    • Added d3 to package dependencies.
    opened by sompylasar 10
  • GitHub Buttons Not Rendering

    GitHub Buttons Not Rendering

    cc @tuanasaurus @fastly/app

    For the gh-pages site, the footer containing the "Fork" and "Star" GitHub buttons isn't rending properly. What I'm seeing in FF and Chrome:

    The code in question

    <div id="social" class="clearfix">
                <iframe src="http://ghbtns.com/github-btn.html?user=fastly&amp;repo=epoch&amp;type=watch&amp;count=true&amp;size=large" allowtransparency="true" frameborder="0" scrolling="0" width="150" height="30"></iframe>
                <iframe src="http://ghbtns.com/github-btn.html?user=fastly&amp;repo=epoch&amp;type=fork&amp;count=true&amp;size=large" allowtransparency="true" frameborder="0" scrolling="0" width="150" height="30"></iframe>
                <iframe id="twitter-widget-0" scrolling="no" frameborder="0" allowtransparency="true" src="https://platform.twitter.com/widgets/tweet_button.1403226798.html#_=1403900563061&amp;count=none&amp;id=twitter-widget-0&amp;lang=en&amp;original_referer=https%3A%2F%2Ffastly.github.io%2Fepoch%2F&amp;related=jasoncosta&amp;size=l&amp;text=Epoch%20by%20Fastly&amp;url=https%3A%2F%2Ffastly.github.io%2Fepoch%2F" class="twitter-share-button twitter-tweet-button twitter-share-button twitter-count-none" title="Twitter Tweet Button" data-twttr-rendered="true" style="width: 76px; height: 28px;"></iframe>
                <script>!function(d,s,id){var js,fjs=d.getElementsByTagName(s)[0];if(!d.getElementById(id)){js=d.createElement(s);js.id=id;js.src="https://platform.twitter.com/widgets.js";fjs.parentNode.insertBefore(js,fjs);}}(document,"script","twitter-wjs");</script>

    The buttons themselves appear to be working (button1 button2) so this may be a problem with the iframe syntax.

    opened by aspires 10
  • Please distribute unminified source code for debugging

    Please distribute unminified source code for debugging

    Because Epoch seems to lack a lot of documentation right now, I'm not entirely sure how to use it, and tracebacks from minified JS are utterly unhelpful in figuring that out. Please consider making an unminified version of epoch.js available for easy debugging!

    opened by toolness 9
  • Add the ability to set fixed ranges for time graphs

    Add the ability to set fixed ranges for time graphs

    Analogous to https://github.com/fastly/epoch/pull/117/, and so it's exactly the same change.

    Additionally, removed the redundant y() function in time/line to avoid having to duplicate that change in another place.

    opened by willwhitney 9
  • Variable range on realtime (line) plots

    Variable range on realtime (line) plots

    E.g. I have this graph representing memory useage of a process: screenshot from 2015-02-22 12 42 05

    Now I can't set a fixed range from 0 to let's say 1GiB, because memory useage depends heavily on the circumstances, or in this example the memory useage doesn't change for the duration of the plot, as you can see, that really messes with Epoch, also triggering an exception (line 8, Uncaught TypeError: Cannot read property 'x' of undefined):

        Plot.prototype._updateTicks = function(newTime) {
          if (!(this.hasAxis('top') || this.hasAxis('bottom'))) {
          if (!((++this._tickTimer) % this.options.ticks.time)) {
            this._pushTick(this.options.windowSize, newTime, true);
          if (!(this._ticks[0].x - (this.w() / this.pixelRatio) >= 0)) {
            return this._ticks[0].exit = true;

    I am not sure how to properly fix this, maybe replace the range option with an extent function (as called from the code)? Or an extent option which takes precedence over the range option.

    opened by Dav1dde 8
  • TypeError: $(...).epoch is not a function

    TypeError: $(...).epoch is not a function


    • nodejs 14.16.1
    • electron #error
    Uncaught TypeError: Cannot read property 'format' of undefined
        at epoch.min.js:1
    Uncaught TypeError: $(...).epoch is not a function
        at test_epoch.html:34


    test file

    <!DOCTYPE html>
    <html lang="en">
        <meta charset="UTF-8">
        <meta http-equiv="X-UA-Compatible" content="IE=edge">
        <meta name="viewport" content="width=device-width, initial-scale=1.0">
        <script src="./node_modules/jquery/dist/jquery.min.js"></script>
        <script src="./node_modules/d3/dist/d3.min.js"></script>
        <link rel="stylesheet" type="text/css" href="./node_modules/epoch-charting/dist/css/epoch.min.css">
        <script src="./node_modules/epoch-charting/dist/js/epoch.min.js"></script>
        <script type="module">
            import * as d3 from "https://cdn.skypack.dev/d3@7";
            const div = d3.selectAll("div");
        <div id="area" class="epoch category10" style="height: 200px;"></div>
            const $ = require("jquery")
            var data = [
                { label: 'Layer 1', values: [{ x: 0, y: 0 }, { x: 1, y: 1 }, { x: 2, y: 2 }] },
                { label: 'Layer 2', values: [{ x: 0, y: 0 }, { x: 1, y: 1 }, { x: 2, y: 4 }] }
            var areaChartInstance = $('#area').epoch({
                type: 'area',
                data: data,
                axes: ['left', 'right', 'bottom']
    opened by wangzhankun 1
  • This project is no longer being updated

    This project is no longer being updated

    Being not updated several years ago, and with the current version of D3.js not compatible with this package, it seems this project is no longer relevant nor feasible to use under a production environment.

    If anybody has a better replacement than plotly.js for doing real time charts, you are welcome.

    opened by hypgfrch 0
  • plasma oscillation in 1-D epoch

    plasma oscillation in 1-D epoch

    I am trying to perform plasma oscillation using 1-D epoch code. However, there is no density evolution occur in the output. kindly help me in digging out the error. I am attaching it input file here.

    begin:control nx = 30000 x_min = 0 x_max = 2*pi npart = 100 * nx t_end = 1.77e-8 end:control

    begin:boundaries bc_x_min = periodic bc_x_max = periodic end:boundaries

    begin:constant den_peak = 1.0e18 end:constant

    begin:species name = Electron density = den_peak*((0.1cos(2pi*x/length_x))+1) charge = -1.0 mass = 1.0 frac = 0.5 end:species

    begin:species name = Proton density = den_peak charge = 1.0 mass = 1836.2 frac = 0.5 end:species


    number of timesteps between output dumps

    dt_snapshot = 1.77e-11

    Number of dt_snapshot between full dumps

    full_dump_every = 1

    Properties at particle positions

    particles = always px = always

    Properties on grid

    grid = always ex = always ey = always ez = always bx = always by = always bz = always jx = always ekbar = always mass_density = never + species charge_density = always number_density = always + species

    extended io

    distribution_functions = always end:output

    opened by Deepa64 0
  • gulp build issue

    gulp build issue

    npm ERR! Linux 4.4.0-1092-aws npm ERR! argv "/usr/local/lib/nodejs/node-v4.1.1-linux-x64/bin/node" "/usr/local/lib/nodejs/node-v4.1.1-linux-x64/bin/npm" "run" "build" npm ERR! node v4.1.1 npm ERR! npm v2.14.4 npm ERR! code ELIFECYCLE npm ERR! [email protected] build: gulp build npm ERR! Exit status 1 npm ERR! npm ERR! Failed at the [email protected] build script 'gulp build'. npm ERR! This is most likely a problem with the epoch-charting package, npm ERR! not with npm itself. npm ERR! Tell the author that this fails on your system: npm ERR! gulp build npm ERR! You can get their info via: npm ERR! npm owner ls epoch-charting npm ERR! There is likely additional logging output above.

    npm ERR! Please include the following file with any support request: npm ERR! /home/ubuntu/epoch-0.8.4/npm-debug.log npm ERR! Test failed. See above for more details.

    opened by jonnalagaddda 2
  • tickFormats example in the documentation

    tickFormats example in the documentation

    Hi, Thanks for your work on this library. I found a small bug in the documentation:

    On this page: https://epochjs.github.io/epoch/real-time/

    in the common option area, one can see this example:

    tickFormats: { time: function(d) { return new Date(time*1000).toString(); } }

    This is actually incorrect and it should be in fact:

    tickFormats: { bottom: function(d) { return new Date(time*1000).toString(); } }

    Also, it may be useful to insert an example about how to display nothing as tick's text, ie:

    tickFormats: { bottom: function(d) { } }

    Thank you.

    opened by csebe 0
  • Cannot read property 'format' of undefined

    Cannot read property 'format' of undefined

    I currently want to write a chrome app that contains a epoch graph. Heres my index.html:

      <meta charset="utf-8">
      <link href="styles/main.css" rel="stylesheet">
      <link rel="stylesheet" type="text/css" href="css/epoch.min.css">
      <div id="pie" style="width: 400px; height: 400px"></div>
      <script src="js/d3.js"></script>
      <script src="js/epoch.js"></script>

    Heres my main.js:

    chrome.app.runtime.onLaunched.addListener(function() {
      var screenWidth = screen.availWidth;
      var screenHeight = screen.availHeight;
      var width = 500;
      var height = 300;
      chrome.app.window.create('index.html', {
        id: "helloWorldID",
        outerBounds: {
          width: width,
          height: height,
          left: Math.round((screenWidth-width)/2),
          top: Math.round((screenHeight-height)/2)
    var pieData = [
      { label: 'Slice 1', value: 10 },
      { label: 'Slice 2', value: 20 },
      { label: 'Slice 3', value: 40 },
      { label: 'Slice 4', value: 30 }
      type: 'pie',
      data: pieData

    When I run this, the chart area stays empty and the error "Uncaught TypeError: Cannot read property 'format' of undefined" appears. The line the error occurs at is 429 which contains this: d3Seconds = d3.time.format('%I:%M:%S %p'); My guess is that the error appears because d3 wasnt properly loaded but I dont know how to fix this as I think I followed the guide.

    opened by JakobStaudt 3
Timeline/Graph2D is an interactive visualization chart to visualize data in time.

vis-timeline The Timeline/Graph2D is an interactive visualization chart to visualize data in time. The data items can take place on a single date, or

vis.js 1.2k Jan 3, 2023
JavaScript toolkit for creating interactive real-time graphs

Rickshaw Rickshaw is a JavaScript toolkit for creating interactive time series graphs, developed at Shutterstock Table of Contents Getting Started Ins

Shutterstock 6.5k Dec 28, 2022
A damn-sexy, open source real-time dashboard builder for IOT and other web mashups. A free open-source alternative to Geckoboard.

freeboard free·board (noun) *\ˈfrē-ˌbȯrd* the distance between the waterline and the main deck or weather deck of a ship or between the level of the w

freeboard 6.3k Dec 28, 2022
Using ASP.NET Core, SignalR, and ChartJs to create real-time updating charts

Real-time Charts with ASP.NET Core, SignalR, and Chart.js This project shows how to update a real-time chart in your web browser using technologies li

Khalid Abuhakmeh 11 Nov 25, 2022
Apache ECharts is a powerful, interactive charting and data visualization library for browser

Apache ECharts Apache ECharts is a free, powerful charting and visualization library offering an easy way of adding intuitive, interactive, and highly

The Apache Software Foundation 53.8k Jan 9, 2023
a graph visualization library using web workers and jQuery

arbor.js -------- Arbor is a graph visualization library built with web workers and jQuery. Rather than trying to be an all-encompassing framework, a

Christian Swinehart 2.6k Dec 19, 2022
Data visualization library for depicting quantities as animated liquid blobs

liquidity.js A data visualization library for depicting quantities as animated liquid blobs. For a demonstration of what the final product can look li

N Halloran 91 Sep 20, 2022
Powerful data visualization library based on G2 and React.

BizCharts New charting and visualization library has been released: http://bizcharts.net/products/bizCharts. More details about BizCharts Features Rea

Alibaba 6k Jan 3, 2023
🌏 A Declarative 3D Globe Data Visualization Library built with Three.js

Gio.js English | 中文 React Version: react-giojs Wechat minigame: wechat usage Gio.js is an open source library for web 3D globe data visualization buil

syt123450 1.6k Dec 29, 2022
📊 Data visualization library for React based on D3

Data visualization library for React based on D3js REAVIZ is a modular chart component library that leverages React natively for rendering the compone

REAVIZ 740 Dec 31, 2022
A library for visualization and creative-coding

Pts Pts is a typescript/javascript library for visualization and creative-coding. Get started at ptsjs.org. Please give it a try, file issues, and sen

William Ngan 4.9k Jan 3, 2023
Apache ECharts is a powerful, interactive charting and data visualization library for browser

Apache ECharts Apache ECharts is a free, powerful charting and visualization library offering an easy way of adding intuitive, interactive, and highly

The Apache Software Foundation 53.8k Jan 5, 2023
An open-source visualization library specialized for authoring charts that facilitate data storytelling with a high-level action-driven grammar.

Narrative Chart Introduction Narrative Chart is an open-source visualization library specialized for authoring charts that facilitate data storytellin

Narrative Chart 45 Nov 2, 2022
Render echarts in obsidian,Apache ECharts,An Open Source JavaScript Visualization Library

obsidian-echarts Render echarts in obsidian,Apache ECharts,An Open Source JavaScript Visualization Library

null 23 Dec 26, 2022
Data Visualization Components

react-vis | Demos | Docs A COMPOSABLE VISUALIZATION SYSTEM Overview A collection of react components to render common data visualization charts, such

Uber Open Source 8.4k Jan 2, 2023
📊 A highly interactive data-driven visualization grammar for statistical charts.

English | 简体中文 G2 A highly interactive data-driven visualization grammar for statistical charts. Website • Tutorial Docs • Blog • G2Plot G2 is a visua

AntV team 11.5k Dec 30, 2022
A visualization grammar.

Vega: A Visualization Grammar Vega is a visualization grammar, a declarative format for creating, saving, and sharing interactive visualization design

Vega 10.1k Dec 30, 2022
A port of the Processing visualization language to JavaScript.

⚠️ This project has been archived ⚠️ With the development of p5js and the API advances in Processing itself, as well as Processing.js itself having be

Processing.js 3.1k Jan 4, 2023
Dynamic HTML5 visualization

Envision.js Fast interactive HTML5 charts. http://groups.google.com/group/envisionjs/ Features Modern Browsers, IE 6+ Mobile / Touch Support Pre-built

HumbleSoftware 1.6k Dec 3, 2022