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