Create setup instructions

[K-Meech]

Definition of Done

Finish creating setup instructions in learners/setup.md

This should include:

• How to download any example data
• How to install any required software e.g. anaconda/napari
• Test the instructions on Windows, Mac, Linux

Example from another carpentries course: https://github.com/swcarpentry/shell-novice/blob/main/learners/setup.md

[davecash75]

@K-Meech
Here is another example: https://github.com/UCL/2023-03-09-UCL-DasH/tree/gh-pages/setup where we have some Bash/Z shell scripts for Linux/Mac and powershell for windows.

[K-Meech]

Thanks for the links @davecash75 - I've documented some of the different installation options below for reference:

For all below, first step is to install anaconda. Conda solves with napari are very slow (at least as tested on my Windows laptop), hence all of these include a call to update conda to the latest version. The latest conda release has libmamba as the default solver which is much faster. Hopefully soon there will be an anaconda release that includes this conda version by default!

Option 1 (via terminal/anaconda prompt):

conda update -n base conda
conda create -y -n napari-env -c conda-forge python=3.9
conda activate napari-env
pip install "napari[all]"
conda install napari-aicsimageio -c conda-forge

napari # Opens the napari viewer

Option 2 (via anaconda navigator GUI)

Note that you can't pip install via anaconda navigator, everything is using conda install underneath

# Go to the Environments tab
# Click on 'Channels', then 'Add…', type 'conda-forge' and press enter, then 'Update channels'
# Switch to 'Updateable', click the blue arrow next to conda, then 'Apply'
# Click the + to create a new environment, call it 'napari-env', select python 3.9 and then 'Create'
# Switch to 'Not installed', click napari, pyqt and napari-aicsimageio, then 'Apply' 
# Click the green arrow on the 'napari-env' tab, and select 'Open terminal'

napari

This works but does currently print a warning:

UserWarning: A NumPy version >=1.17.3 and <1.25.0 is required for this version of SciPy (detected version 1.26.0
  warnings.warn(f"A NumPy version >={np_minversion} and <{np_maxversion}"

Option 3 (via bash scripts + terminal)

This would use bash scripts similar to here that do most of the steps in Option 1

# Download scripts and environment/requirements files
# Open terminal + run bash scripts that do most of the steps in Option 1

conda activate napari-env
napari

[K-Meech]

Just to note that option 2 also seems to cause errors in the napari-aicsimageio plugin - for example, .svs images won't open using option 2, but will open with option 1

[MonikaSvata]

On hold until we confirm which Napari versions are being used and content of lessons finalised.

[davecash75]

Option 1/3 will cause some headaches for those who already have installed anaconda and conda. I had to try a few different things to get my conda up to 23.10.0 (was on 23.1.0), but the benefits as @K-Meech are huge. It sat there for ages not having any luck solving the environment and when I moved to the powered by Mamba approach it was sorted within a minute. But how to regulate all of that within a script or give guidance will be difficult.

[dpshelio]

@dpshelio to check how to update earlier versions of conda.

[davecash75]

As discussed on today's meeting, we may want the script to check the conda version and if it is before 23.10.0, we will need to install mamba and then either (a) use mamba to install napari-aicsimageio or (b) make libmamba the solver on the conda install command.

[dpshelio]

Tried on miniconda 23.11.0 (from 2023-11-24) on Windows with Python=3.11 (default). pip install "napari[all]" takes quite a while as it needs to install all the dependencies (numpy and others). Installing everything took ~15min. However, it failed to open an image with OpenGL errors.

RuntimeError: Using glBindFramebuffer with no OpenGL context.

On Linux, without the latest miniconda update and trying to avoid the "update conda" one, I've tried to install libmamba as per their instructions. It took well beyond my patience. Therefore I used mamba to install it instead. Then the rest works fine.

I'd like to suggest, to use only conda and no pip. Following the step above I noticed that installing it via pip and then conda, it downloads and installs many packages twice. So, step 1 would become:

conda update -n base conda
conda create -y -n napari-env -c conda-forge python=3.9 napari  napari-aicsimageio

napari # Opens the napari viewer

This is also the recommended by Napari for arm64 macOSs.

Otherwise, we may need them to set the interoperability between conda and pip.

[K-Meech]

Thanks for checking @dpshelio - happy to only use conda and no pip. At least on windows, it does mean you have to install pyqt too (it says this in the napari installation instructions under option 2 also) so:

conda update -n base conda
conda create -y -n napari-env -c conda-forge python=3.9 napari pyqt napari-aicsimageio

napari # Opens the napari viewer

[K-Meech]

Just to add to this - it now appears that some of the file format readers that napari-aicsimageio uses (e.g. aicspylibczi) aren't available via conda. Therefore, to support the widest range of file formats, we'd have to install via pip instead. The bioformats jar is only available on conda though, so we will have to mix pip and conda to get the full functionality.

Also, if we install any plugins via the user interface of napari (Plugins > Install/Uninstall Plugins...), this always uses pip. So it probably makes sense to use pip for as much as possible and only install the bioformats_jar from conda.

e.g.

conda update -n base conda
conda create -y -n napari-env conda-forge python=3.9 bioformats_jar
pip install "napari[all]" napari-aicsimageio

[dpshelio]

Then I'd suggest to run before that

conda config --set pip_interop_enabled True

as suggeested on conda documentation about interoperability with pip

[MonikaSvata]

Rather than creating script for installation, add simple list of tests to run after the set up instructions - to check if all installation/set-up is done correctly and works (e.g. open Napari etc.) - Kimberley to include.

Open a new branch for set up instruction and data.

[K-Meech]

@thompson318 - could you open a new branch + draft PR for this? This info needs to be added to the learners/setup.md file, along with instructions to download the following images:

• '00001_01.ome.tiff' on this page of the OME website
• 'Plate1-Blue-A-12-Scene-3-P3-F2-03.czi' from the OME sample data

[thompson318]

Other data to download mitocheck.ome.tiff from episode on filetypes and metatdata.

[thompson318]

Other data to download mitocheck.ome.tiff from episode on filetypes and metatdata. OK, I think this is 00001_01.ome.tiff, fixed in PR #33

[thompson318]

pip install "napari[all]" napari-aicsimageio

I've failed after the conda installation step. Running conda create -y -n napari-env conda-forge python=3.9 bioformats_jar gives me:

PackagesNotFoundError: The following packages are not available from current channels:

• bioformats_jar
• conda-forge

I'm not very familiar with conda yet, so will investigate.

[K-Meech]

@thompson318 I think there's a missing -c there, does it work with this?

conda create -y -n napari-env -c conda-forge python=3.9 bioformats_jar

[thompson318]

Thanks @K-Meech , that sorted it.

[MonikaSvata]

Merged in - can be closed.