Quickstart

Installation

Isoplot requires Python 3.7 or higher. If you do not have a Python environment configured on your computer, we recommend that you follow the instructions from Anaconda. Then, open a terminal (e.g. run Anaconda Prompt if you have Anaconda installed) and type :

pip install isoplot

If you have an old version of the software installed, you can update to the latest using the following command:

pip install -U isoplot

You are now ready to start Isoplot.

There are two ways to use isoplot : through the dedicated jupyter notebook (recommended) or through the command line.

Environment installation

One of the advantages of the Anaconda Suite is that it gives access to a user-friendly GUI for the creation and maintenance of python environments. Python environments give the user a way to separate different installations of tools so that different package dependencies do not overlap with each other. This is especially useful if packages share the same dependencies but in different versions. The Anaconda Suite provides a quick and intuitive way of separating these installations.

How to create an environment in Anaconda

When the user opens up the Anaconda software, she/he ends up on the main menu:

The main window shows all the tools available for installation in the Navigator. To get to the environments page, the user must click on the “Environments” panel that is in the left-side menu.

Once on the Environments page, the user can click on the “create” button that is present at the bottom left of the screen. A pop up menu will then appear and allow the user to select a python version and a name for the environment.

Once the user clicks on the “create” button the environment is created and ready for use!

Installing packages in the environment

Now that the environment exists, it is time to populate it with the tools needed. The first thing to do is to open up a command-line interface, preferably Anaconda Prompt (it is the one that will be used in this tutorial. Other command-line interfaces might use different names for commands). Once the interface is open, the first thing to do is to activate the desired environment. The command for this is as follows:

conda activate <name-of-environment>

Once this is done the environment name should be seen on the left of the screen behind the name of the directory the interface is open in.

Once the environment is activated, the user can install using pip or conda any of the desired tools. The dependencies and the tool itself will now be installed in a safe and separate set of folders which will ensure that other installations are not affected by anything happening in the environment. Once the user is done, she/he can now close the prompt.

Jupyter Notebook

First install jupyter notebook through the Anaconda Navigator or through the dedicated website and launch the notebook.

Navigate to the Isoplot.ipynb file that you can download from the Github.

Launch the first cell to initiate the « upload data » and « submit data » buttons and use them to load in the tsv or csv IsoCor output file and generate the template file (ModifyThis.xlsx)

Modify the template as needed, save it and load it into the notebook after launching the second cell and initiating the « Upload template » and « Submit template » buttons.

Launch the next cells and generate plots !

Note

For more information on how to setup a python tool in a specific environment (recommended) using jupyter notebooks, check out this documentation.

Command-line interface

To process your data, type in a terminal :

isoplot [command line options]

Here after the available options are enumerated and detailed.

usage: isoplot [-h] --value
               [{corrected_area,isotopologue_fraction,mean_enrichment} [{corrected_area,isotopologue_fraction,mean_enrichment} ...]]
               [-m METABOLITE] [-c CONDITION] [-t TIME] [-gt]
               [-tp TEMPLATE_PATH] [-sa] [-bp] [-mb] [-IB] [-IM] [-IS] [-hm]
               [-cm] [-HM] [-s] [-v] [-a] [-z ZIP] [-g]
               input_path run_name format

Positional Arguments

input_path

Path to datafile

run_name

Name of the current run

format

Format of generated file

Named Arguments

--value

Possible choices: corrected_area, isotopologue_fraction, mean_enrichment

Select values to plot. This option can be given multiple times

Default: “isotopologue_fraction”

-m, --metabolite

Metabolite(s) to plot. For all, type in ‘all’

Default: “all”

-c, --condition

Condition(s) to plot. For all, type in ‘all’

Default: “all”

-t, --time

Time(s) to plot. For all, type in ‘all’

Default: “all”

-gt, --generate_template

Generate the template using datafile metadata

Default: False

-tp, --template_path

Path to template file

-sa, --stacked_areaplot

Create static stacked areaplot

Default: False

-bp, --barplot

Create static barplot

Default: False

-mb, --meaned_barplot

Create static barplot with meaned replicates

Default: False

-IB, --interactive_barplot

Create interactive stacked barplot

Default: False

-IM, --interactive_meanplot

Create interactive stacked barplot with meaned replicates

Default: False

-IS, --interactive_areaplot

Create interactive stacked areaplot

Default: False

-hm, --static_heatmap

Create a static heatmap using mean enrichment data

Default: False

-cm, --static_clustermap

Create a static heatmap with clustering using mean enrichment data

Default: False

-HM, --interactive_heatmap

Create interactive heatmap using mean enrichment data

Default: False

-s, --stack

Add option if barplots should be unstacked

Default: True

-v, --verbose

Turns logger to debug mode

Default: False

-a, --annot

Add option if annotations should be added on maps

Default: False

-z, --zip

Add option & path to export plots in zip file

-g, --galaxy

Option for galaxy integration. Not useful for local usage

Default: False