Lesson Contribution: how to install numpy

[Talishask]

I'm a member of The Carpentries staff and I'm submitting this issue on behalf of another member of the community. In most cases I won't be able to follow up or provide more details other that what I'm providing below.

---

As part of the checkout process, I am reading through the python class , in session 2 before introducing numpy module, I will suggest add some instruction to user that how to install numpy if they don't have it on their system . During the whole class , I don't see anywhere to teach user how to install additional modules they might need in coding. so this is a good example to show them.

pip install numpy

[maxim-belkin]

Thank you, Talisha and the contributor!

I think this is a nice issue to discuss as part of the instructor checkout procedure so I'll add corresponding labels. I'd like our community members to weigh in on the pros and cons of implementing proposed changes (adding instructions on how to install Python packages).

Maxim

[ldko]

I think it would be worth putting in a callout after the first import numpy to briefly let learners know how to install the package if they don't have it installed. This could generally be skipped over when being taught in a workshop where learners were instructed to use Anaconda but could be of use if someone missed this or is using the materials on their own and did not follow the setup instructions.

[xintin]

In my opinion, in other chapters, too, if we are introducing a new library/package, it is good to share how to install them using pip/pip3 or conda.

[maxim-belkin]

Thanks, @xintin, for joining the discussion. The points that you raised were, in fact, ... my concerns:

• if we provide such a callout box for numpy, we ought to provide a similar one for matplotlib (other modules that we use are part of a standard Python installation)
• our lesson uses Anaconda, so it makes sense to provide instructions for conda in addition to or instead of those for pip.

Why do these concern me?

1. In order for the workshop to run smoothly, all learners are expected to install Anaconda before the lesson begins. If they do, they won't need this callout box. If they don't... we can't really take into account all possible scenarios when learners don't follow one or another part of the lesson.
2. Both pip and conda are command-line tools and require basic knowledge of shell / terminal. It is not uncommon for people taking our lesson to be uncomfortable with CLI tools, especially on Windows systems where I anticipate to have more problems with these instructions.
3. If we decide to provide instructions for pip and conda (and I think that would be the right thing to do), we have to make it clear that they might interact with each other in a weird way: https://www.anaconda.com/blog/using-pip-in-a-conda-environment.
4. Teaching how to install Python modules is not, currently the goal of the lesson (our goal is to teach basic programming principles -- variables, data types, conditionals, loops, functions). I agree with you that it's super useful and we might have to devote an episode to this, but we have to have a longer conversation about the contents of the lesson.
5. Context switching (in two places). While it might seem like not a big deal to you/us, it has a potential to confuse learners: they might try to run pip from the Python terminal, or forget to switch back to the Jupyter Notebook from the terminal, or decide that pip is a Python function.

As a possible solution, we can add pip and conda instructions to our Setup page and add a callout box saying that if Python shows a long error message that says something about ImportError when you do import numpy, then go to the Setup page and make sure to install appropriate packages. I think ideally that note/callout would be collapsible (.solution rather than .callout) but that's not so important.

[RoelBrouwer]

I hope weighing in on this discussion is still useful, as it has been a while since the last contribution to the discussion. But here are my two cents:

I mostly agree with the points that @maxim-belkin raises. I broadly see three options on how to implement this suggestion:

1. Create a separate episode dedicated to the environment / library management;
2. Provide a callout box or something similar consistently each time a library is introduced that explains how to install it if it is not available on the user's system;
3. Include it in the instructions on the setup page.

I think we can discard option 1 on the account that it is not the core goal of this lesson to teach this, and dedidicating an entire episode to it then is a bit overkill.
Personally, I would favor the latter option (no. 3), like @maxim-belkin already suggested. As there is already a separate paragraph there for each type of setup, you can separate out the instructions:

• Option A would not need these additional instructions. This makes sure to not unnecessarily complicate things for anyone who will not need to know about this to follow the lesson;
  Possibly, a subsection could be added here briefly explaining conda environments, but maybe this would fit better under option B - as I would expect the people choosing option B are already more familiar with command-line stuff.
• Option B would not necessarily need any instructions either, but it could be nice to provide them here.
• Option C would require these instructions. Probably provide a section on pip and conda separately? Maybe even just pip, with a reference to the explanation of conda above, as it might just be that people choosing this option do not want to install a whole lot more than absolutely necessary (and therefore do not have Anaconda / miniconda).

[ivastar]

I'd like to offer a solution to Option C offered by @RoelBrouwer. These are the instructions that I give participants when I teach this lesson, modified to generalize from astronomy (here is my fork: https://ivastar.github.io/python-novice-astro/setup/):

Install Python:

You will need terminal access for this process. Contact the workshop instructor if you have no experience working in a terminal.

Test if you already have Anaconda or Miniconda installed. In your terminal type the following commands:

$ bash
$ which conda

{: .source}

If this returns nothing, please proceed to the next step. If it produces a path such as /Users/yourname/anaconda/bin/conda (yours may be different), skip the next step and go straight to step 2.

1. Install Miniconda Python 3 by following the directions here. A video tutorial is available here. You do not need root access. We recommend Miniconda rather than Anaconda because it is a faster and more light-weight installation. Verify your installation as suggested on the conda page before moving on.

2. Create an conda environment by running the following commands:

$ conda create --name your_env_name python numpy matplotlib
$ conda activate your_env_name

{: .source}

Replace your_env_name with something useful, say carpentries. This should be enough to get you through the workshop but just in case, this is how you would install a new packages:

$ conda activate your_env_name
$ conda install new_package

{.source}

3. Clean up your workspace. Check your default profile files (.cshrc, .bashrc, .bash_profile) and comment any entries that define or add to $PYTHONPATH. Start a fresh Terminal window and type echo $PYTHONPATH - you should not see a long jumble of paths to unknown corners of your hard drive. If you don't know what this means, skip to the next one.

4. Get yourself a nicer terminal. iTerm is really nice for OSX. For Windows, here is Git Bash.

5. For this class we can use Nano, Emacs or VIM, but if you want a nicer text editor, download Sublime Text, Atom, BBEdit or TextWrangler. We will not cover IDEs such as PyCharm or Spyder.