akmo3 / cytoscape.js

Graph theory (network) library for visualisation and analysis

Created at the University of Toronto and published in Oxford Bioinformatics (2016, 2023).
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:

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, umd, 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

• Manual Release
• Feature Release
• Backport/Patch Release

IMP: The releases should be made atleast 5 min apart for the zenodo to pick the new release. IMP: Amend Github Action in all branches for consistent results across branches

• Repository Setup for Github Actions: Repository Setup

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).

cytoscape.js's Issues

Checkout repository and select patch branch

Purpose:

• When a milestone is closed, this should indicate that the release should be made for that milestone.
• Closing a milestone is a trigger for the GH actions release process.

Timeline:

• Milestone gets closed
• GH actions starts
• There is some gating that blocks the GH action from finishing ('permanent' actions/results -- npm release), and someone needs to hit a button or something to confirm first

Details:

This task consists of action to checkout the appropriate branch for a patch release, which can be done using two ways:

1. Manually giving input using workflow_dispatch
2. On completion of a milestone, get the label of milestone which specifies the release to which the patch be applied.
3. Documentation: The trigger needs to be obvious to everyone.

Inputs:

• Branch
• Type of release that you're making: patch / feature -- apply to most/all of the scripts/actions

Testing: How do we confirm that this is working.

• Example GH action
• Test on closing of milestone in this repo -- scope this to a particular milestone name (testissue3)
• Or: disable the test gh action when done
• Manually confirm

Create environments for release process

1. Create one single environment with permission for both publishing and creating a cytoscape-js.blog issue. The name can be RELEASE_ENVIRONMENT.

Run the release process on the main repo

Task #5: Run tests

Test Issue to check patch release for 3.10.3

Setup npm test repository and secrets into GitHub

This task includes to setup the environment entirely for the development of action. This includes:

• Provide push permission to mentors
• Setup npm for demo push and updates
• Setup secrets

Update Github Action on master if the action is updated in unstable

1. Document this in README.md
2. Also edit the action to use directly the GitHub action present in master branch

Create a action to automatically determine new version string for releases

The action should correspond to the below behaviour:

• For Feature Release: 1.2.3 => 1.3.0
• For Patch Release: 1.2.3 => 1.2.4

Create Github Action for the patch release

Do not run step for github pages push for backport

Version updates in merge_unstable_to_master.sh

cytoscape.js/.github/workflows/scripts/merge_unstable_to_master.sh

Lines 58 to 62 in ebddf47

	# Update package.json
	sed -i "s/\"version\": \".*\"/\"version\": \"$VERSION\"/" package.json
	# Update package-lock.json
	sed -i "s/\"version\": \".*\"/\"version\": \"$VERSION\"/" package-lock.json

This corresponds to step (4)(ii)(e).

The point of this step is that the unstable branch should have some version number on it that's sensible:

• If someone (e.g. an external contributor) looks at the unstable branch, they should know that the branch is for new, next version features.
• The version should not match the same as the release we are about to make.

Make a release of $VERSION, then we want $VERSION+1 for unstable.

E.g. 1.2.0 is being released, then version in package.json should be 1.3.0-unstable

Meta issue: GSoC'23 - Automate release process of Cytoscape.js

The GitHub action will be created bottom-up, where small parts of the action will be created first as composite actions, independently tested and then merged into the final complete action. All the tasks required to be done are listed here:

• #1
• #3
• #4
• #5
• #6
• #7
• #8

Run through the release process manually

• The release process is outlined in the readme.
• It would be good to run through the process manually and then note any issues or anything that you think of or notice, while you're going through the process.
• Requirements: Change the name of the package in package.json
• Requirement: GH pages permissions?

Outcomes:

• Identify more details for the other issues (& new issues)
• Confirm that you have all permissions and setup required for testing (npm demo package etc.)

Docs

Make following changes to documentation:

• Feature-Release.yml

1. Add a warning to not change branch from unstable

• Patch/Backport Release

1. Add documentation that you need to run patch release explicitly after every backport release.

• Prerequisite: If someone in future wants to amend the GH actions for releasing, then they have to apply those changes to each applicable branch.

The list of versions should be updated using a template

Akash to update:

The list of versions should be updated using a template (built by docmaker.js from a file with the list of versions, versions.json)
versions.json: { versions: [‘3.10.0’, ‘3.10.1’, ‘3.11.0’] }
Add a version: Read the versions.json, push version, write the file
Template maker/builder (docmaker.js): Process the list of versions
Lodash
List of releases
Each patch version under each release
Sorted
Create an issue to track this feature

Useful tool: act

https://github.com/nektos/act

Check if required files are changed after running `npm run release`

Pull requests for the main repo

Make PRs to the main repo to apply these changes so that the releases can be made on cytoscape/cytoscape.js.

Investigate removal of curl and directly running the scripts from the checkout repo

Considerations re. `set -e`

Some things to take into account re. set -e: http://mywiki.wooledge.org/BashFAQ/105

Creation of back-port branches

I'm not sure whether this is covered already, but it came up during a manual release just now.

Whenever a new feature release is made for a .0 release (e.g. 3.26.0), there should be a new branch made for the back-port branch (that would have been on the master branch before).

E.g. when releasing 3.26.0:

• Before merging master and unstable together:
• Make a new branch based on the tip of master, e.g. 3.25.x
• Push the new branch
• Then continue on with the normal release process for the feature release

Create action to support Github Release

This task includes the creation of a composite action that :

1. Check for necessary files that should be updated
2. Add the release to git
3. Update the package version and tag the release
4. Push the release changes

Task #6: Run release and update documentation

This task includes the creation of a composite action that :

1. Prepare release
2. Update documentation

Write script to merge unstable to master for feature release

As per the release instructions:

    1. Make sure your local master is up-to-date: git checkout master && git pull
    2. Make sure your local unstable is up-to-date: git checkout unstable && git pull
    3. Create a merge commit that selects the state of unstable and push it: git merge -s ours master && git push
    4. Fast-forward master to the merge commit: git checkout master && git merge unstable && git push
    5. Update the version number in package.json and package-lock.json on unstable to some provisional new version number, and push it.

This tasks also requires handling GitHub secrets to enable secure push to remote.

Add new patch/backport version to master branch `versions.json`

Update documentation re. new release process

Update the README with information about how the new process works:

• The release process needs an access token
• Note the secrets necessary

Note the steps that someone has to carry out for each type of release in the README:

• Backport
• Patch/bugfix
• New feature release

Misc.

• Update the readme and move the current manual steps into a new file under .github dir

Update all branches to remove `docs:push` from package.json