Technical Documentation: cytoscape/cytoscape.js
ℹ️ Provenance: Hybrid Fusion: cytoscape/cytoscape.js (README + 1 In-Tree Chapters) · CodeWiki Reference · Recency: Active (< 180 days)1. Project Overview & Quickstart (cytoscape/cytoscape.js)
<img style="width: 200px; height: 200px;" src="https://raw.githubusercontent.com/cytoscape/cytoscape.js/unstable/documentation/img/cytoscape-logo.png" width="200" height="200">
[](https://github.com/cytoscape/cytoscape.js)
[](https://blog.js.cytoscape.org)
[](https://raw.githubusercontent.com/cytoscape/cytoscape.js/master/LICENSE)
[](https://www.npmjs.com/package/cytoscape)
[](https://zenodo.org/badge/latestdoi/2255947)
[](https://www.npmjs.com/package/cytoscape)
[](https://github.com/cytoscape/cytoscape.js/actions/workflows/tests.yml)
[](https://js.cytoscape.org/#extensions)
[](https://cloudflare.com)
Created at the University of Toronto and published in Oxford Bioinformatics (2016, 2023). <br />
Authored by: Max Franz, Christian Lopes, Dylan Fong, Mike Kucera, ..., Gary Bader
Cytoscape.js
Graph theory (network) library for visualisation and analysis : https://js.cytoscape.org
Description
Cytoscape.js is a fully featured graph theory library. Do you need to model and/or visualise relational data, like biological data or social networks? If so, Cytoscape.js is just what you need.
Cytoscape.js contains a graph theory model and an optional renderer to display interactive graphs. This library was designed to make it as easy as possible for programmers and scientists to use graph theory in their apps, whether it's for server-side analysis in a Node.js app or for a rich user interface.
You can get started with Cytoscape.js with one line:
var cy = cytoscape({ elements: myElements, container: myDiv });Learn more about the features of Cytoscape.js by reading its documentation.
Example
The Tokyo railway stations network can be visualised with Cytoscape:
<img style="width: 300px; height: 126px;" src="https://raw.githubusercontent.com/cytoscape/cytoscape.js/unstable/documentation/img/tokyo-big.png" width="300" height="126">
<img style="width: 300px; height: 126px;" src="https://raw.githubusercontent.com/cytoscape/cytoscape.js/unstable/documentation/img/tokyo-big-zoomed-in.png" width="300" height="126">
A live demo and source code are available for the Tokyo railway stations graph. More demos are available in the documentation.
Documentation
You can find the documentation and downloads on the project website.
Roadmap
Future versions of Cytoscape.js are planned in the milestones of the Github issue tracker. You can use the milestones to see what's currently planned for future releases.
Contributing to Cytoscape.js
Would you like to become a Cytoscape.js contributor? You can contribute in technical roles (e.g. features, testing) or non-technical roles (e.g. documentation, outreach), depending on your interests. Get in touch with us by posting a GitHub discussion.
For the mechanics of contributing a pull request, refer to CONTRIBUTING.md.
Feature releases are made monthly, while patch releases are made weekly. This allows for rapid releases of first- and third-party contributions.
Citation
To cite Cytoscape.js in a paper, please cite the Oxford Bioinformatics issue:
Cytoscape.js: a graph theory library for visualisation and analysis
Franz M, Lopes CT, Huck G, Dong Y, Sumer O, Bader GD
Bioinformatics (2016) 32 (2): 309-311 first published online September 28, 2015 doi:10.1093/bioinformatics/btv557 (PDF)
- PubMed abstract for the original 2016 article
- PubMed abstract for the 2023 update article
Build dependencies
Install node and npm. Run npm install before using npm run.
Build instructions
Run npm run <target> in the console. The main targets are:
Building:
* build: do all builds of the library (umd, min, cjs, esm)
* build:min : do the unminified build with bundled dependencies (for simple html pages, good for novices)
* build:umd : do the umd (cjs/amd/globals) build
* build:esm : do the esm (ES 2015 modules) build
* clean : clean the build directory
* docs : build the docs into documentation
* release : build all release artifacts
* watch : automatically build lib for debugging (with sourcemap, no babel, very quick)
* good for general testing on debug/index.html
* served on http://localhost:8080 or the first available port thereafter, with livereload on debug/index.html
* watch:babel : automatically build lib for debugging (with sourcemap, with babel, a bit slower)
* good for testing performance or for testing out of date browsers
* served on http://localhost:8080 or the first available port thereafter, with livereload on debug/index.html
* watch:umd : automatically build prod umd bundle (no sourcemap, with babel)
* good for testing cytoscape in another project (with a "cytoscape": "file:./path/to/cytoscape" reference in your project's package.json)
* no http server
* dist : update the distribution js for npm etc.
Testing:
The default test scripts run directly against the source code. Tests can alternatively be run on a built bundle. The library can be built on node>=6, but the library's bundle can be tested on node>=0.10.
* test : run all testing & linting
* test:js : run the mocha tests on the public API of the lib (directly on source files)
* npm run test:js -- -g "my test name" runs tests on only the matching test cases
* test:build : run the mocha tests on the public API of the lib (on a built bundle)
* npm run build should be run beforehand on a recent version of node
* npm run test:build -- -g "my test name" runs build tests on only the matching test cases
* test:modules : run unit tests on private, internal API
* npm run test:modules -- -g "my test name" runs modules tests on only the matching test cases
* lint : lint the js sources via eslint
* benchmark : run all benchmarks
* benchmark:single : run benchmarks only for the suite specified in benchmark/single
Release instructions
Background
- Ensure that a milestone exists for the release you want to make, with all the issues for that release assigned in the milestone.
- Bug fixes should be applied to both the master and unstable branches. PRs can go on either branch, with the patch applied to the other branch after merging.
- When a patch release is made concurrently with a feature release, the patch release should be made first. Wait 5 minutes after the patch release completes before starting the feature release -- otherwise Zenodo doesn't pick up releases properly.
Patch version
1. Go to Actions > Patch release
1. Go to the 'Run workflow' dropdown
1. [Optional] The 'master' branch should be preselected for you
1. Press the green 'Run workflow' button
1. Close the milestone for the release
<img style="width: 300px; height: auto;" src="https://raw.githubusercontent.com/cytoscape/cytoscape.js/unstable/documentation/img/preview-patch.png" width="300">
Feature version
1. Go to Actions > Feature release
1. Go to the 'Run workflow' dropdown
1. [Optional] The 'unstable' branch should be preselected for you
1. Press the green 'Run workflow' button
1. Close the milestone for the release
1. Make the release announcement on the blog
<img style="width: 300px; height: auto;" src="https://raw.githubusercontent.com/cytoscape/cytoscape.js/unstable/documentation/img/preview-feature.png" width="300">
Notes on GitHub Actions UI
- 'Use workflow from' in the GitHub UI selects the branch from which the workflow YML file is selected. Since the workflow files should usually be the same on the master and unstable branches, it shouldn't matter what's selected.
- 'Branch to run the action on' in the GitHub UI is preselected for you. You don't need to change it.
Tests
Mocha tests are found in the test directory. The tests can be run in the browser or they can be run via Node.js (npm run test:js).
2. In-Tree Documentation Chapters (cytoscape/cytoscape.js)
CONTRIBUTING
Contributing to Cytoscape.js
Cytoscape.js is an open source project, and we greatly appreciate any and all contributions.
A blog post is available on blog.js.cytoscape.org geared towards first-time code contributors with more in-depth instructions on the project's structure, the process of creating and merging changes to the code, and more.
If you'd like to contribute code to Cytoscape.js but you're not sure exactly what you'd like to implement, take a look at our current milestones to see what features we have planned in future --- or anything labelled help-wanted. Of course, we also welcome your own ideas. You can discuss new ideas with the community on GitHub discussions.
Our goal is to make Cytoscape.js easy to use and comprehensive. Thank you for taking the time and effort to contribute and to help make that happen!
Submitting issues
The first step towards providing a code contribution is to write a short, descriptive issue. If your issue pertains to an extension, you should file the issue on that extension's issue tracker instead.
Describe the bug or feature that you are addressing in your issue. Then, create your issue's corresponding pull request that contains your code changes.
How to make your changes in a pull request
New features go in the unstable branch, which is used for the next (breaking/major or feature/minor) version. Bugfixes go in the master branch for the next bugfix/patch version. This allows us to follow semver nicely.
To propose a change, fork the cytoscape.js repository on Github, make a change, and then submit a pull request so that the proposed changes can be reviewed. If this is your first time making a pull request on GitHub, you can refer to our comprehensive, step-by-step blog post.
The source is organised in relatively the same way as the documentation, under ./src. Try to maintain that organisation as best as you can. You are free to create new files and require() them using ESM import and export.
Add your new feature to the documentation. Updates to the documentation should go in docmaker.json file or the accompanying md files. The documentation's HTML is generated from a template, and so it should not be edited directly.
Code style
Cytoscape.js is transpiled with Babel, so ES2015/ES6+ language features can be used.
Use two spaces for indentation, and single-quoted strings are preferred. The main thing is to try to keep your code neat and readable. There isn't a strict styleguide; it's more important that your code is easily understood and well tested. We do use eslint, so you can use eslint in the terminal or use eslint support in your editor.
You can run eslint --fix to automatically format the code to more or less match the style we use. It will only catch basic things, though.
Testing
Tests go in the ./test directory, as Mocha tests usually do. They are just a flat list of .js files that Mocha runs. If your change is a bugfix, please add a test case that would fail without your fix. If your change is a new feature, please add tests accordingly.
If your change is visual/rendering-related, then Mocha tests are not pragmatic. Use the debug page in the debug directory to try out visual changes. That page contains a sidebar with buttons and dropdowns that make visual and interactive testing easy.
Please run npm test to make sure all the unit tests are passing before you make your pull request.
We also have support for running the Mocha tests in IE9+ and other old browsers. You can run the tests in a Windows IE VM while running npm run watch:umd. Go to http://youripaddress:8081/test/ie.html in IE to open the Mocha test page.
---
--- METRICS ---
- Files Extracted: 2
- Estimated Token Budget: ~3470 tokens
- Recency Window: Active (< 180 days)
- Canonical Reference: https://codewiki.google/github.com/cytoscape/cytoscape.js