Getting Started

Welcome to ERLabPy! This page will guide you through the installation process and provide some tips to get you up and running with ERLabPy.

Recommended Editor Setup

For the smoothest notebook workflow, use Visual Studio Code (or VS Code-based editors such as Cursor, Windsurf, or Antigravity) with:

  1. The Jupyter extension

  2. The dedicated erlab extension

This setup enables convenient ERLabPy actions directly from notebooks and the editor UI.

AI Assistance

For quick guidance while working with ERLabPy (including installation):

  • Use the ARPES Analysis Assistant custom GPT for ChatGPT-based help.

    The assistant is trained on ERLabPy documentation and can help with code examples, explanations of functions and parameters, and general guidance on installing and using the package.

  • Ask questions and explore auto-generated docs at DeepWiki.

    Advanced users may also consider connecting the DeepWiki MCP (Model Context Protocol, not microchannel plates 😉) server to their LLM setup.

  • An agent skill for ERLabPy is available in the GitHub repository (beta).

Warning

LLMs are not a source of truth. Always verify API details in the documentation and validate results on your own data. LLM-generated code may contain errors or inaccuracies. Always review and test code generated by LLMs to ensure it works correctly and is appropriate for your use case.

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:

  • Environment-based (e.g. pip, conda)

  • Project-based (e.g. uv, pixi)

  • From source (for debugging and development)

In environment-based workflows you install packages into an environment, which you can activate and deactivate from any directory. These workflows are well-established and easy to get started with, but they can lead to issues with reproducibility and dependency conflicts if not managed carefully.

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. The project-based workflow is more modern and has better reproducibility, but is less widely adopted and may have a steeper learning curve for users new to Python or package management.

Tip

If you are new to Python or unsure which method to choose, start with the Environment-based method using conda.

The two main tools that install Python packages are pip and conda. Their functionality partially overlaps (both can install Python packages), however, they can also work together. We’ll discuss the major differences between pip and conda here - this is important to understand if you want to manage packages effectively.

The first difference is that conda is cross-language and it can install Python, while pip is installed for a particular Python on your system and installs other packages to that same Python install only. This also means conda can install non-Python libraries and tools you may need (e.g. compilers, CUDA, HDF5), while pip can’t.

The second difference is that pip installs from the Python Packaging Index (PyPI), while conda installs from its own channels (typically “conda-forge”). PyPI is the largest collection of packages by far, however, all popular packages are available for conda as well.

The third difference is that conda is an integrated solution for managing packages, dependencies and environments, while with pip you may need another tool (there are many!) for dealing with environments or complex dependencies.

Installing with conda

Miniforge is the recommended way to install conda. 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 pyqt6 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=*=*_newaccelerate"

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

  1. Install Python.

  2. Create and activate a virtual environment with venv.

    Hint

    See the tutorial in the Python Packaging User Guide.

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

Installing with uv

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

  1. Install uv following the instructions in the uv documentation.

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

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

Installing with pixi

Here is a step-by-step guide to setting up a workspace to use erlab with pixi.

  1. Install pixi following the instructions in the pixi documentation.

  2. Create a new workspace in a new subdirectory by executing the following in a terminal:

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

  3. Add erlab and the recommended dependencies to your workspace:

    pixi add erlab pyqt6 ipywidgets

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

Note

Interactive tools in erlab.interactive require 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 = [
    "dask[distributed]>=2024.4.1",
    "findiff>=0.12.0",
    "h5netcdf>=1.7.1",
    "igor2>=0.5.13",
    "igorwriter>=0.6.1",
    "joblib>=1.3.2",
    "lazy-loader>=0.4",
    "lmfit>=1.3.2",
    "ipykernel>=6.29.5,!=7.2.0",
    "matplotlib>=3.8.0",
    "numba>=0.63.0; sys_platform != 'darwin' or platform_machine != 'x86_64'",
    "numba>=0.61.0,<0.63.0; sys_platform == 'darwin' and platform_machine == 'x86_64'",
    "numexpr>=2.11.0",
    "numpy>=1.26.0",
    "packaging>=24.0",
    "pickleshare>=0.7.5",
    "pydantic>=2.11.7",
    "pyperclip>=1.8.2",
    "pyqtgraph>=0.13.1",
    "pyzmq>=27.0.2",
    "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.5.4",
    "pygments>=2.11.0",
    "xraydb>=4.5.8",
]


[project.optional-dependencies]
complete = ["erlab[viz,io,perf,misc]"]
viz = ["hvplot>=0.11.0,!=0.12.0", "ipywidgets"]
io = [
    "astropy>=5.1.1",
    "nexusformat>=1.0.6",
    "zarr>=3.1.2",
]
perf = ["numbagg>=0.8.1"]
misc = ["iminuit>=2.25.2,!=2.31.2", "csaps>=1.1.0", "numdifftools>=0.9.42"]

Notes on compatibility

  • ERLabPy supports Python 3.11 and later.

  • Qt5 bindings (PyQt5 and PySide2) are not supported. Use Qt6 bindings, such as PyQt6 or PySide6.