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.

  • If you are new to Python, Scientific Python Lectures is a great resource to get started with Python for scientific computing.

  • 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 before diving into 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:

  • 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:

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

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.

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. 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 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=*=*_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.

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.12",
    "igorwriter>=0.6.1",
    "joblib>=1.3.2",
    "lazy-loader>=0.4",
    "lmfit>=1.3.2",
    "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",
]


[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",
    "zarr>=3.1.2",
]
perf = ["numbagg>=0.8.1", "xxhash>=3.5.0"]
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.