Ctrl+K

1. Installing pysarpro#

How you should install pysarpro depends on your needs and skills:

1.1. Supported platforms#

  • Windows 64-bit on x86 processors

  • macOS on x86 and M (ARM) processors

  • Linux 64-bit on x86 processors

While we do not officially support other platforms, you could still try building from source.

1.2. Version check#

To see whether pysarpro is already installed or to check if an install has worked, run the following in a Python shell or Jupyter notebook:

import pysarpro as sarpro

print(sarpro.__version__)

or, from the command line:

python -c "import pysarpro; print(pysarpro.__version__)"

(Try python3 if python is unsuccessful.)

You’ll see the version number if pysarpro is installed and an error message otherwise.

1.3. Installation via pip and conda#

These install only pysarpro and its dependencies; pip has an option to include related packages.

1.3.1. pip#

Prerequisites to a pip install: You’re able to use your system’s command line to install packages and are using a virtual environment (any of several).

While it is possible to use pip without a virtual environment, it is not advised: virtual environments create a clean Python environment that does not interfere with any existing system installation, can be easily removed, and contain only the package versions your application needs. They help avoid a common challenge known as dependency hell.

To install the current pysarpro you’ll need at least Python 3.10. If your Python is older, pip will find the most recent compatible version.

# Update pip
python -m pip install -U pip
# Install pysarpro
python -m pip install -U pysarpro

To access the full selection of demo datasets, use pysarpro[data]. To include a selection of other scientific Python packages that expand pysarpro’s capabilities to include, e.g., parallel processing, you can install the package pysarpro[optional]:

python -m pip install -U pysarpro[optional]

Warning

Please do not use the command sudo and pip together as pip may overwrite critical system libraries which may require you to reinstall your operating system.

1.3.2. conda#

Miniconda is a bare-essentials version of the Anaconda package; you’ll need to install packages like pysarpro yourself. Like Anaconda, it installs Python and provides virtual environments.

Once you have your conda environment set up, you can install pysarpro with the command:

conda install pysarpro

1.4. System package managers#

Using a package manager (yum, apt-get, etc.) to install pysarpro or other Python packages is not your best option:

  • You’re likely to get an older version.

  • You’ll probably want to make updates and add new packages outside of the package manager, leaving you with the same kind of dependency conflicts you see when using pip without a virtual environment.

  • There’s an added risk because operating systems use Python, so if you make system-wide Python changes (installing as root or using sudo), you can break the operating system.

1.5. Downloading all demo datasets#

Some of the data used in our examples is hosted online and is not installed by default by the procedures explained above. Data are downloaded once, at the first call, but this requires an internet connection. If you prefer downloading all the demo datasets to be able to work offline, ensure that package pooch is installed and then run this command:

python -c 'import pysarpro as sarpro; sarpro.data.download_all()'

or call sarpro.data.download_all() in your favourite interactive Python environment (IPython, Jupyter notebook, …).

1.6. Additional help#

If you still have questions, reach out through

To suggest a change in these instructions, please open an issue on GitHub.

2. Installing pysarpro for contributors#

We are assuming that you have a default Python environment already configured on your computer and that you intend to install pysarpro inside of it.

We also make a few more assumptions about your system:

  • You have a C compiler set up.

  • You have a C++ compiler set up.

  • You are running a version of Python compatible with our system as listed in our pyproject.toml.

  • You’ve cloned the git repository into a directory called pysarpro. You have set up the upstream remote to point to our repository and origin to point to your fork.

This directory contains the following files:

pysarpro
├── asv.conf.json
├── azure-pipelines.yml
├── benchmarks/
├── CITATION.bib
├── CODE_OF_CONDUCT.md
├── CONTRIBUTING.rst
├── CONTRIBUTORS.txt
├── doc/
├── INSTALL.rst
├── LICENSE.txt
├── MANIFEST.in
├── meson.build
├── meson.md
├── pyproject.toml
├── README.md
├── RELEASE.txt
├── requirements/
├── requirements.txt
├── pysarpro/
├── TODO.txt
└── tools/

All commands below are assumed to be running from the pysarpro directory containing the files above.

2.1. Build environment setup#

Once you’ve cloned your fork of the pysarpro repository, you should set up a Python development environment tailored for pysarpro. You may choose the environment manager of your choice. Here we provide instructions for two popular environment managers: venv (pip based) and conda (Anaconda or Miniconda).

2.1.1. venv#

# Create a virtualenv named ``pysarpro-dev`` that lives outside of the repository.
# One common convention is to place it inside an ``envs`` directory under your home directory:
mkdir ~/envs
python -m venv ~/envs/pysarpro-dev
# Activate it
# (On Windows, please use ``pysarpro-dev\Scripts\activate``)
source ~/envs/pysarpro-dev/bin/activate
# Install main development and runtime dependencies
pip install -r requirements.txt
# Install build dependencies of pysarpro
pip install -r requirements/build.txt
# Build pysarpro from source
spin build
# The new version lives under `${PWD}/build-install/.../site-packages`.
# Test your installation
spin test
# Build docs
spin docs
# Try the new version in IPython
spin ipython

2.1.2. conda#

When using conda for development, we recommend adding the conda-forge channel for the most up-to-date version of many dependencies. Some dependencies we use (for testing and documentation) are not available from the default Anaconda channel. Please follow the official conda-forge installation instructions before you get started.

# Create a conda environment named ``pysarpro-dev``
conda create --name pysarpro-dev
# Activate it
conda activate pysarpro-dev
# Install main development and runtime dependencies
conda install -c conda-forge --file requirements/default.txt
conda install -c conda-forge --file requirements/test.txt
conda install -c conda-forge pre-commit
# Install main development and runtime dependencies
pip install -r requirements.txt
# Install build dependencies of pysarpro
pip install -r requirements/build.txt
# Install docs dependencies of pysarpro
pip install -r requirements/docs.txt
# Build pysarpro from source
spin build
# The new version lives under `${PWD}/build-install/.../site-packages`.
# Test your installation
spin test
# Build docs
spin docs
# Try the new version in IPython
spin ipython

For more information about building and using the spin package, see meson.md.

2.2. Testing#

Test your installation for correct behavior using:

pytest pysarpro

2.3. Updating the installation#

Before updating your installation, you typically want to grab the latest source:

git checkout main
git pull upstream main

And you likely want to create a feature branch from there. As you work on this branch, you can re-build pysarpro using:

spin build

Repeated, incremental builds usually work just fine, but if you notice build problems, rebuild from scratch using:

spin build --clean

2.4. Platform-specific notes#

Windows

A run-through of the compilation process for Windows is included in our setup of Azure Pipelines (a continuous integration service).

Debian and Ubuntu

Install suitable compilers:

sudo apt-get install build-essential

2.5. Full requirements list#

Build Requirements

# Generated via tools/generate_requirements.py and pre-commit hook.
# Do not edit this file; modify pyproject.toml instead.
meson-python>=0.15
wheel
setuptools>=67
packaging>=21
ninja
Cython>=3.0.4
pythran
numpy>=1.23
spin==0.7
build

Runtime Requirements

# Generated via tools/generate_requirements.py and pre-commit hook.
# Do not edit this file; modify pyproject.toml instead.
numpy>=1.23
scipy>=1.8
networkx>=2.8
pillow>=9.1
imageio>=2.33
tifffile>=2022.8.12
packaging>=21
lazy_loader>=0.3

Test Requirements

# Generated via tools/generate_requirements.py and pre-commit hook.
# Do not edit this file; modify pyproject.toml instead.
asv
matplotlib>=3.6
numpydoc>=1.5
pooch>=1.6.0
pytest>=7.0
pytest-cov>=2.11.0
pytest-localserver
pytest-faulthandler

Documentation Requirements

# Generated via tools/generate_requirements.py and pre-commit hook.
# Do not edit this file; modify pyproject.toml instead.
sphinx>=7.2
sphinx-gallery>=0.14
numpydoc>=1.6
sphinx-copybutton
pytest-runner
matplotlib>=3.6
dask[array]>=2022.9.2
pandas>=1.5
seaborn>=0.11
pooch>=1.6
tifffile>=2022.8.12
myst-parser
ipywidgets
ipykernel
plotly>=5.10
kaleido
scikit-learn>=1.1
sphinx_design>=0.5
pydata-sphinx-theme>=0.14.1
PyWavelets>=1.1.1

Developer Requirements

# Generated via tools/generate_requirements.py and pre-commit hook.
# Do not edit this file; modify pyproject.toml instead.
pre-commit
ipython
tomli; python_version < '3.11'

Data Requirements

The full selection of demo datasets is only available with the following installed:

# Generated via tools/generate_requirements.py and pre-commit hook.
# Do not edit this file; modify pyproject.toml instead.
pooch>=1.6.0

Optional Requirements

You can use pysarpro with the basic requirements listed above, but some functionality is only available with the following installed:

  • SimpleITK

    Optional I/O plugin providing a wide variety of formats. including specialized formats using in medical imaging.

  • Astropy

    Provides FITS I/O capability.

  • PyAMG

    The pyamg module is used for the fast cg_mg mode of random walker segmentation.

  • Dask

    The dask module is used to speed up certain functions.

# Generated via tools/generate_requirements.py and pre-commit hook.
# Do not edit this file; modify pyproject.toml instead.
SimpleITK
astropy>=5.0
cloudpickle>=0.2.1
dask[array]>=2021.1.0
matplotlib>=3.6
pooch>=1.6.0
pyamg
PyWavelets>=1.1.1
scikit-learn>=1.1

2.6. Help with contributor installation#

See Additional help above.

On this page
Show Source