From 848497a392054c474cd40300d43711a3dc534638 Mon Sep 17 00:00:00 2001 From: Radovan Bast Date: Wed, 11 Dec 2024 21:58:52 +0100 Subject: [PATCH] simpler install instructions; closes #39 --- content/installation.md | 297 ++++++++++++++++++---------------------- 1 file changed, 130 insertions(+), 167 deletions(-) diff --git a/content/installation.md b/content/installation.md index de51708..2048b22 100644 --- a/content/installation.md +++ b/content/installation.md @@ -3,34 +3,50 @@ [this page is adapted from ] -## 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. @@ -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