Installation

The installation of piva has been tested on macOS, Windows, and Linux. You can install it either from source or using a package manager. The following guidelines are designed to help you avoid most common installation issues.

To begin, regardless of the installation method you choose, download and install Conda to set up a virtual environment for the installation.

Installation from Sources

To ensure all dependencies are properly handled, it is recommended to install the package from source by cloning the GitHub repository:

git clone https://github.com/pudeIko/piva.git

Note

Installing the package from GitHub may require git. If it’s not already installed, you can add it using:

conda install git

Next, navigate to the downloaded directory and run the following command:

cd piva
conda env create -f environment.yml

This will create and activate a virtual environment named piva-env and install piva in editable mode, allowing for easier modifications and enhancements to the code.

To activate the environment and start the software, simply run:

conda activate piva-env
piva

This will open the DataBrowser window.

Installation via PyPi

Alternatively, piva can be installed using the PyPI package manager.

This approach requires creating a virtual environment manually first. As in the example below, it is recommended to use Python version 3.10.8:

conda create --name piva-env python==3.10.8
[some output]
conda activate piva-env

Inside the activated virtual environment, upgrade pip and install piva:

pip install --upgrade pip
pip install piva

To start the software and open the DataBrowser window, run:

piva

Testing

Once installed, correct configuration of the package can be verified by following methods:

1. From the Menu bar of the opened DataBrowser, navigate to Open -> Example. This will bring up an example dataset that can be used to test the functionalities of the piva package and get a feel for the GUI.

2. Using implemented automated tests.

   One can simply navigate to the project root and run:

   pytest
   

   Alternatively, specific tests can be executed separately:

   • To check proper behavior of implemented Dataloaders run:

     python -m piva.tests.dataloaders_test
     

     Which will print to the terminal list of correctly loaded files.

   • DataViewers can be tested with:

     python -m piva.tests.viewers_test
     

     This will start new piva session, execute sequence of actions emulating a physical user and test basic functionalities of the GUI.

   • Functinalities using JupyterLab can be checked with a semi-automated test by running:

     python -m piva.tests.jupyter_test
     

     This will create example Jupyter notebooks, start a JupyterLab server, stop the server, and remove the created files.

     Note

     When running on Windows, users might need to stop the server (started on port 56789) manually. To do so, after executing the test, run:

     jupyter-lab stop 56789
     

Successful execution of the tests should give a message like:

-- Docs: https://docs.pytest.org/en/stable/how-to/capture-warnings.html
================ 4 passed, 7 warnings in 108.44s (0:01:48) ================

Note

Running on Linux with wayland. If you are faced with an error of the form Warning: Ignoring XDG_SESSION_TYPE=wayland on Gnome. Use QT_QPA_PLATFORM=wayland to run on Wayland anyway. you can work around this by setting XDG_SESSION_TYPE=xcb (as opposed to wayland as the error message would suggest). Do this either by running export XDG_SESSION_TYPE=xcb in the shell you are working with, or directly at the piva command: XDG_SESSION_TYPE=xcb; piva.

Dependencies

This software is built upon on a number of other open-source frameworks. The complete list of packages is:

data_slicer>=1.0.2
h5py>=3.11.0
igor2>=0.5
ipywidgets>=7.6.3
julia>=0.5.6
jupyterlab>=3.5
jupyterthemes>=0.20.0
matplotlib>=3.3.4
numba>=0.57.0
numpy<2.0.0
openpyxl>=3.0.9
pandas>=1.3.5
pydantic>=2.0.0
pyqt5>=5.15.0
pyqtgraph>=0.13.1
scipy>=1.6.0
tqdm>=4.56.0
typing>=3.7

Most notably, this includes:

• pyqtgraph for fast live visualizations and widgets,

• numpy for numerical operations,

• jupyterlab for running deeper analysis and implementation of the experimental logbooks

• matplotlib for plot exporting functionalities.