INSTALL.rst

Install

Note

This section pertains to executing Python from a command line, with the Python program importing py4cytoscape and then using its functions to call Cytoscape. If you intend to run Python in a Jupyter Notebook instead, the installation instructions are much simpler, and can be found in the Jupyter Notebook section of the Concepts chapter. The section below doesn't apply to you.

Note

The quickest and easiest way to see py4cytoscape in action is by following the Quick Start instructions.

py4cytoscape requires Python 3.9 or later. If you do not already have a Python environment configured on your computer, please see the instructions for installing the full scientific Python stack.

Note

If you are on Windows and want to install optional packages (e.g., scipy), then you will need to install a Python distributions such as Anaconda, Enthought Canopy, Python(x,y), WinPython, or Pyzo. If you use one of these Python distribution, please refer to their online documentation.

PyCharm and other integrated development environments often install their own Python distributions.

If you are using the MSYS2 distribution on Windows and have pacboy installed, you can install py4cytoscape and its dependencies with the following commands:

pacboy -S python-{requests,networkx,igraph,pandas,pip}:p --needed
pip install py4cytoscape

Below we assume you have a suitable Python environment already configured on your computer and you intend to install py4cytoscape inside of it. If you want to create and work with Python virtual environments, please follow instructions on venv and virtual environments.

First, make sure you have the latest version of pip (the Python package manager) installed. If you do not, refer to the Pip documentation and install pip first.

Cytoscape Prerequisite

To exercise py4cytoscape, you must first have downloaded, installed, and executed Cytoscape. If you have not already done this, please refer to the Launching Cytoscape instructions.

Note

These instructions assume Cytoscape and py4cytoscape are running on the same workstation or virtual machine. py4cytoscape communicates with Cytoscape via a localhost (127.0.0.1) connection, which precludes py4cytoscape from accessing Cytoscape remotely.

To overcome this limitation, you can execute your Python/py4cytoscape workflow on a remote Jupyter Notebook server (e.g., Google Colab or GenePattern Notebook) as described in the Jupyter Notebook section.

Install the latest version (Python Console)

Install the current release of py4cytoscape with pip:

pip install igraph requests pandas networkx colorbrewer chardet decorator backoff colour
pip install py4cytoscape

Install the development version (Python Console)

To install the latest py4cytoscape development version, instead of pip install py4cytoscape, use:

pip install igraph requests pandas networkx colorbrewer chardet decorator backoff colour
pip install git+https://github.com/cytoscape/py4cytoscape.git

To install the py4cytoscape branch (for example 0.0.10) version, instead of pip install py4cytoscape, use:

pip install igraph requests pandas networkx colorbrewer chardet decorator backoff colour
pip install git+https://github.com/cytoscape/py4cytoscape.git@0.0.10

Alternately, to install a particular py4cytoscape development version (e.g., 0.0.11), instead of pip install py4cytoscape, use:

pip install igraph requests pandas networkx colorbrewer chardet decorator backoff colour
git clone git://github.com/cytoscape/py4cytoscape@0.0.11

Verify Cytoscape connection

To verify that py4cytoscape is properly installed and able to communicate with Cytoscape, execute the following in a Python Console (after starting Cytoscape):

import py4cytoscape as py4
dir(py4)
py4.cytoscape_ping()
py4.cytoscape_version_info()

This will import py4cytoscape into the Python namespace, print a (long) list of py4cytoscape entrypoints, and then demonstrate a connection to Cytoscape by collecting Cytoscape information.

Sanity Testing (command line)

py4cytoscape uses the Python unittest testing package. You can learn more about unittest on its homepage.

To execute tests from an OS command line, set the current directory to the py4cytoscape package directory. Then, establish the execution environment:

cd py4cytoscape
cd tests
set PYTHONPATH=..

Note

You must start Cytoscape before executing any tests.

Executing just a sanity test takes only a few minutes:

runsanitytests.bat

You should be able to see Cytoscape load small networks and manipulate them.

You can also try the Quick Start instructions in Tutorials section.

Deep testing (command line)

The main py4cytoscape test suite consists of a number of sub-suites. Executing all of them can take an hour or two, depending on your workstation.

To execute all tests that don't require user interaction, establish the environment (if you haven't already done so):

cd py4cytoscape
cd tests
set PYTHONPATH=..

Note

You must start Cytoscape before executing any tests.

Run all test sub-suites:

runalltests.bat

Note that runalltests executes without any console output. Instead, it sends normal console output to the cons file, and standard error output to the err file. The err contains normal test failures, but also contains a summary report of any failures once all tests have been run.

Executing one or two tests is relatively quick. To execute a single sub-suite (e.g., test_apps.py):

python -m unittest test_apps.py

To execute more than one sub-suite (e.g., test_apps.py and test_filters.py):

python -m unittest test_apps.py test_filters.py

To execute all sub-suites:

python -m unittest

To execute a single test (e.g., test_get_app_information) in a single sub-suite:

python -m unittest test_apps.AppsTests.test_get_app_information
python -m unittest test_tools.ToolsTests.test_network_merge

Note

To send test output to a file, redirect stderr and console:

python -m unittest 2>stderr.log 1>cons.log

Note

Some tests require console input, and without console prompts, the tests will appear to stall. To avoid executing such tests, set the PY4CYTOSCAPE_SKIP_UI_TESTS environment variable described below.

Note

To execute tests with less console debug output, set this environment variable before executing tests:

set PY4CYTOSCAPE_SUMMARY_LOGGER=FALSE

To further configure logging, see the :ref:`Logging` file.

Note

To execute tests without showing test names as tests execute, set this environment variable before executing the tests:

set PY4CYTOSCAPE_SHOW_TEST_PROGRESS=FALSE

Note

To skip execution of tests that require user input, set this environment variable before executing tests:

set PY4CYTOSCAPE_SKIP_UI_TESTS=TRUE

Note

When executing a large number of tests, we recommend that all three environment variables be set as described above.

Note

When executing tests in PyCharm, you can set environment variables using the Run | Edit Configurations... menu item.