Add more details to setup instructions?

[uschille]

The current setup instructions do not include details on additional Python packages that are needed (e.g., skimage is not automatically included in the bare Python 3 environment on some Linux distributions). We might want to give some more instructions (or links to other Carpentries lessons where these might already be included) and perhaps provide a requirements.txt. This will probably depend on what decisions are made for #130, #134, and #140.

[tobyhodges]

The current setup instructions do not include details on additional Python packages that are needed (e.g., skimage is not automatically included in the bare Python 3 environment on some Linux distributions).

True that skimage is not included with Python 3 by default, but the setup instructions do specify that learners should install the Anaconda distribution of Python, which includes many additional packages including skimage, numpy, matplotlib, etc.

That said, if you want to add a list of the packages used in the lesson, for anyone who knows how to install packages for the version of Python they are already using and who would prefer to avoid downloading and installing a whole new distribution, I think that is a reasonable thing to put into the Setup page. Perhaps as a collapsible box, like those used for the Windows setup instructions on our Lesson Example?

[bobturneruk]

I think we probably should finalise the requirements and then consider the best approach.

I tried and failed to find a list of what comes with Anaconda. My understanding was that this varied by platform a bit. e.g. on Windows 10 (below). You'd still have to pip or conda install scikit-image (for example)? I think we'd need to explain or automate this? Depends on assumed prerequisite knowledge, I guess.

(sssurvey) PS C:\Users\bobturner\Documents\sssurvey> conda create -y --force -n dci python=3.7
Collecting package metadata (current_repodata.json): done
Solving environment: done

## Package Plan ##

  environment location: C:\Users\bobturner\.conda\envs\dci

  added / updated specs:
    - python=3.7


The following NEW packages will be INSTALLED:

  ca-certificates    conda-forge/win-64::ca-certificates-2021.5.30-h5b45459_0
  certifi            conda-forge/win-64::certifi-2021.5.30-py37h03978a9_0
  openssl            conda-forge/win-64::openssl-1.1.1k-h8ffe710_0
  pip                conda-forge/noarch::pip-21.2.3-pyhd8ed1ab_0
  python             conda-forge/win-64::python-3.7.10-h7840368_100_cpython
  python_abi         conda-forge/win-64::python_abi-3.7-2_cp37m
  setuptools         conda-forge/win-64::setuptools-49.6.0-py37h03978a9_3
  sqlite             conda-forge/win-64::sqlite-3.36.0-h8ffe710_0
  ucrt               conda-forge/win-64::ucrt-10.0.20348.0-h57928b3_0
  vc                 conda-forge/win-64::vc-14.2-hb210afc_5
  vs2015_runtime     conda-forge/win-64::vs2015_runtime-14.29.30037-h902a5da_5
  wheel              conda-forge/noarch::wheel-0.36.2-pyhd3deb0d_0
  wincertstore       conda-forge/win-64::wincertstore-0.2-py37h03978a9_1006


Preparing transaction: done
Verifying transaction: done
Executing transaction: done
#
# To activate this environment, use
#
#     $ conda activate dci
#
# To deactivate an active environment, use
#
#     $ conda deactivate

(sssurvey) PS C:\Users\bobturner\Documents\sssurvey> conda activate dci
(dci) PS C:\Users\bobturner\Documents\sssurvey> conda list
# packages in environment at C:\Users\bobturner\.conda\envs\dci:
#
# Name                    Version                   Build  Channel
ca-certificates           2021.5.30            h5b45459_0    conda-forge
certifi                   2021.5.30        py37h03978a9_0    conda-forge
openssl                   1.1.1k               h8ffe710_0    conda-forge
pip                       21.2.3             pyhd8ed1ab_0    conda-forge
python                    3.7.10          h7840368_100_cpython    conda-forge
python_abi                3.7                     2_cp37m    conda-forge
setuptools                49.6.0           py37h03978a9_3    conda-forge
sqlite                    3.36.0               h8ffe710_0    conda-forge
ucrt                      10.0.20348.0         h57928b3_0    conda-forge
vc                        14.2                 hb210afc_5    conda-forge
vs2015_runtime            14.29.30037          h902a5da_5    conda-forge
wheel                     0.36.2             pyhd3deb0d_0    conda-forge
wincertstore              0.2             py37h03978a9_1006    conda-forge

[uschille]

The current setup instructions do not include details on additional Python packages that are needed (e.g., skimage is not automatically included in the bare Python 3 environment on some Linux distributions).

True that skimage is not included with Python 3 by default, but the setup instructions do specify that learners should install the Anaconda distribution of Python, which includes many additional packages including skimage, numpy, matplotlib, etc.

You are right, I missed the difference between Miniconda and Anaconda there for a moment.

That said, if you want to add a list of the packages used in the lesson, for anyone who knows how to install packages for the version of Python they are already using and who would prefer to avoid downloading and installing a whole new distribution, I think that is a reasonable thing to put into the Setup page. Perhaps as a collapsible box, like those used for the Windows setup instructions on our Lesson Example?

Yes, I think it would be valuable to provide some steps on conda create etc. for learners that might want to use computing infrastructure at their home institution. This would enable them to transition more seemlessly from the workshop to applying the skills in their work. I'm also thinking that if workshops are held locally, facilitators might not want every user to install their own distribution. But perhaps I'm introducing mission creep here?

I agree with @bobturneruk that we should finalize the requirements first and then revisit the setup instructions.

[tobyhodges]

Yes, I think it would be valuable to provide some steps on conda create etc. for learners that might want to use computing infrastructure at their home institution. This would enable them to transition more seemlessly from the workshop to applying the skills in their work. I'm also thinking that if workshops are held locally, facilitators might not want every user to install their own distribution. But perhaps I'm introducing mission creep here?

For a lesson aimed at novice programmers, the "just install Anaconda" approach is perfect - it provides pretty much everything they need with minimal cognitive load - but, because this lesson is aimed at people who already have some familiarity with Python, I believe there could be room for discussion of environments and dependencies in this Image Processing lesson.

As you both suggested, let's come back to this once we know for sure what the requirements for the lesson will be.

[bobturneruk]

Regardless of more exotic dependencies, not sure you'd get scikit-image (for example), which we almost certainly need, if you "just install Anaconda". I'll could check with a clean install, but conda create ... definitely didn't give me scikit-image by default. Maybe base has some other stuff.

[tobyhodges]

@bobturneruk check out the package listings linked from this page: https://docs.anaconda.com/anaconda/packages/pkg-docs/

Those are the packages available/installed by default with the full Anaconda distribution. It tells you what will be available if you launch Python in the default environment after you have installed Anaconda. That's different from what is installed when you use conda to create a new environment: in that case, only the packages you specify (e.g. with an environment.yml file) when you when you run conda create will be available.

scikit-image is included in the installer for all of the Python version/operating system combinations I checked.

[bobturneruk]

Great, thanks! Hadn't realised that.