Tutorial For Cytoscape Web

Table of Contents

1. Set up the Development environment
   • Install node and npm
   • Run Cytoscape-Web on your local machine
2. Get familier with the Cytoscape-Web
   • Basic Architecture and Concept
     • Nav bar and Menu
     • Workspace
     • CyWebNetwork
   • Introduction to the code base
   • Basic Design
3. Example of Extending the features
   • Add a new menu item
   • Create a simple network
   • Subtract a subnetwork from selection
4. How to debug
5. How to add a test

Set up the Development environment

Install node and npm

For Linux

1. Update your package repository:

• Run sudo apt update

2. Install Node.js and npm:

• Run sudo apt install nodejs AND
• Run sudo apt install npm

3. Verify the installation:

• Run node --version (Must be >= 16.8.0) AND
• Run npm --version

For Mac

1. Install Homebrew:

• Run /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

2. Install Node.js and npm:

• Run brew install node

3. Verify the installation:

• Same as in the Linux case.

For Windows

1. Download the Windows Installer:

• Visit the Node.js website and download the Windows Installer.
• Run the installer and follow the prompts to install Node.js and npm.

2. Verify the installation:

• Same as in the Linux case(Run the commands in a command prompt or PowerShell).

Run Cytoscape-Web on your local machine

To get Cytoscape-web up and running locally, please follow these steps:

1. Prepare Your Workspace:

• Choose a directory where you want to store the Cytoscape-web codebase. Navigate to this directory in your terminal or command prompt.

2. Clone the Repository:

• Run the following command in the terminal: git clone https://github.com/cytoscape/cytoscape-web.
• The above command creates a new folder named cytoscape-web containing the project files. Now you need to change into the newly cloned repository's directory by running cd cytoscape-web.

3. Install dependencies

• Install the project's dependencies using npm: npm install.

4. Start the Development Server

• Once the dependencies are installed, you can start the development server with the command npm run dev.

5. Access the application

• Open your web browser and navigate to localhost:5500. This address connects to the development server running on your machine.

Get familier with Cytoscape-Web

Basic Architecture and Concept

Cytoscape-Web is a single-page web application, with Backend using REST API and Frontend using React. The main work data flow is shown in the following diagram:

Nav bar and Menu

Workspace

Workspace is the basic unit of user’s data, it represents the working status on a user's Cytoscape-Web. It includes:

• name: readable name of the Workspace
• id: unique ID of the Workspace
• metadata: creationTime, localModificationTime
• networkIds: list of network IDs
• current network: the network that is currently loaded in website

CyWebNetwork

The CyWebNetwork is a key object in Cytoscape-Web. It contains every information in a network, which includes:

Network Summary - includes metadata and network attributes

• UUID of network
• Network Name
• Network attributes
• URL of a thumbnail image
• A Key to the data model persisted in the client side storage

Visual Style - a reference to the vizmapper object

• Defaults
• Mappings
• Bypasses

Network Topology

• Edges
• Nodes

View Model: the key-value pair storing what should be displayed in the actual visualizations

• Node attribute table
• Edge attribute table

Tables: a 2-D array where each column represents an attribute and each row represents a node/edge

• Node attribute table
• Edge attribute table

Visual Style

Introduction to the code base

├─ 📁data
    ├─ 📄empty-db.json                      # Empty database example
├─ 📁docs
    ├─ 📄testing.md
├─ 📁netlify
    ├─ 📄redirects
├─ 📁node_modules                           # Dependencies and libraries
    ├─ 📄...
├─ 📁src                                    # Main Code Base
    ├─ 📁 assets                                # Static icons, images, and color palettes are stored here
        ├─ 📄 BrBG.png                              - A color palette
        ├─ 📄 cytoscape.svg                         - The cytoscpae icon 
        ├─ 📄 config.json                           - Basic configurations of the website
        ├─ 📄...
    ├─ 📁components                             # Website components are stored here
        ├─ 📁 Login                                 # User login panel
        ├─ 📁 NetworkPanel                          # Network panel (upper-right side)
            ├─ 📁 CyjsRenderer                          - Network Renderer
        ├─ 📁 TableBrowser                          # The bottom table that contains information on nodes, edges, and networks
        ├─ 📁 ToolBar                               # The top navigation bar
            ├─ 📁 AnalysisMenu                          - Dropdown menu of 'Analysis'
            ├─ 📁 DataMenu                              - Dropdown menu of 'Data'
        ├─ 📁 Workspace                             # The upper-left-side workspace panel
        ├─ 📄...    
    ├─ 📁features                               # Website components are stored here
        ├─ 📁 HierarchyViewer
        ├─ 📁 LLMQuery
    ├─ 📁models                                 # Models of data or UI components are stored here
        ├─ 📁 Workspace 
        ├─ 📄...
    ├─ 📁store                                  # Managing the state related to different objects
        ├─ 📁 hooks
        ├─ 📁 io
        ├─ 📁 persist
        ├─ 📄 NetworkStore.ts
    ├─ 📁utils
        ├─ 📄...
    ├─ 📄...
├─ 📁test
    ├─ 📄...
├─ 📁unittest
    ├─ 📄...
├─ 📄.gitignore
├─ 📄README.md

Basic design

The main workflow is: the components interact with stores, and stores interacts with database.

Components <--> Stores <--> Database

Currently, there are basically WorkspaceStore

Store Name	Role	Operation
WorkspaceStore		- Set new workspace - Add/remove network(s) to the workspace
NetworkSummaryStore		Add/delete network summaries-Update contents of a summary
NetworkStore		Add/delete network to the store - Edit network structure - add/delete nodes-add/delete edges
TableStore		Add/delete tables -Update a value in a table -Utilities - get all column values
ViewModelStore		Add/delete view models - Keep track of selection states
VisualStyleStore

Database:

To avoid data loss caused by accidents, IndexedDB is employed in this project to persist data locally. However, it also brings some limitations:

• There is always one Workspace database per domain (per browser)
• This means even if a user opens multiple tabs, the same workspace will be used.

The following tables are stored in the cached

Table Name	Key	Value
workspace	Workspace ID	Workspace object
cyNetworkWorks	Network ID	Network Oject
cyTables	Network ID	Table Object
cyNetworkViews	Network ID	View Model Object
cyVisualStyles	Network ID	Visual Style object
summaries	Network ID	summary object

Examples of extending the features

Add a new menu item

Code

Create a simple network

Code

Subtract a subnetwork from selection

Code

How to Debug

How to add a test