Installation

There are two ways to install Candela: from standard package repositories systems such as npm and the Python Package Index (PyPI). Installing from a package repository is simpler, but limited to public release versions; installing from source is slightly more complicated but allows you to run cutting-edge development versions.

Installing from package management systems

JavaScript

To install the Candela JavaScript library to node_modules/candela in your current directory, run:

npm install candela

To install the Candela JavaScript library as a dependency of your web application and add it to your package.json file, run:

npm install --save candela

A self-contained JavaScript bundle for Candela will be found at node_modules/candela/dist/candela[.min].js.

Using Webpack

If your project uses a Webpack build process, you can use Candela’s bundled Webpack helper function to include Candela easily in your project without having to use the fullsize bundle file. The idea is to directly include Candela source files as needed in your project, relying on the Webpack helper to arrange for the proper loaders and other configuration options to be used. For example, without Webpack, your source file might include lines like

var candela = require('candela/dist/candela.min.js');
var ScatterPlot = candela.components.ScatterPlot;

This will result in your application loading the entire Candela bundle at runtime, which may not be optimal if you just wish to use the ScaterPlot component. Instead, using Webpack, you could cast this code as follows:

var ScatterPlot = require('candela/components/ScatterPlot');

To make sure that your build process uses the correct loaders for this file, you should make sure to use the Candela webpack helper function in your project’s Webpack configuration:

var candelaWebpack = require('candela/webpack');

module.exports = candelaWebpack({
  // Your original webpack configuration goes here
});

This approach lets you keep your code more concise and meaningful, while also avoiding unnecessarily large application bundles.

Python

The latest release version of the Python bindings for Candela can always be found in the Python Package Index. The easiest way to install Candela is via Pip, a package manager for Python.

1. Install software dependencies

Install the following software:

• Python 2.7
• Pip

On Linux and OS X computers, your local package manager should be sufficient for installing these. On Windows, please consult this guide for advice about Python and Pip.

2. Install the Candela Python package

Use this command in a shell to install the Candela package and its dependencies:

pip install pycandela

You may need to run this command as the superuser, using sudo or similar.

Building and installing from source

Before any of these source installations, you will need to issue this Git command to clone the Candela repository:

git clone git://github.com/Kitware/candela.git

This will create a directory named candela containing the source code. Use cd to move into this directory:

cd candela

JavaScript

Candela is developed on GitHub. If you wish to contribute code, or simply want the very latest development version, you can download, build, and install from GitHub, following these steps:

1. Install software dependencies

To build Candela from source, you will need to install the following software:

• Git
• Node.js
• npm
• cairo (brew install cairo on macOS)

2. Install Node dependencies

Issue this command to install the necessary Node dependencies via the Node Package Manager (NPM):

npm install

The packages will be installed to a directory named node_modules.

3. Begin the build process

Issue this command to kick off the build process:

npm run build

The output will create a built Candela package in build/candela/candela.js.

Watch the output for any errors. In most cases, an error will halt the process, displaying a message to indicate what happened. If you need any help deciphering any such errors, drop us a note on GitHub issues or on Gitter chat.

4. View the examples

Candela contains several examples used for testing, which also may be useful for learning the variety of visualizations available in Candela. To build the examples, run:

npm run build:examples

To view the examples, run:

npm run examples

5. Run the test suites

Candela comes with a battery of tests. To run these, you can invoke the test task as follows:

npm run test:all

This runs both the unit and image tests. Each test suite can be run on its own, with:

npm run test:unit

and:

npm run test:image

Each of these produces a summary report on the command line.

6. Build the documentation

Candela uses Sphinx documentation hosted on ReadTheDocs. To build the documentation locally, first install the required Python dependencies:

pip install -r requirements-dev.txt

When the installation completes, issue this command:

npm run docs

The documentation will be hosted at http://localhost:3000.

Python

1. Install software dependencies

To use Candela from Python you will need Python 2.7 and pip.

2. Install the library locally

pip install -e .

3. Test the installation

Issue this command to start Jupyter notebook server in your browser:

jupyter-notebook

Create a notebook from the New menu and enter the following in a cell, followed by Shift-Enter to execute the cell and display the visualization:

import requests
data = requests.get(
    'https://raw.githubusercontent.com/vega/vega-datasets/gh-pages/data/iris.json'
).json()

import pycandela
pycandela.components.ScatterPlot(
    data=data, color='species', x='sepalLength', y='sepalWidth')

R - using install_github or Git checkout

This procedure will install Candela either directly from GitHub or from a local Git checkout of Candela.

1. Install R , and optionally RStudio

2. Install the Candela package

To install directly from GitHub:

install.packages('devtools')
devtools::install_github('Kitware/candela', subdir='R/candela', dependencies = TRUE)

To install from a Git checkout, set your working directory to the Git checkout then install and check the installation. check() will run tests and perform other package checks.

setwd('/path/to/candela/R/candela')
install.packages('devtools')
devtools::install(dependencies = TRUE)
devtools::check()

3. Test the installation

The following will create a scatter plot of the mtcars dataset and save it to out.html:

library(candela)
w <- candela('ScatterPlot', data=mtcars, x='mpg', y='wt', color='disp')
htmlwidgets::saveWidget(w, 'out.html')

From RStudio, the visualization will appear in the application when you refer to a visualization without assigning it to a variable:

w

Note: saveWidget requires an installation of Pandoc when run outside of RStudio. See the installation instructions to install.