Getting Started¶

Welcome to ERLabPy! This documentation will guide you through the installation process and provide an overview of the package.

If you are new to programming with Python, check out Scientific Python Lectures as a great starting point.

Data structures in ERLabPy are represented using xarray[1], which provides a powerful data structure for working with multi-dimensional arrays. Be sure to review the xarray tutorial and the xarray user guide to get familiar with it.

Installing¶

Note

Parts of this section are based on Scipy’s installation guide and NumPy’s installation guide.

The recommended method of installation depends on your preferred workflow. The common workflows can roughly be broken down into the following categories:

Project-based (e.g. uv, pixi) (recommended)
Environment-based (e.g. pip, conda) (the traditional workflow)
From source (for debugging and development)

In project-based workflows, a project is a directory containing a manifest file describing the project, a lock-file describing the exact dependencies of the project, and the project’s (potentially multiple) environments.

In contrast, in environment-based workflows you install packages into an environment, which you can activate and deactivate from any directory. These workflows are well-established, but lack some reproducibility benefits of project-based workflows.

Choose the method that best suits your needs. If you’re unsure, start with the project-based workflow using uv.

Project Based

Installing with uv

Here is a step-by-step guide to setting up a project to use erlab, with uv, a Python package manager.

Install uv following the instructions in the uv documentation.
Create a new project in a new subdirectory by executing the following in a terminal:
```
uv init my-project
cd my-project
```
Hint

The second command changes directory into your project’s folder. You can name the project whatever you like.
Add the erlab package to your project with all recommended optional dependencies:
```
uv add "erlab[complete]"
```
Note

This will automatically install Python if you don’t already have it installed!

Hint

You can also add other packages to your project in the same way, e.g. uv add matplotlib.

Environment Based

The two main tools that install Python packages are pip and conda. Their functionality partially overlaps (both can install Python packages), but they also have differences:

Conda is cross-language and can install Python along with non-Python libraries and tools (e.g. compilers, CUDA, HDF5).
Pip installs packages from the Python Packaging Index (PyPI) for a particular Python install.
Conda provides an integrated solution for managing packages, dependencies and environments, whereas with pip you might need additional tools.

Installing with conda

Miniforge is the recommended way to install conda and mamba. If you are new to conda, the Scikit-HEP project has a great guide to get you started.

After creating an environment, install erlab from conda-forge as follows:

conda install -c conda-forge erlab

Or with the recommended dependencies:

conda install -c conda-forge erlab pyside6 hvplot ipywidgets

If you require other optional dependencies, append them to the above command.

Hint

If you are using conda on macOS, you might experience degraded performance with the default BLAS and LAPACK libraries.

For Apple Silicon Macs, use Accelerate:

conda install "libblas=*=*accelerate"

For Intel Macs, use MKL:

conda install "libblas=*=*mkl"

To prevent conda from switching back to the default libraries upon updating, see the conda-forge documentation.

Installing with pip

Install Python.
Create and activate a virtual environment with venv.

Hint

See the tutorial in the Python Packaging User Guide.
Install erlab with pip, including all recommended optional dependencies:
```
python -m pip install erlab[complete] pyqt6
```

For a list of all available optional dependencies, see the optional dependencies section.

From Source

For advanced users and developers who want to customize, debug, or contribute to ERLabPy, see the contributing guide for more information.

Importing¶

Once installed, you can import ERLabPy in your Python scripts or interactive sessions.

The recommended import conventions are:

import erlab
import erlab.analysis as era
import erlab.interactive as eri
import erlab.plotting as eplt

A more comprehensive set of imports might look like:

import erlab
import erlab.analysis as era
import erlab.interactive as eri
import erlab.plotting as eplt
import matplotlib.pyplot as plt
import numpy as np
import xarray as xr

xr.set_options(keep_attrs=True)

Note

The interactive plotting module, erlab.interactive, requires a Qt library (such as PyQt6 or PySide6). If one is not installed, ERLabPy will notify you upon import.

Dependencies¶

ERLabPy depends on several scientific Python libraries. The table below lists some of the key packages and their roles in the scientific Python ecosystem:

Package	Used in
numpy	Computation and array manipulation, linear algebra
scipy	Linear algebra, signal processing, and image processing
xarray	Data storage and manipulation
numba	Just-in-time compilation for significant speedups
matplotlib	Plotting
lmfit	Solving optimization problems and curve fitting

For interactive plotting, a Qt library such as PyQt6 or PySide6 is required. ERLabPy imports Qt bindings from qtpy, which automatically selects the appropriate library based on what is installed.

See the user-guide to get started with ERLabPy!

Optional dependencies¶

For a full list of dependencies and optional dependency groups, check the [project] and [project.optional-dependencies] sections in pyproject.toml:

dependencies = [
    "findiff>=0.12.0",
    "h5netcdf>=1.2.0",
    "igor2>=0.5.12",
    "igorwriter>=0.6.1",
    "joblib>=1.3.2",
    "lazy-loader>=0.4",
    "lmfit>=1.3.2",
    "matplotlib>=3.8.0",
    "numba>=0.61.0",
    "numpy>=1.26.0",
    "pickleshare>=0.7.5",
    "pyperclip>=1.8.2",
    "pyqtgraph>=0.13.1",
    "qtawesome>=1.3.1",
    "qtconsole>=5.6.0",
    "qtpy>=2.4.1",
    "scipy>=1.15.0",
    "tqdm>=4.66.2",
    "varname>=0.13.0",
    "xarray>=2024.10.0",
    "xarray-lmfit>=0.2.1",
]

[project.optional-dependencies]
complete = ["erlab[viz,io,perf,misc]"]
viz = ["hvplot>=0.11.0,!=0.12.0", "ipywidgets"]
io = ["astropy>=5.1.1", "libarchive-c>=5.2", "nexusformat>=1.0.6"]
perf = ["numbagg>=0.8.1"]
misc = ["iminuit>=2.25.2", "csaps>=1.1.0", "dask>=2024.4.1"]

Notes on compatibility¶

ERLabPy supports Python 3.11 and later.
There are some known compatibility issues with PyQt5 and PySide2. It is recommended to use PyQt6 or PySide6 if possible.