perseuspy 0.3.9
Utilities for integrating python scripts into Perseus workflows
License: MIT

perseuspy README
================

.. image:: https://readthedocs.org/projects/perseuspy/badge/?version=latest
    :target: http://perseuspy.readthedocs.io/en/latest/?badge=latest
    :alt: Documentation Status

.. sphinx-inclusion-marker-do-not-remove

.. image:: https://travis-ci.org/cox-labs/perseuspy.svg?branch=master
    :target: https://travis-ci.org/cox-labs/perseuspy

This repository contains the source code of the ``perseuspy`` software package.
``perseuspy`` contains convenience functions which allow for faster and easier development
of plugins for `Perseus <https://maxquant.org/perseus>`_ in the Python programming language.
This page contains installation instructions and developer information on ``perseuspy``, for high-level information please
refer to the manuscript listed below.

``perseuspy`` was designed to work in conjunction with the `PluginInterop <https://github.com/cox-labs/PluginInterop>`_
plugin, but can also be used stand-alone.

Citation
--------

If you use ``perseuspy`` in your projects, please cite

Rudolph, J D and Cox, J 2018, *A network module for the Perseus software for computational proteomics facilitates proteome interaction graph analysis* `doi:10.1101/447268 <https://doi.org/10.1101/447268>`_.

Installation
------------
``perseuspy`` can be installed directly from `pip`. If you are new to Python, more detailed installation instructions for windows are provided below.

.. code:: bash

    pip install perseuspy

Developing plugins
==================

Perseus provides activities to call Python scripts from within the workflow via
`PluginInterop <https://github.com/cox-labs/PluginInterop>`_, e.g. `Matrix => Python`.
Developing a plugin therefore translates to writing a Python script that follows
a small set of conventions. By adhering to these conventions, Perseus will be
able to successfully communicate with R and transfer inputs and results between
the programs. ``perseuspy`` provides the neccessary functions to make plugin development
in Python easy and straight forward.

Matrix plugin
-------------
This example Python script extracts the first 15 rows from the matrix. While its functionality
is very simple. It can serve as a starting point for more extensive scripts.

.. code:: python

    import sys
    from perseuspy import pd
    from perseuspy.parameters import *
    _, infile, outfile = sys.argv # read arguments from the command line
    df = pd.read_perseus(infile) # read the input matrix into a pandas.DataFrame
    df2 = df.head(15) # keep only the first 15 rows of the table
    df2.to_perseus(outfile) # write pandas.DataFrame in Perseus txt format

Network plugin
--------------
The following snippet can be used as a starting point for network analyses.

.. code:: python

    import sys
    from perseuspy import nx, pd, read_networks, write_networks
    _, infolder, outfolder = sys.argv # read arguments from the command line
    networks_table, networks = read_networks(infolder) # networks in tabular form
    graphs = nx.from_perseus(networks_table, networks) # graphs as networkx objects
    # perform some analysis
    _networks_table, _networks = nx.to_perseus(graphs) # convert back into tabular form
    write_networks(tmp_dir, networks_table, networks) # write to folder


Updating to the latest version
------------------------------

.. code:: bash

    pip install --upgrade perseuspy

Installation (Windows long)
---------------------------
First open a terminal by searching for ``cmd.exe`` in the start menu. Here we can easily
check if all required programs are installed.

#. Check to see if the ``pip`` executable is already available.
   ::

      pip install perseuspy

   If there is no error you are already done. If it fails, continue with the next steps.
#. Navigate to the installation directory of your Python installation. If it is installed
   e.g. ``D:/Programs/Python/`` we would first change the drive letter (maybe unnecessary)
   and then go to the installation directory.
   ::

       D:
       cd Programs/Python

   Now we should be able to run ``python`` from the command line.
   ::

       python.exe --version

   This should print the installed version of python
#. Navigate to the ``Scripts`` directory and run the installation
   ::

       cd Scripts
       pip install perseuspy

   If you want to upgrade you installation, run
   ::

       pip install --upgrade perseuspy

#. Test the installation by navigating back to the Python folder and trying to import ``perseuspy``.
   ::

       cd ..
       python.exe

   Now you should be inside the ``python`` interpreter. Check the installation by running.
   ::

       import perseuspy

   If the command doesn't produce any error you can exit ``python`` by pressing `CTRL+c`.
#. Add ``python`` to your ``PATH`` (optional, recommended). Makes it easier for Perseus to find the Python
   installation. There are many resources on how to add programs to the ``PATH`` available online. No description
   is provided here since instructions are specific to the version of Windows that is used.

Usage
------------
You can use ``perseuspy`` just like any other python module.

.. code:: python

    # import a monkey-patched version of pandas
    from perseuspy import pd
    df = pd.read_perseus('matrix1.txt')
    df2 = df.dropna()
    df2.to_perseus('matrix2.txt')


Generating the developer documentation
--------------------------------------
Run ``./generate_docs.sh`` from ``bash``.

Licensing and Contributions
---------------------------
``perseuspy`` is licensed under the MIT lisence.
Contributions are welcome! If you are interested in contributing to code or documentation,
please read `CONTRIBUTING.rst <CONTRIBUTING.rst>`_.