Skip to content

Update setup instructions #149

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Mar 20, 2025
Merged

Update setup instructions #149

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
642f1c5
update setup instructions
tobyhodges Mar 14, 2025
2d7235f
updates for conda forge
chennesy Mar 16, 2025
0df20d8
fix windows and remove anaconda
chennesy Mar 18, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 1 addition & 7 deletions episodes/data-visualisation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -141,15 +141,9 @@ albany['circulation'].plot(kind='hist', bins=20,
## Use Plotly for interactive plots

Let’s switch back to the full DataFrame in `df_long` and use another
plotting package in Python called Plotly. First let’s install and then use the package.
plotting package in Python called Plotly.

```python
# uncomment below to install plotly if the import fails.
# !pip install plotly

# if you didn't install Jupyter via Anaconda, you may also need to install ipywidgets.
# !pip install ipywidgets

import plotly.express as px
```

Expand Down
31 changes: 15 additions & 16 deletions episodes/getting-started.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -51,7 +51,7 @@ Here a few areas where you might apply Python in your work.

## Use JupyterLab to edit and run Python code.

If you haven't already done so, see [the setup instructions](../learners/setup.md) for details on how to install JupyterLab and Python via Anaconda. The setup instructions also walk you through the steps you should follow to create an `lc-python` folder on your Desktop, and to download and unzip the dataset we'll be working with inside of that directory.
If you haven't already done so, see [the setup instructions](../learners/setup.md) for details on how to install JupyterLab and Python using Miniforge. The setup instructions also walk you through the steps you should follow to create an `lc-python` folder on your Desktop, and to download and unzip the dataset we'll be working with inside of that directory.

### Getting started with JupyterLab
To run Python, we are going to use Jupyter Notebooks via [JupyterLab][jupyterlab]. Jupyter notebooks are common tools for data science and visualization, and serve as a convenient environment for running Python code interactively where we can view and share the results of our Python code.
Expand All @@ -71,40 +71,40 @@ Jupyter notebooks let us execute and view the results of our Python code immedia
- Each notebook contains one or more cells that contain code, text, or images.

### Start JupyterLab
Once you have created the `lc-python` directory on your Desktop, you can start JupyterLab by opening a shell command line interface or by using Anaconda Navigator.
Once you have created the `lc-python` directory on your Desktop, you can start JupyterLab by opening a shell command line interface.

#### Mac users - Command Line

1. Press the <kbd>cmd</kbd> + <kbd>spacebar</kbd> keys and search for `Terminal`. Click the result or press <kbd>return</kbd>. (You can also find `Terminal` in your `Applications` folder, under `Utilities`.)
2. After you have launched Terminal, change directories to the `lc-python` folder you created earlier and type `jupyter lab`. Note that the `$` sign is used to indicate a command to be typed on the command prompt, but we never type the `$` sign itself, just what follows after it.
2. After you have launched Terminal, change directories to the `lc-python` folder you created earlier.
3. Next run `conda activate carpentries` to launch a Python environment which includes Jupyter Notebooks and other tools we will need to proceed through the lesson.
4. Finally, type `jupyter lab` which should open a browser window where you can run Jupyter Notebooks.

Note that the `$` sign is used to indicate a command to be typed on the command prompt, but we never type the `$` sign itself, just what follows after it.

```bash
$ cd ../Desktop/lc-python
$ conda activate carpentries
$ jupyter lab
```

#### Windows users - Command Line

To start the JupyterLab server you will need to access the Anaconda Prompt.

1. Press the <kbd>Windows Logo Key</kbd> and search for `Anaconda Prompt`, click the result or press enter.
1. Press the <kbd>Windows Logo Key</kbd> and search for `Miniforge Prompt`, click the result or press enter.
2. Once you have launched the Miniforge Prompt, change directories to the `lc-python` folder you created earlier. (The example below assumes a starting path of `C:\Users\username`)
3. Next run `conda activate carpentries` to launch a Python environment which includes Jupyter Notebooks and other tools we will need to proceed through the lesson.
4. Finally, type `jupyter lab` which should open a browser window where you can run Jupyter Notebooks.

2. Once you have launched the Anaconda Prompt, type the command `jupyter lab`. Note that the `$` sign is used to indicate a command to be typed on the command prompt, but we never type the `$` sign itself, just what follows after it.
Note that the `$` sign is used to indicate a command to be typed on the command prompt, but we never type the `$` sign itself, just what follows after it.

```bash
$ cd ..\Desktop\lc-python
$ cd \Desktop\lc-python
$ conda activate carpentries
$ jupyter lab
```

#### Start JupyterLab from Anaconda Navigator
If you are unfamiliar with the command line, you can launch JupyterLab by opening the Anaconda Navigator app and choosing the `Launch` button underneath the JuypterLab icon.

First [start Anaconda Navigator (click for detailed instructions on macOS, Windows, and Linux)](https://docs.anaconda.com/free/navigator/getting-started/#navigator-starting-navigator). You can search for Anaconda Navigator via Spotlight on macOS (<kbd>Command</kbd> + <kbd>spacebar</kbd>), or by using the Windows search function (<kbd>Windows Logo Key</kbd>).

After you have launched Anaconda Navigator, click the `Launch` button under JupyterLab. You may need to scroll down to find it. Here is a screenshot of an Anaconda Navigator page similar to the one that should open on either macOS or Windows.

![Launch JupyterLab from Anaconda Navigator](../episodes/fig/0_anaconda_navigator_landing_page.png){alt='screenshot of the launch button for JuypterLab in Anaconda Navigator'}

## The JupyterLab Interface

Launching JupyterLab opens a new tab or window in your preferred web browser. While JupyterLab enables you to run code from your browser, it does not require you to be online. If you take a look at the URL in your browser address bar, you should see that the environment is located at your localhost, meaning it is running from your computer: `http://localhost:8888/lab`.
Expand Down Expand Up @@ -191,7 +191,6 @@ You can also use "hotkeys"" to change Jupyter cells from Code to Markdown and ba
- Press the <kbd>y</kbd> key to convert the cell back to Code.
::::::::::::::::::::::::::::::::::::::::::::::::::

[anaconda]: https://docs.anaconda.com/anaconda/install/
[spyder]: https://www.spyder-ide.org/
[jupyterlab]: https://jupyterlab.readthedocs.io/en/stable/

Expand Down
4 changes: 2 additions & 2 deletions episodes/libraries.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -120,7 +120,7 @@ The ASCII letters are abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ

## Module not found error

Before you can import a Python library, you sometimes will need to download and install it on your machine. Anaconda comes with many of the most popular Python libraries for scientific computing applications built-in, so if you installed Anaconda for this workshop, you'll be able to import many common libraries directly. Some less common tools, like the PyMarc library, however, would need to be installed first.
Before you can import a Python library, you sometimes will need to download and install it on your machine. The Carpentries conda environment that we're using for the workshop installs a number of common Python libraries for academic computing. Since those are available when you activate the environment you'll be able to import many common libraries directly. Some less common tools, like the PyMarc library, however, would need to be installed first.

```python
import pymarc
Expand All @@ -130,7 +130,7 @@ import pymarc
ModuleNotFoundError: No module named 'pymarc'
```

You can find out how to install the library by looking at the documentation. [PyMarc](https://pypi.org/project/pymarc/), for example, recommends using a command line tool, `pip`, to install it. You can install with pip in a Jupyter notebook by starting the command with a percentage symbol, which allows you to run shell commands from Jupyter:
You can find out how to install the library by looking at the documentation. [PyMarc](https://pypi.org/project/pymarc/), for example, recommends using a command line tool, `pip`, for installation, though you can also [install PyMarc using conda](https://anaconda.org/asmeurer/pymarc). To install with pip in a Jupyter notebook you can begin the command with a percentage symbol, which allows you to run shell commands from Jupyter:

```python
%pip install pymarc
Expand Down
2 changes: 1 addition & 1 deletion index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ This lesson is an introduction to programming in Python for library and informat

2. Learners must install Python and JupyterLab, and download the dataset that will be used in the lesson, before the workshop begins.

Please see <a href="#installing-python-using-anaconda">setup instructions below</a> for details.
Please see <a href="#installing-python-using-miniforge">setup instructions below</a> for details.


::::::::::::::::::::::::::::::::::::::::::::::::::
Expand Down
46 changes: 9 additions & 37 deletions learners/setup.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,46 +2,19 @@
title: Setup
---

## Installing Python Using Anaconda
Python is a popular language for research computing, and great for general-purpose programming as well. Installing all of its research packages individually can be a bit difficult, so we recommend Anaconda, an all-in-one installer.
## Installing Python Using Miniforge

Regardless of how you choose to install it, please make sure you install Python 3.6 or above. The latest 3.x version recommended on [Python.org][python] is fine.
[Python](https://python.org) is a popular language for scientific computing, and great for general-purpose programming as well.
For this workshop we use Python version 3.x.
Installing all of its scientific packages individually can be a bit difficult, so we provide an environment file to help you take care of them all together.
We will use the _Miniforge_ distribution of Python.

We will teach Python using JupyterLab, a programming environment that runs in a web browser (JupyterLab will be installed by Anaconda). For this to work you will need a reasonably up-to-date browser. The current versions of the Chrome, Safari and Firefox browsers are all supported (some older browsers, including Internet Explorer version 9 and below, are not).

::::::::::::::::: tab

### Windows

[Watch a video tutorial for Windows][video-windows].

1. Open [anaconda.com/download][anaconda-dl] with your web browser.
2. Download the Anaconda for Windows installer with Python 3. (If you are not sure which version to choose, you probably want the 64-bit Graphical Installer *Anaconda3-...-Windows-x86_64.exe*)
3. Install Python 3 by running the Anaconda Installer, using all of the defaults for installation except make sure to check *Add Anaconda to my PATH environment variable*.

### Mac

[Watch a video tutorial for Mac][video-mac].

1. Open [anaconda.com/download][anaconda-dl] with your web browser.
2. Download the Anaconda Installer with Python 3 for macOS (you can either use the Graphical or the Command Line Installer).
3. Install Python 3 by running the Anaconda Installer using all of the defaults for installation.

### Linux

Note that the following installation steps require you to work from the shell. If you aren't comfortable doing the installation yourself stop here and request help from the workshop organizers.

1. Open [anaconda.com/download][anaconda-dl] with your web browser.
2. Download the Anaconda Installer with Python 3 for Linux.
3. Open a terminal window and navigate to the directory where the executable is downloaded (e.g., `cd ~/Downloads`).
4. Type `bash Anaconda3` and press <kbd>Tab</kbd> to auto-complete the full file name. The name of file you just downloaded should appear.
5. Press <kbd>Enter</kbd> (or <kbd>Return</kbd> depending on your keyboard). You will follow the text-only prompts. To move through the text, press <kbd>Spacebar</kbd>. Type `yes` and press <kbd>Enter</kbd> to approve the license. Press <kbd>Enter</kbd> (or <kbd>Return</kbd>) to approve the default location for the files. Type `yes` and press <kbd>Enter</kbd> (or <kbd>Return</kbd>) to prepend Anaconda to your PATH (this makes the Anaconda distribution the default Python).
6. Close the terminal window.

:::::::::::::::::::::::::
Please refer to the [Python section of the workshop website for installation instructions](https://carpentries.github.io/workshop-template/install_instructions/#python).

## JupyterLab
We will teach Python using JupyterLab, a part of a family of [Jupyter][jupyter] tools that includes Jupyter Notebook and JupyterLab, both of which provide interactive web environments where you can write and run Python code. If you installed Anaconda, JupyterLab is installed on your system. If you did not install Anaconda, you can [install JupyterLab][jupyter-install] on its own using conda, pip, or other popular package managers.
We will teach Python using JupyterLab, a part of a family of [Jupyter][jupyter] tools that includes Jupyter Notebook and JupyterLab, both of which provide interactive web environments where you can write and run Python code.
If you followed the instructions linked above, JupyterLab is installed on your system.
Alternatively, you can [install JupyterLab][jupyter-install] on its own using conda, pip, or other popular package managers.

## Download the data

Expand All @@ -53,7 +26,6 @@ This lesson uses circulation data in multiple CSV files from the Chicago Public

[python]: https://python.org/downloads
[video-windows]: https://www.youtube.com/watch?v=xxQ0mzZ8UvA
[anaconda-dl]: https://www.anaconda.com/download/
[video-mac]: https://www.youtube.com/watch?v=TcSAln46u9U
[jupyter]: https://docs.jupyter.org/en/latest/
[jupyter-install]: https://jupyterlab.readthedocs.io/en/stable/getting_started/installation.html
Expand Down