Installation

Installation#

Do NOT use pip

Due to the cross-language nature of pymer4 installing via pip is not officially supported.
Please use one of the two options below.

ATTENTION: Windows Users

Unfortunately, Windows it not officially supported as package installation can be unreliable. We recommend using the Windows Subsystem for Linux (WSL) and setting up a conda install through there. Alternatively you can try to follow this guide to setup an R installation with the rpy2 Python library.

1. Using Anaconda#

If you don’t already have Anaconda/Miniconda setup, follow first follow the instructions here

To install into existing environment use

conda install -c ejolly -c conda-forge pymer4

To create a new environment with additional scientific Python libraries

conda create --n pymer4 -c ejolly -c conda-forge pymer4

You can test the installation by running the following command in a terminal within the environment you installed pymer4

python -c "from pymer4 import test_install; test_install()"

Note

The -c conda-forge in the the conda commands above ensures that additional dependencies for pymer4 are installed via the conda-forge channel which contains the relevant R packages, rather than Anaconda defaults which does not.

2. Using Pixi#

Pixi.sh is a new modern Python package and environment manager that works with uv and conda-forge allowing you mix-and-match pip and conda packages. It uses a pyproject.toml file as the blueprints for an isolated environment and python package. Rather than updating that file yourself, you use various pixi commands which will keep this file up-to-date. This works similarily to npm in Javascript.

After installing pixi, you can create a fresh project called myproject using:

pixi init --format pyproject --channel ejolly --channel conda-forge myproject

Then just install pymer4 using:

pixi add pymer4

All the changes you make with pixi commands like add modify the pyproject.toml file. For example, we can add additional dependencies, e.g. jupyter notebook support, plotting, etc:

pixi add seaborn ipykernel

Or packages from pip:

pixi add --pypi polars

Which will produce a file like this tracking our channels (ejolly, conda-forge, pip), dependencies, and versions:

[project]
authors = [{ name = "ejolly", email = "eshin.jolly@gmail.com" }]
name = "myproject"
requires-python = ">= 3.11"
version = "0.1.0"
dependencies = ["polars"]

[build-system]
build-backend = "hatchling.build"
requires = ["hatchling"]

[tool.pixi.workspace]
channels = ["ejolly", "conda-forge"]
platforms = ["osx-arm64"]

[tool.pixi.pypi-dependencies]
myproject = { path = ".", editable = true }

[tool.pixi.tasks]

[tool.pixi.dependencies]
pymer4 = ">=0.9.1,<0.10"
ipykernel = ">=6.29.5,<7"
seaborn = ">=0.13.2,<0.14"

We can simply place this file and the associated pixi.lock under version control and our environment becomes fully reproducible with pixi install !

3. Using Google Collab#

If you are having trouble or don’t want to install pymer4 locally, you can use it in a Google Colab notebook by following the directions below. Or you can just copy the Example Notebook that we’ve setup.

Manually setting up conda on Collab#

In the first cell of your note book add the following code and run it. This will cause your notebook kernel to appear to “crash” and restart - this is expected

!pip install -q condacolab
import condacolab
condacolab.install()

Installing pymer4#

Once the kernel restarts, you’ll have the !mamba command available that you can use to install pymer4. You don’t need to rerun the previous cell. Just create and run a new cell below it with the following code:

!mamba install -q pymer4 -c ejolly -c conda-forge

Then you should be all set!

Using the development version of pymer4#

To support easy installation of the latest “bleeding-edge” version of pymer4 on the main branch of Github you can use the command below to install from the pre-release channel on anaconda.org. The main branch may often contain upcoming fixes and features slated for a new release.

conda install -c ejolly/label/pre-release -c conda-forge pymer4

Installation issues on intel macOS#

Some of the more cryptic error messages you might encounter on macOS are due to compiler issues that give rpy2 (a package dependency of pymer4) some issues during install. Here’s a fix that should work for that:

  1. Install homebrew if you don’t have it already by running the command at the link (it’s a great pacakage manager for macOS). To check if you already have it, do which brew in your Terminal. If nothing pops up you don’t have it.

  2. Fix brew permissions: sudo chown -R $(whoami) $(brew --prefix)/* (this is necessary on macOS Sierra or higher (>= macOS 10.12))

  3. Update homebrew brew update

  4. Install the xz utility brew install xz

  5. At this point you can try to re-install pymer4 and re-test the installation. If it still doesn’t work follow the next few steps below

  6. Install an updated compiler: brew install gcc, or if you have homebrew already, brew upgrade gcc

  7. Enable the new compiler for use:

    export CC="$(find `brew info gcc | grep usr | sed 's/(.*//' | awk '{printf $1"/bin"}'` -name 'x86*gcc-?')"
export CFLAGS="-W"

  8. If the above results in any error output (it should return nothing) you might need to manually find out where the new compiler is installed. To do so use brew info gcc and cd into the directory that begins with /usr in the output of that command. From there cd into bin and look for a file that begins with x86 and ends with gcc-7. It’s possible that the directory ends with gcc-8 or a higher number based on how recently you installed from homebrew. In that case, just use the latest version. Copy the full path to that file and run the following:

    export CC= pathYouCopiedInQuotes
export CFLAGS="-W"

  9. Finally install rpy2 using the new compiler you just installed: pip install rpy2 if you have R/RStudio or conda install -c conda-forge rpy2 if you don’t.

  10. Now you should be able to pip install pymer4 :)

Contents