Python integration

JIPipe provides nodes that allow to execute native Python (CPython) code and use it to process data. All nodes that are relevant to Python processing can be found in the Miscellaneous | Python script category. The following nodes are available:

Python script (iterating) ⭐

(Most commonly used node)

Executes the Python script for each iteration step. Each slot receives exactly one data item per step.

Python script (merging)

Executes the Python script for each iteration step. Each slot receives multiple data items per step if they cannot be separated by annotations.

Python script (multi-parameter capable, custom)

(Rarely used special case)

Executes the Python script exactly once that will receive all the data at once.

Background

The JIPipe Python integration basically works by applying the following steps:

Create temporary directories for inputs and outputs
Write all input data to its temporary directory in JIPipe's data table format.
Run the Python script, but also tell it where it can find the input and output folders
Let JIPipe read all data from the output directory. The data must be in JIPipe's data table format.

Most of the steps are already covered by the Python integration node and the JIPipe Python adapter library that is automatically injected into the Python script.

Writing Python scripts

Generally, you can use all Python libraries that are available to you in the currently configured Python environment. But to facilitate the data transfer between JIPipe and Python, you will need to use the functionality provided by JIPipe's adapter libraries and injected variables.

JIPipe-generated variables

On executing a Python script, JIPipe will automatically inject the following global variables into the Python script:

Name	Description
`jipipe_inputs`	Dictionary where the keys are named according to the node's input slots and the values contain a representation of the data contained within the slot.
`jipipe_outputs`	Dictionary where the keys are named according to the node's output slots and the values contain an object that will allow to write outputs.
`jipipe_annotations`	Dictionary (string to string) that contains the text annotations associated to the current iteration step. Data annotations are currently not supported. Only text annotations can be passed.
`jipipe_variables`	Dictionary that contains variables from the Script parameters parameter of the node.

Importing data from JIPipe into Python

To copy data from the JIPipe into a Python variable you will need to get the correct input slot from the jipipe_inputs variable. For example, to obtain the input slot Input as variable ds, write:

ds = jipipe_inputs["Input"]

Depending on which kind of data you want to use, you will have the following options:

The jipipe.imagej module provided by JIPipe's Python adapter offers a convenient functions to either obtain a file path to an image or directly load it using skimage.io.imread.

                    # Do not forget to import
                    from jipipe.imagej import *

                    # Get the data table
                    ds = jipipe_inputs["Input"]

                    # Option 1: Load the image with skimage
                    img = load_image_file(ds, row=0)

                    # Option 2: Get the path to the image and use it with any library
                    # It will likely be a TIFF or OME TIFF, but can also be PNG/BMP/JPG
                    img_path = get_image_file(ds, row=0)
                

The jipipe.imagej module provided by JIPipe's Python adapter offers a convenient functions to either obtain a file path to the CSV exported table or directly load it as pandas.DataFrame.

                    # Do not forget to import
                    from jipipe.imagej import *

                    # Get the data table
                    ds = jipipe_inputs["Input"]

                    # Option 1: Load the CSV table with Pandas
                    df = load_table_file(ds, row=0)

                    # Option 2: Get the path to the CSV table and use it with any library
                    img_path = get_table_file(ds, row=0)
                

If the data type is neither a table nor an image, you can obtain the row folder that contains the file(s) that represent the data.

                    # Get the data table
                    ds = jipipe_inputs["Input"]

                    # Get the path where the data is stored
                    folder = data_slot.get_row_storage_path(row=0)

                    # You can use for example folder.glob("*.csv") to extract all csv files
                    # Please adapt this for your data
                

Exporting data from Python into JIPipe

JIPipe expects that data is placed at very specific locations, following a highly standardized format. To do this conveniently, you will need to get the correct output slot from the jipipe_outputs variable. For example, to obtain the output slot Output as variable dso, write:

dso = jipipe_outputs["Output"]

Depending on which kind of data and which libraries you want to export, you will have the following options:

The jipipe.imagej module provided by JIPipe's Python adapter offers a convenient functions to add a Numpy array as image into an output slot.

                    # Do not forget to import
                    from jipipe.imagej import *

                    # Assume we have an image img

                    # Get the data table
                    dso = jipipe_outputs["Output"]

                    # Add the image into the slot (without annotations)
                    add_image(img, dso)

                    # You can also create text annotations (set annotation "test" to the value "value")
                    add_image(img, dso, text_annotations={"test", "value"})
                

The jipipe.imagej module provided by JIPipe's Python adapter offers a convenient functions to add a Pandas DataFrame as Results Table into an output slot.

                    # Do not forget to import
                    from jipipe.imagej import *

                    # Assume we have a data frame df

                    # Get the data table
                    dso = jipipe_outputs["Output"]

                    # Add the image into the slot (without annotations)
                    add_table(df, dso)

                    # You can also create text annotations (set annotation "test" to the value "value")
                    add_table(df, dso, text_annotations={"test", "value"})
                

If you utilize a library that does not convert images into Numpy arrays, you will have to export the image manually into TIFF or PNG. To do this, you will have to add a new row into the output table and manually save data into the row folder.

                    from pathlib import Path

                    # For example we have a matplotlib plot

                    # Get the data table
                    dso = jipipe_outputs["Output"]

                    # Add the row into the output
                    output_row = dso.add_row() # Here we can also add text_annotations if needed

                    # We get the path where JIPipe expects the data
                    output_row_path = dso.get_row_storage_path(output_row)

                    # Export the image via our library
                    # For example with matplotlib
                    plt.savefig(output_row_path / Path("data.png"))
                

If you are working with other data types, please read about how JIPipe stores this particular type by navigating to Help | Data type documentation and going to the Data storage section.

                    from pathlib import Path

                    # Get the data table
                    dso = jipipe_outputs["Output"]

                    # Add the row into the output
                    output_row = dso.add_row() # Here we can also add text_annotations if needed

                    # We get the path where JIPipe expects the data
                    output_row_path = dso.get_row_storage_path(output_row)

                    # Export everything into output_row_path
                

Debugging Python scripts

While JIPipe currently does not have any advanced debugging features, you can utilize the log entry generated by JIPipe to identify errors and even run your pipeline outside JIPipe.

Full script printout: As JIPipe applies modifications to your script, it will print the final script into the log window:
Commandline run command: JIPipe will also log all environment variables and the full run command:
Python stdout/stderr output: JIPipe will also log all standard out and standard error messages directly after the run command.

JIPipe-provided python

JIPipe will automatically take care of setting up Python for you and select the newest available artifact for you. The following Python versions with the specified libraries are available:

                    asciitree==0.3.3
                    contourpy==1.3.0
                    cycler==0.12.1
                    fasteners==0.19
                    filelock==3.13.1
                    fonttools==4.53.1
                    fsspec==2024.2.0
                    imageio==2.35.1
                    Jinja2==3.1.3
                    joblib==1.4.2
                    kiwisolver==1.4.7
                    lazy_loader==0.4
                    looseversion==1.3.0
                    MarkupSafe==2.1.5
                    matplotlib==3.9.2
                    mpmath==1.3.0
                    networkx==3.3
                    numcodecs==0.13.0
                    numpy==2.1.1
                    opencv-python==4.10.0.84
                    packaging==24.1
                    pandas==2.2.2
                    patsy==0.5.6
                    pillow==10.4.0
                    plotly==5.24.1
                    Pygments==2.18.0
                    pyparsing==3.1.4
                    python-dateutil==2.9.0.post0
                    pytz==2024.2
                    PyYAML==6.0.2
                    scikit-image==0.24.0
                    scikit-learn==1.5.2
                    scipy==1.14.1
                    seaborn==0.13.2
                    SimpleITK==2.4.0
                    six==1.16.0
                    statsmodels==0.14.3
                    sympy==1.12
                    tenacity==9.0.0
                    threadpoolctl==3.5.0
                    tifffile==2024.8.30
                    torch==2.4.1+cpu
                    torchaudio==2.4.1+cpu
                    torchvision==0.19.1+cpu
                    trackpy==0.6.4
                    typing_extensions==4.12.2
                    tzdata==2024.1
                    vedo==2024.5.2
                    vtk==9.3.1
                    zarr==2.18.3
                

                    imageio==2.19.3
                    joblib==1.1.0
                    networkx==2.8.4
                    numpy==1.23.1
                    packaging==21.3
                    Pillow==9.2.0
                    pyparsing==3.0.9
                    python-dateutil==2.8.2
                    pytz==2022.1
                    PyWavelets==1.3.0
                    scikit-image==0.19.3
                    scikit-learn==1.1.1
                    scipy==1.8.1
                    six==1.16.0
                    threadpoolctl==3.1.0
                    tifffile==2022.5.4
                

Overriding the Python version

You can always override the utilized Python version on a node, project, and application level.

Click the Infos & Settings button at the top right.
Go to the Settings tab on the right-hand side and select Plugins | Python integration.
Ensure that Project default environment is enabled.
Click the Configure ... button and select one of the options.

Select the node you want to change
Go to the Parameters panel and activate the parameter Override Python environment.
Click the Configure ... button located next to the Override Python environment parameter and select one of the options.

Navigate to Project | Application settings
Select Plugins | Python integration
Click the Configure ... button located next to Default Python environment and select one of the options.
If you want to reset this setting, click the arrow next to the help symbol and select Restore to default value. If this didn't help, reset the application settings.

Last modified: 19 September 2024