Skip to content

Commit

Permalink
Update set-up page and slides (#66)
Browse files Browse the repository at this point in the history
  • Loading branch information
@jorisvandenbossche
jorisvandenbossche authored Dec 6, 2024
1 parent 36fc40f commit 6b46e36
Show file tree
Hide file tree
Showing 2 changed files with 92 additions and 103 deletions.
189 changes: 89 additions & 100 deletions docs/setup.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,57 +6,84 @@ layout: default

To get started, you should have the following three elements setup:

1. Install Python and the required Python packages
2. Download the course material to your computer
1. Download the course material to your computer
2. Install Python and the required Python packages using `conda`
3. Test your configuration and installation
4. Start Jupyter lab

In the following sections, more details are provided for each of these steps. When all three are done, you are ready to start coding!

## 1. (_before the course_) Install Python and the required Python packages
## 1. Getting the course materials

For scientific and data analysis, we recommend to use Anaconda (or Miniconda) (<https://www.anaconda.com/download/>), which provides a Python
distribution that includes the scientific libraries (this recommendation applies to all platforms, so for both Windows, Linux and Mac),
instead of installing Python as such. After installation, proceed with the setup.
### Option 1: You are already a git user

### Install Anaconda
As the course has been set up as a [git](https://git-scm.com/) repository managed on [Github](https://github.com/jorisvandenbossche/DS-python-geospatial),
you can clone the entire course to your local machine. Use the command line to clone the repository and go into the course folder:

#### Option 1: I do not have Anaconda installed
```
git clone https://github.com/jorisvandenbossche/DS-python-geospatial.git
cd DS-python-geospatial
```

For first time users and people not fully confident with using the command line, we advise to install Anaconda, by downloading and installing
the Python 3.x version from <https://www.anaconda.com/download/>. Recent computers will require the 64-Bit installer.
In case you would prefer using Github Desktop,
see [this tutorial](https://help.github.com/desktop/guides/contributing-to-projects/cloning-a-repository-from-github-to-github-desktop/).

For more detailed instructions to install Anaconda, check the [Windows](https://docs.anaconda.com/anaconda/install/windows/),
[Mac](https://docs.anaconda.com/anaconda/install/mac-os/) or [linux](https://docs.anaconda.com/anaconda/install/linux/) installation tutorial.
### Option 2: You are not a git user

**Note:** When you are already familiar with the command line and Python environments you could opt to use Miniconda instead of Anaconda
and download it from <https://conda.io/miniconda.html>. The main difference is that Anaconda provides a graphical user interface (Anaconda navigator)
and a whole lot of scientific packages (e.g <https://docs.anaconda.com/anaconda/packages/py3.9_win-64/>) when installing, whereas for Miniconda
the user needs to install all packages using the command line. On the other hand, Miniconda requires less disk space.
To download the repository to your local machine as a zip-file, click the `download ZIP` on the
repository page <https://github.com/jorisvandenbossche/DS-python-geospatial> (green button "Code"):

#### Option 2: I have installed Anaconda earlier
![Download button](./static/img/download-button.png)

When you already have an installation of Anaconda, you have to make sure you are working with the most recent versions. As the course is
developed for Python 3, make sure you have Anaconda3 (on Windows, check Start > Programs > Anaconda3). If not, reinstall Anaconda according
to the previous section.
After the download, unzip on the location you prefer within your user account (e.g. `My Documents`, not `C:\`). Watch out for a nested 'DS-python-geospatial/DS-python-geospatial' folder structure after unzipping and move the inner DS-python-geospatial folder to your preferred location.

Start the Anaconda Navigator program (for Windows users: Start > Anaconda Navigator) and go to the Environments tab. You should see
the *base (root) environment*, click the arrow next to it and click `Open terminal`, as shown in the following figure:
__Note:__ Make sure you know where you stored the course material, e.g. `C:/Users/yourusername/Documents/DS-python-geospatial`.

![Navigator terminal](./static/img/navigator_terminal.png)
## 2. Install Python and the required Python packages using `conda`

Type following command + ENTER-button (make sure you have an internet connection):
For scientific and data analysis, we recommend to use `conda`, a command line
tool for package and environment management (<https://docs.conda.io/projects/conda/>).
`conda` allows us to install a Python distribution with the the scientific libraries
we will use in this course (this recommendation applies to all
platforms, so for both Windows, Linux and Mac).

```
conda update -n base conda
```
and respond with *Yes* by typing `y`. Packages should be updated after the completion of the command.
### 2.1 Install `conda`

### Setup after Anaconda installation
#### Option 1: I do not have `conda` installed

As not all packages we will use in the course are provided by default as part of Anaconda, we have to add the package to Anaconda to get started.
As a good practice, we will create a new _conda environment_ to work with. This environment will contain the required packages on which this
course depends.
We recommend to use the installer provided by the conda-forge community: <https://conda-forge.org/download/>.

Follow the instructions on that page, i.e. first download the appropriate
installed (depending on your operating system), and then run that installer.

On Windows, this will mean double-clicking the downloaded `.exe` file, and
following the instructions. During installation, choose the options (click checkbox):

- '_Register Miniforge3 as my default Python 3.12_' (in case this returns an error about an existing Python 3.12 installation, remove the existing Python installation using [windows Control Panel](https://support.microsoft.com/en-us/windows/uninstall-or-remove-apps-and-programs-in-windows-4b55f974-2cc6-2d2b-d092-5905080eaf98)).
- '_Clear the package cache upon completion_'.

On MacOS or Linux, you have to open a terminal,
and run `bash Miniforge3-$(uname)-$(uname -m).sh`

#### Option 2: I already have `conda`, Anaconda or Miniconda installed

When you already have an installation of `conda` or Anaconda, you have to make
sure you are working with a recent version. If you installed it only a few
months ago, this step is probably not needed, otherwise follow the next steps:

1. Open a terminal window (on Windows, use the dedicated "Anaconda Prompt" or "Miniforge Prompt", via Start Menu)
2. Run `conda update conda`, by typing that command, hit the ENTER-button
(make sure you have an internet connection), and respond with *Yes* by typing `y`.
3. Run `conda config --add channels conda-forge`, by typing that command, hit the ENTER-button
4. Run `conda config --set channel_priority strict`, by typing that command, hit the ENTER-button

If you are using Anaconda on Windows, replace each time "Miniforge Prompt" by "Anaconda Prompt" in the following sections.

### 2.2 Setup after `conda` installation

Now we will use `conda` to install the Python packages we are going to use
throughout this course.
As a good practice, we will create a new _conda environment_ to work with.

The packages used in the course are enlisted in
an [`environment.yml` file](https://raw.githubusercontent.com/jorisvandenbossche/DS-python-geospatial/main/environment.yml). The file looks as follows:
Expand All @@ -66,7 +93,7 @@ name: DS-geospatial
channels:
- conda-forge
dependencies:
- python=3.11
- python=3.12
- geopandas
- ...
```
Expand All @@ -76,45 +103,34 @@ The file contains information on:
- `channels` to define where to download the packages from
- `dependencies` contains each of the packages

To download the environment file, click to go to
the [environment.yml](https://raw.githubusercontent.com/jorisvandenbossche/DS-python-geospatial/main/environment.yml) online. Once opened in the
browser, right-click and save the file/page on your computer. The specific text depends on your browser (`Save page as...`, `Save as...`).
The environment.yml file for this course is included in the course material you
downloaded.

__WARNING !__ Make sure you save the file as `environment.yml` instead of `environment.yml.txt` which, specifically on Windows operating system,
might be the default option. To do so, choose for 'save as type' _All Files_ instead of 'Text Document'.
Now we can create the environment:

![](./static/img/environment_save.png)
1. Open the terminal window (on Windows use "Miniforge Prompt", open it via Start Menu > 'Miniforge Prompt')
2. Navigate to the directory where you downloaded the course materials (that
directory should contain a `environment.yml` file, double check in your file explorer):

You will need the folder/directory containing the `environment.yml` file in the next step. Make sure you know where you stored the file on
your computer, e.g. when stored in the folder `C:/Users/yourusername/Documents` you should see the file `environment.yml` in File Explorer
in that directory.
```
cd FOLDER_PATH_TO_COURSE_MATERIAL
```

Next, start the Anaconda Navigator program (for windows users: Start > Anaconda Navigator) and go to the Environments tab. You should see
the *base (root) environment*, click the arrow next to it and click `Open terminal`, as shown in the following figure:
3. Create the environment by typing the following commands line by line +
hitting the ENTER-button (make sure you have an internet connection):

![Navigator terminal](./static/img/navigator_terminal.png)
```
conda env create -f environment.yml
```

Type following commands line by line + ENTER-button (make sure you have an internet connection):

```
conda install -n base conda-libmamba-solver
conda config --set solver libmamba
conda config --add channels conda-forge
conda config --set channel_priority strict
cd FOLDER_PATH_TO_ENVIRONMENT_FILE
conda env create -f environment.yml
```
__!__ `FOLDER_PATH_TO_COURSE_MATERIAL` should be replaced by the path to the
folder containing the downloaded course materials (e.g. in the example it is `C:/Users/yourusername/Documents/DS-python-geospatial`)

__!__ `FOLDER_PATH_TO_ENVIRONMENT_FILE` should be replaced by the path to the folder containing the downloaded environment file. In the
example earlier, this was `C:/Users/yourusername/Documents`, but make sure you use your specific folder (as seen in File Explorer).
__!__ You can safely ignore the warning `FutureWarning: 'remote_definition'...`.

Respond with *Yes* by typing `y` when asked. Output will be printed and if no error occurs, you should have the environment configured
with all packages installed.
Respond with *Yes* by typing `y` when asked. Output will be printed and if no error occurs, you should have the environment configured with all packages installed.

**Note:** If you did use Miniconda instead, create the environment using the same commands/instructions in the terminal (make sure to
do the `conda config ...` steps.).

When finished, keep the terminal window open (or reopen it). Execute the following commands to check your installation:
When finished, keep the terminal window (or "Miniforge Prompt") open (or reopen it). Execute the following commands to check your installation:

```
conda activate DS-geospatial
Expand All @@ -130,34 +146,13 @@ import matplotlib

If no message is returned, you're all set! If a message (probably an error) returned, contact the instructors. Copy paste the message returned.


## 2. (_first day of the course_) Getting the course materials

### Option 1: You are a git user

As the course has been setup as a [git](https://git-scm.com/) repository managed on [Github](https://github.com/jorisvandenbossche/DS-python-geospatial),
you can clone the entire course to your local machine. Use the command line to clone the repository and go into the course folder:
To get out of the Python session, type:

```
git clone https://github.com/jorisvandenbossche/DS-python-geospatial.git
cd DS-python-geospatial
quit
```

In case you would prefer using Github Desktop,
see [this tutorial](https://help.github.com/desktop/guides/contributing-to-projects/cloning-a-repository-from-github-to-github-desktop/).

### Option 2: You are not a git user

To download the repository to your local machine as a zip-file, click the `download ZIP` on the
repository page <https://github.com/jorisvandenbossche/DS-python-geospatial> (green button "Code"):

![Download button](./static/img/download-button.png)

After the download, unzip on the location you prefer within your user account (e.g. `My Documents`, not `C:\`).

__Note:__ Make sure you know where you stored the course material, e.g. `C:/Users/yourusername/Documents/DS-python-geospatial`

## 3. (_first day of the course_) Test your configuration
## 3. Test your configuration

To check if your packages are properly installed, open the Conda Terminal again (see above) and navigate to the course directory:

Expand Down Expand Up @@ -185,12 +180,14 @@ When all checkmarks are ok, you're ready to go!

## 4.(_start of day during course_) Starting Jupyter Notebook with Jupyter Lab

Each of the course modules is set up as a [Jupyter notebook](http://jupyter.org/), an interactive environment to write and run code. It is
no problem if you never used jupyter notebooks before as an introduction to notebooks is part of the course.
Each of the course modules is set up as a [Jupyter notebook](http://jupyter.org/), an interactive environment to write and run code. It is no problem if you never used jupyter notebooks before as an introduction to notebooks is part of the course.

### Option 1: Using the command line

* In the terminal, navigate to the `DS-python-geospatial` directory (downloaded or cloned in the previous section)
* In the terminal (or "Miniforge Prompt"), navigate to the `DS-python-geospatial` directory (downloaded or cloned in the previous section)

```
cd FOLDER_PATH_TO_COURSE_MATERIAL
```

* Ensure that the correct environment is activated.

Expand All @@ -204,14 +201,6 @@ no problem if you never used jupyter notebooks before as an introduction to note
jupyter lab
```

### Option 2: Using Anaconda Navigator

In the Anaconda Navigator *Home* tab, first switch to the course environment, called `DS-geospatial` in the selection bar. Next,
select the Launch button under the Jupyter Lab icon:

![Navigator terminal](./static/img/navigator_notebook.png)

## Next?

This will open a browser window automatically. Navigate to the course directory (if not already there) and choose the `notebooks` folder to
access the individual notebooks containing the course material.
This will open a browser window automatically. Navigate to the course directory (if not already there) and choose the `notebooks` folder to access the individual notebooks containing the course material.
6 changes: 3 additions & 3 deletions docs/slides.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@
# Python for GIS and Geoscience

Doctoral schools of Ghent University<br>
September 20-22, 2023
December 12, 16 and 19, 2024

Joris Van den Bossche, Stijn Van Hoey

Expand Down Expand Up @@ -227,7 +227,7 @@

![:scale 100%](http://esq.h-cdn.co/assets/15/51/980x490/landscape-1450137389-john-cleese.JPG)

### https://forms.gle/j8zYZkUL9J5rfSrw8
### https://forms.gle/trjSSDhzD656j63LA

Please fill in the questionnaire.

Expand Down Expand Up @@ -402,4 +402,4 @@
var slideshow = remark.create();
</script>
</body>
</html>
</html>

0 comments on commit 6b46e36

Please sign in to comment.