Getting Started¶

Installing¶

The recommended way to install ERLabPy is via conda. If you do not have conda installed, follow the installation instructions. Once you have a working conda environment, you can install ERLabPy with the conda command line tool:

conda install -c conda-forge erlab

Add any optional dependencies you want to install to the command above.

Hint

If you are using 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, see the conda-forge documentation.

If you don’t use conda, you can install ERLabPy with pip:

python -m pip install erlab

Optional dependency groups can be installed with the following commands:

python -m pip install erlab[viz]       # Install optional dependencies for visualization
python -m pip install erlab[perf]      # Install optional dependencies for performance
python -m pip install erlab[misc]      # Install miscellaneous optional dependencies
python -m pip install erlab[complete]  # Install all optional dependencies

If you wish to install ERLabPy from source, see the Contributing Guide.

Dependencies¶

ERLabPy is installed with many different python libraries. Some key packages and links to their documentation are listed below as a reference. In particular, this documentation assumes basic familiarity with the first four packages, which will be sufficient for most use cases.

Package	Used in
numpy	Computation and array manipulation, linear algebra
xarray	Data storage and manipulation
matplotlib	Plotting
scipy	Linear algebra, signal processing, and image processing
lmfit	Optimization problems including curve fitting
pyqtgraph	Interactive plotting (i.e., imagetool)

ERLabPy also requires a Qt library such as PyQt5, PyQt6, PySide2, or PySide6. To ensure compatibility and keep the namespace clean, ERLabPy imports Qt bindings from qtpy, which will automatically select the appropriate library based on what is installed.

See the User Guide to start using ERLabPy!

Optional dependencies¶

The following packages are optional dependencies that are not installed by default. They are only used in specific functions, or is not used at all but is listed just for convenience.

Package	Description
csaps	Multidimensional smoothing splines
ipywidgets	Interactive widgets
hvplot and bokeh	Interactive plotting
cmasher, cmocean, and colorcet	More colormaps!
numbagg and bottleneck	Fast multidimensional aggregation, accelerates xarray

For a full list of dependencies and optional dependencies, take a look at the [project] and [project.optional-dependencies] section in pyproject.toml:

dependencies = [
    "h5netcdf>=1.2.0",
    "igor2>=0.5.6",
    "joblib>=1.3.2",
    "lmfit>=1.2.0,!=1.3.0",
    "matplotlib>=3.8.0",
    "numba>=0.59.0",
    "numpy>=1.26.0",
    "pyperclip>=1.8.2",
    "pyqtgraph>=0.13.1",
    "qtawesome>=1.3.1",
    "qtpy>=2.4.1",
    "scipy>=1.12.0",
    "tqdm>=4.66.2",
    "uncertainties>=3.1.4",
    "varname>=0.13.0",
    "xarray>=2024.02.0",
]

[project.optional-dependencies]
complete = ["erlab[viz,perf,misc,dev]"]
viz = ["cmasher", "cmocean", "colorcet", "hvplot", "ipywidgets"]
perf = ["numbagg>=0.8.1", "bottleneck>=1.3.8"]
misc = ["iminuit>=2.25.2", "csaps>=1.1.0", "dask>=2024.4.1"]
dev = [
    "mypy",
    "pre-commit",
    "pytest-cov",
    "pytest-qt",
    "pytest-xdist",
    "pytest",
    "python-semantic-release",
    "ruff",
]
docs = [
    "sphinx",
    "sphinx-autodoc-typehints",
    "sphinx-copybutton",
    "sphinxcontrib-bibtex",
    "sphinx-qt-documentation",
    "pybtex",
    "nbsphinx",
    "furo",
    "sphinx-design",
]

Notes on compatibility¶

ERLabPy is tested on Python 3.11 and 3.12. It is not guaranteed to work on older versions of Python.
There are some known compatibility issues with PyQt5 and PySide2, so it is recommended to use the newer PyQt6 or PySide6 if possible.
If you meet any unexpected behaviour while using IPython’s autoreload extension, try excluding the following modules:
```
%aimport -erlab.io.dataloader -erlab.accessors
```