Skip to content

Commit

Permalink
simpler install instructions; closes #39
Browse files Browse the repository at this point in the history
  • Loading branch information
@bast
bast committed Dec 11, 2024
1 parent 0fcbaeb commit 848497a
Showing 1 changed file with 130 additions and 167 deletions.
297 changes: 130 additions & 167 deletions content/installation.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,34 +3,50 @@
[this page is adapted from <https://aaltoscicomp.github.io/python-for-scicomp/installation/>]


## Packages that we will need

In this course we will need **Python 3** and the following Python libraries/packages:
- **jupyterlab**
- **altair**
- pandas (comes with altair)
- vega_datasets (optional)
- numpy (optional)


## How to install Python

We expect you to have a working Python installation with some common libraries.
**We currently recommend Miniforge, which includes the base and packages
through a different, freely usable channel.** You can explore the options in
the tabs below.
## Choosing an installation method

For this course we will install an isolated environment
with following dependencies:
```yaml
name: data-viz
channels:
- conda-forge
dependencies:
- python <= 3.12
- jupyterlab
- altair-all
- vega_datasets
- pandas
- numpy
```
**If you are used to installing Python packages**, you can use your preferred
installation method. However, we recommend to not install the above packages
system-wide and never to install using administrator privileges.
Below we offer several options to install Python and the required packages
from the [environment.yml file](https://github.com/coderefinery/data-visualization-python/blob/main/software/environment.yml).
If you are used to installing packages in Python and know what to do with the
above `environment.yml` file, please follow your own preferred installation
method.

**If you are new to Python or unsure** how to create isolated environments in
Python from files like the `environment.yml` above, please follow the
instructions below.

:::{discussion} There are many choices and we try to suggest a good compromise
There are very many ways to install Python and packages with pros and cons and
in addition there are several operating systems with their own quirks. This
can be a huge challenge for beginners to navigate. It can also difficult for
instructors to give recommendations for something which will work everywhere
and which everybody will like.

Below we will recommend **Miniforge** since it is free, open source, general,
available on all operating systems, and provides a good basis for reproducible
environments. However, it does not provide a graphical user interface during
installation. This means that every time we want to start a JupyterLab session,
we will have to go through the command line.
:::

:::{admonition} Python, conda, anaconda, miniforge, etc?
:class: dropdown

Unfortunately there's a lot of jargon. We'll go over this in the
course but here is a crash course:
Unfortunately there are many options and a lot of jargon.
Here is a crash course:

* **Python** is a programming language very commonly used in
science, it's the topic of this course.
Expand All @@ -55,165 +71,112 @@ course but here is a crash course:
the Anaconda channels.
:::

::::{tabs}
:::{group-tab} Miniforge
This is our recommended method - it can be used for any purpose
and makes a strong base for the future.

Follow the [instructions on the miniforge web page](https://github.com/conda-forge/miniforge). This installs
the base, and from here other packages can be installed.
## Installing Python via Miniforge

Miniforge uses the command line - this gives you the most power
but can feel unfamiliar.
:::
Follow the [instructions on the miniforge web page](https://github.com/conda-forge/miniforge). This installs
the base, and from here other packages can be installed.


## Installing and activating the software environment

:::{group-tab} Anaconda
Anaconda is easier to get started with, but may be more limiting
in the future. The Anaconda Navigator provides a graphical
interface to most of what you would need.
First we will start Python in a way that activates conda/mamba. Then we will
install the software environment from [this environment.yml
file](https://raw.githubusercontent.com/coderefinery/data-visualization-python/main/software/environment.yml).

The [Anaconda Python distribution](https://docs.continuum.io/anaconda/install/) conveniently packages
most popular libraries, but its license has does not allow large organizations to
use it for free (and has actually been enforced against
universities).
An **environment** is a self-contained set of extra libraries - different
projects can use different environments to not interfere with each other. This
environment will have all of the software needed for this particular course.

Note the license of Anaconda - there were recently issues with
it being used by large universities for free, and this is not
yet fully resolved.
We will call the environment `data-viz`.

::::{tabs}
:::{group-tab} Windows
Use the "Miniforge Prompt" to start Miniforge. This
will set up everything so that ``conda`` and ``mamba`` are
available.
Then type
(without the `$`):
```console
$ mamba env create -n data-viz -f https://raw.githubusercontent.com/coderefinery/data-visualization-python/main/software/environment.yml
```
:::

:::{group-tab} Linux / MacOS
Each time you start a new command line terminal,
you can activate Miniforge by running
(without the `$`):
```console
$ source ~/miniforge3/bin/activate
```

This is needed so that
Miniforge is usable wherever you need, but doesn't affect any
other software on your computer (this is not needed if you
choose "Do you wish to update your shell profile to
automatically initialize conda?", but then it will always be
active).

In the second step, we will install the software environment:
```console
$ mamba env create -n data-viz -f https://raw.githubusercontent.com/coderefinery/data-visualization-python/main/software/environment.yml
```
:::
::::


## Starting Python

You need to start Python in a way that activates conda/mamba.

::::::{tabs}
:::::{group-tab} Miniforge
::::{tabs}
:::{group-tab} Windows
Windows: Use the "Miniforge Prompt" to start Miniforge. This
will set up everything so that ``conda`` and ``mamba`` are
available.
:::
:::{group-tab} Linux / MacOS
Each time you start a new command line terminal,
you can activate Miniforge by running:
```
$ source ~/miniforge3/bin/activate
```

This is needed so that
Miniforge is usable wherever you need, but doesn't affect any
other software on your computer (this is not needed if you
choose "Do you wish to update your shell profile to
automatically initialize conda?", but then it will always be
active).
:::
::::
:::::

:::::{group-tab} Anaconda
The [Anaconda Navigator](https://docs.anaconda.com/navigator/) provides a convenient
way to access the software. It can be installed from that page.
:::::
::::::
## Starting JupyterLab

Every time we want to start a JupyterLab session,
we will have to go through the command line and first
activate the `data-viz` environment.

## Installing and activating the software environment
::::{tabs}
:::{group-tab} Windows
Start the Miniforge Prompt. Then type
(without the `$`):
```console
$ conda activate data-viz
$ jupyter-lab
```
:::

Once Python and conda/mamba are installed, you can use it to install
an environment. An **environment** is a self-contained set of extra
libraries - different projects can use different environments to not
interfere with each other. This environment will have all of the
software needed for this particular course.

::::::{tabs}
:::::{group-tab} Miniforge
This [environment.yml file](https://raw.githubusercontent.com/coderefinery/data-visualization-python/main/software/environment.yml)
contains all packages needed for the course, and can be
installed with. The following command will install an
environment named `data-viz`:
::::{tabs}
:::{group-tab} Windows
```
$ mamba env create -n data-viz -f https://raw.githubusercontent.com/coderefinery/data-visualization-python/main/software/environment.yml
```
:::
:::{group-tab} Linux / MacOS
```
$ mamba env create -n data-viz -f https://raw.githubusercontent.com/coderefinery/data-visualization-python/main/software/environment.yml
```
:::
::::{tabs}

Each time you start a new command line, you need to activate
miniforge and this environment:
::::{tabs}
:::{group-tab} Windows
Start the Miniforge Prompt. Then run:
```
$ conda activate data-viz
$ jupyter-lab
```
:::
:::{group-tab} Linux / MacOS
```
$ source ~/miniforge3/bin/activate
$ conda activate data-viz
```
:::
::::
:::::

:::::{group-tab} Anaconda
Use the navigator to create a new environment from [this environment.yml
file](https://raw.githubusercontent.com/coderefinery/data-visualization-python/main/software/environment.yml).
You'll have to download it and then [import
it](https://docs.anaconda.com/navigator/tutorials/manage-environments/#importing-an-environment).

When running this course's exercise, make sure the `data-viz` environment is
activated before starting JupyterLab or any code. You need to start
terminals or JupyterLab from the Anaconda Navigator for the `data-viz`
environment to be used.
:::::
::::::
:::{group-tab} Linux / MacOS
Start the terminal and in the terminal, type
(without the `$`):
```console
$ source ~/miniforge3/bin/activate
$ conda activate data-viz
$ jupyter-lab
```
:::
::::


## Starting JupyterLab
## Removing the software environment

::::{tabs}
:::{group-tab} Windows
In the Miniforge Prompt, type
(without the `$`):
```console
$ conda env list
$ conda env remove --name data-viz
$ conda env list
```
:::

We do most of the lessons from JupyterLab (and JupyterLab provides
most of the other tools we need).

::::::{tabs}
:::::{group-tab} Miniforge
::::{tabs}
:::{group-tab} Windows
Start the Miniforge Prompt. Then run:
```
$ conda activate data-viz
$ jupyter-lab
```
:::
:::{group-tab} Linux / MacOS
```
$ source ~/miniforge3/bin/activate
$ conda activate data-viz
$ jupyter-lab
```
:::
::::
:::::

:::::{group-tab} Anaconda
If you install the full Anaconda distribution, this will be
available and can be started either through Anaconda Navigator
or command line.

Make sure the `data-viz` environment is selected and
you can start JupyterLab.
:::::
::::::
:::{group-tab} Linux / MacOS
In the terminal, type
(without the `$`):
```console
$ source ~/miniforge3/bin/activate
$ conda env list
$ conda env remove --name data-viz
$ conda env list
```
:::
::::


## How to verify your installation
Expand Down

0 comments on commit 848497a

Please sign in to comment.