ipycytoscape

ipycytoscape allows you to visualize graphs in Jupyter Notebooks using Cytoscape.js. Graphs can be created via the native ipycytoscape API or imported from several common data formats and libraries:

• NetworkX: Using add_graph_from_networkx().
• JSON: Importing graph data in JSON format.
• Pandas: Creating graphs from DataFrames.
• Native API: Building graphs directly using ipycytoscape methods.

You can use sphinx-autobuild to continuously watch for changes in source files and automatically rebuild the documentation. This is configured via the project's Makefile.

```bash
cd docs
make watch

Note: If you are modifying a notebook that is included in the documentation via nblink, you will still need to manually rebuild to capture changes to that specific file.

You can install ipycytoscape using pip or via conda/mamba from the conda-forge channel.

# Using pip
pip install ipycytoscape

# Using conda
conda install -c conda-forge ipycytoscape

# Using mamba
mamba install -c conda-forge ipycytoscape

To view recent adjustments to the documentation, you must first install the documentation requirements and then build the HTML files using make.

```bash
# Install documentation requirements
cd ipycytoscape
pip install -e.[docs]

# Build the HTML documentation
cd docs
make html

Once built, you can view the rendered documentation by opening build/html/index.html in your browser.

To develop ipycytoscape, you need npm and a configured environment.

1. Create and activate a conda environment with jupyterlab and nodejs.
2. Clone the repository.
3. Install the package in editable mode with test and docs extras. This runs npm install and npm run build automatically.
4. Use jupyter labextension develop to link the extension.

For classic notebook development, use jupyter nbextension install with the --symlink flag (note: --symlink is not supported on Windows).

# Environment setup
conda create -n ipycytoscape -c conda-forge jupyterlab nodejs
conda activate ipycytoscape

# Clone and install
git clone https://github.com/cytoscape/ipycytoscape.git
cd ipycytoscape

pip install jupyter_packaging==0.7.9
pip install -e ".[test, docs]"

# Link extension
jupyter labextension develop . --overwrite

If you are using a version of Jupyter Notebook older than 5.3 (specifically the classic notebook), you must manually install and enable the front-end extension. If you installed via conda, these steps are usually unnecessary, but if required, use the --sys-prefix flag.

# Install the extension
jupyter nbextension install --sys-prefix --py ipycytoscape

# Enable the extension
jupyter nbextension enable --sys-prefix --py ipycytoscape

To run automated checks whenever you perform a git commit, you can install pre-commit hooks using pip and the pre-commit CLI. If you choose not to install them locally, the pre-commit.ci bot will automatically attempt to push fixes to your pull requests.

pip install pre-commit
pre-commit install

To see your changes reflected in the browser:

TypeScript changes: Run npm run watch in one terminal to monitor and rebuild code. In a separate terminal, start jupyter lab. Once the webpack rebuild completes, refresh the JupyterLab page.

Python changes: Restart the notebook kernel to apply changes made to Python code.

# Watch TypeScript changes
npm run watch

# In another terminal
jupyter lab

You can install ipycytoscape using pip or conda/mamba.

Note for JupyterLab 1.x or 2.x users: You must follow additional installation instructions for the JupyterLab manager extension to ensure the widget renders correctly.

# Using pip
pip install ipycytoscape

# Using conda
conda install -c conda-forge ipycytoscape

# Using mamba
mamba install -c conda-forge ipycytoscape

To build the documentation locally:

1. Navigate to the docs directory.
2. Update the conda environment using doc_environment.yml.
3. Run make html.

cd docs
conda env update --file doc_environment.yml
make html

If you are using older versions of JupyterLab (1.x or 2.x), you must install nodejs and the jupyterlab-manager extension, then build JupyterLab.

# installing nodejs
conda install -c conda-forge nodejs

# install jupyterlab-manager extension
jupyter labextension install @jupyter-widgets/jupyterlab-manager@2.0 --no-build

# if you have previously installed the manager you still to run jupyter lab build
jupyter lab build

To install a developer version of ipycytoscape from source, clone the repository and use pip with the -e (editable) flag. This allows changes to the Python code to take effect without re-installing the package.

git clone https://github.com/cytoscape/ipycytoscape
cd ipycytoscape
pip install -e .