Py4cytoscape Documentation Release 0.0.1
Total Page:16
File Type:pdf, Size:1020Kb
py4cytoscape Documentation Release 0.0.1 The Cytoscape Consortium Jun 21, 2020 CONTENTS 1 Audience 3 2 Python 5 3 Free Software 7 4 History 9 5 Documentation 11 6 Indices and tables 271 Python Module Index 273 Index 275 i ii py4cytoscape Documentation, Release 0.0.1 py4cytoscape is a Python package that communicates with Cytoscape via its REST API, providing access to a set over 250 functions that enable control of Cytoscape from within standalone and Notebook Python programming environ- ments. It provides nearly identical functionality to RCy3, an R package in Bioconductor available to R programmers. py4cytoscape provides: • functions that can be leveraged from Python code to implement network biology-oriented workflows; • access to user-written Cytoscape Apps that implement Cytoscape Automation protocols; • logging and debugging facilities that enable rapid development, maintenance, and auditing of Python-based workflow; • two-way conversion between the igraph and NetworkX graph packages, which enables interoperability with popular packages available in public repositories (e.g., PyPI); and • the ability to painlessly work with large data sets generated within Python or available on public repositories (e.g., STRING and NDEx). With py4cytoscape, you can leverage Cytoscape to: • load and store networks in standard and nonstandard data formats; • visualize molecular interaction networks and biological pathways; • integrate these networks with annotations, gene expression profiles and other state data; • analyze, profile, and cluster these networks based on integrated data, using new and existing algorithms. py4cytoscape enables an agile collaboration between powerful Cytoscape, Python libraries, and novel Python code so as to realize auditable, reproducible and sharable workflows. CONTENTS 1 py4cytoscape Documentation, Release 0.0.1 2 CONTENTS CHAPTER ONE AUDIENCE The audience for py4cytoscape includes biologists, mathematicians, physicists, biologists, computer scientists, and social scientists. A running sample of research based on Cytoscape can be found on Tumblr. Cytoscape provides tutorials, videos, and automation vignettes. Google Scholar reports that Cytoscape was cited in over 10,000 in academic papers in 2019, most of which executed Cytoscape via the traditional mouse and keyboard. py4cytoscape can automate these results as a means of achieving reproducible science. 3 py4cytoscape Documentation, Release 0.0.1 4 Chapter 1. Audience CHAPTER TWO PYTHON Python is a powerful programming language that allows simple and flexible representations of networks as well as clear and concise expressions of network algorithms. Python has a vibrant and growing ecosystem of packages that can be used in combination with py4cytoscape integrate with traditional workflow engines (e.g., Galaxy and Gene Pattern) to produce robust end-to-end workflows. In order to make the most out of py4cytoscape you should know how to write basic programs in Python. Among the many guides to Python, we recommend the Python documentation and Python in a Nutshell. 5 py4cytoscape Documentation, Release 0.0.1 6 Chapter 2. Python CHAPTER THREE FREE SOFTWARE py4cytoscape is free software; you can redistribute it and/or modify it under the terms of the License. We welcome contributions. Join us on GitHub. 7 py4cytoscape Documentation, Release 0.0.1 8 Chapter 3. Free Software CHAPTER FOUR HISTORY The original Python libraries for Cytoscape were written by Keiichiro Ono in 2015 as an interface to the then-new CyREST automation interface. Its original name was py2cytoscape. It was further evolved through 2019 by Kozo Nishida and Jorge Bouças. In late 2019, py4cytoscape was undertaken by Barry Demchak as a replacement for py2cytoscape. It implemented the API defined by RCy3, an R package in Bioconductor developed by a Cytoscape Automation working group consisting of Alex Pico (primary author), Mark Grimes, Julia Gustavsen, Shraddha Pai, Ruth Isserlin, Barry Demchak. RCy3 was based on prior work contributed by Paul Shannon, Tanja Muetze, Georgi Kolishkovski and Keiichiro Ono. We intend to keep the function definitions available through py4cytoscape and RCy3 consistent and synchronized going forward, and to re-integrate unique features found only in py2cytoscape. 9 py4cytoscape Documentation, Release 0.0.1 10 Chapter 4. History CHAPTER FIVE DOCUMENTATION 5.1 Install py4cytoscape requires Python 3.6, 3.7, or 3.8. 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. Below we assume you have the default 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. 5.1.1 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: Cytoscape and py4cytoscape must be running on the same workstation or virtual machine. py4cytoscape communicates with Cytoscape via a localhost connection, which precludes py4cytoscape from accessing Cytoscape remotely. While this limitation can be overcome by configuring py4cytoscape or supplying the Cytoscape URL in py4cytoscape calls, this can become a complex networking problem if firewalls and routers are present on the network. 11 py4cytoscape Documentation, Release 0.0.1 5.1.2 Install the development version (Python Console) Install the current release of py4cytoscape with pip: pip install python-igraph requests pandas networkx git clone git://github.com/bdemchak/py4cytoscape cd py4cytoscape python setup.py install # or python setup.py install --user 5.1.3 Install the development version (Jupyter Notebook) Install the current release of py4cytoscape with pip: !pip install python-igraph requests pandas networkx !pip install git+https://github.com/bdemchak/py4cytoscape !curl localhost:1234 5.1.4 Verify Cytoscape connection To verify that py4cytoscape is properly installed and able to communicate with Cytoscape, execute the following in a Python Console or Jupyter Notebook (after starting Cytoscape): import py4cytoscape as py4 dir(py4) py4.cytoscape_ping() py4.cytoscape_version_info() py4.import_network_from_file("tests\data\galfiltered.sif") 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 and loading a demonstration network. 5.1.5 Testing py4cytoscape uses the Python unittest testing package. You can learn more about unittest on its home- page. To execute tests from an OS command line, set the current directory to the py4cytoscape package directory. Then, establish the execution environment: cd tests set PYTHONPATH=.. The py4cytoscape test suite consists of a number of sub-suites. Executing one or two of them 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 the entire test suite: 12 Chapter 5. Documentation py4cytoscape Documentation, Release 0.0.1 python-m unittest To execute a single test (e.g., test_get_app_information) in a single test suite: python-m unittest test_apps.AppsTests.test_get_app_information Note: To send test output to a file, redirect stderr and console: python-m unittest2>stderr.log1>cons.log 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. 5.2 Tutorial This guide can help you start working with py4cytoscape. save this space for a simple workflow that Kozo is working on . 5.2. Tutorial 13 py4cytoscape Documentation, Release 0.0.1 5.3 Reference Release 0.0.1 Date Jun 21, 2020 5.3.1 Apps Functions for inspecting and managing apps for Cytoscape. Local Apps disable_app(app[, base_url]) Disable App. enable_app(app[, base_url]) Enable App. get_app_status(app[, base_url])