Python-Perseus interop using perseuspy

Utility and covenience functions for Python-Perseus interop. Building on the pandas package. If you intend to develop a plugin for Perseus, please see PluginInterop.

Installation (short)

pip install perseuspy

Updating to the latest version

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.

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

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

    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

  3. 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
  4. Test the installation by navigating back to the Python folder and trying to import perseuspy.

    cd ..

    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.

  5. Add python to your PATH (optional). Makes it easier for Perseus to find the Python installation. There are many resources on how to add programs to the PATH available online.


You can use perseuspy just like any other python module.

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

Plugin template

The following snippet can be used as a starting point for python scripting in Perseus.

import sys
from perseuspy import pd
from perseuspy.parameters import *
_, paramfile, infile, outfile = sys.argv # read arguments from the command line
parameters = parse_parameters(paramfile) # parse the parameters file
df = pd.read_perseus(infile) # read the input matrix into a pandas.DataFrame
some_value = doubleParam(parameters, 'some value') # extract a parameter value
df2 = some_value / df.drop('Name', 1)
df2.to_perseus(outfile) # write pandas.DataFrame in Perseus txt format

Network Plugin template

The following snippet can be used as a starting point for python scripting in Perseus (for networks).

import sys
from perseuspy import nx, pd, read_networks, write_networks
_, paramfile, 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
_networks_table, _networks = nx.to_perseus(graphs) # convert back into tabular form
write_networks(tmp_dir, networks_table, networks) # write to folder

Generating the documentation

Run ./ from bash.

Licensing and Contributions

perseuspy is licensed under the MIT lisence. Contributions are welcome!

Indices and tables