Jupyterbook for Delft Technical University Coastal Systems
Project description
Coastal Systems Open Codebook
Tutorial notebooks for Delft University of Technology Coastal Systems course. The book is available online in both PDF and markdown.
Usage
For the tuturial sessions we will use an interactive computing environment, that is built
on the Jupyter ecosystem and mostly rely on software that is supported by numfocus. We will communicate the tutorial content
using git
version control and provide instructions on how to do so using the GitHub client. In the subsections
that follow we talk you through the three configurations steps.
1. Git
If you are not familiar with using Git, please have a look this short but excellent introduction first.
-
Please refer to the GitHub Client documentation to install the GitHub client, or see these instructions to install git using the command line.
-
Clone this repository to your local computer using either of the following options.
-
GitHub client: Browse to the webpage, click on the green "Code" button and select "Open with GitHub Desktop"; or simply paste the URL into the GitHub client "clone repository" menu.
-
Bash shell: If you have a bash terminal available, assuming that git is configured, you can simply run:
git clone https://github.com/FlorisCalkoen/CoastalCodebook.git
.
-
-
GitHub client does not install the underlying git software on your machine. Follow these instructions to install git on your machine.
By these steps, the files that are hosted at GitHub are "pulled" to your machine. You can check that by opening a file explorer and going to the path where you cloned the directory. The files that you find there should reflect what's on the GitHub page. But we can't we do anything with the files yet, as we don't have the software that can understand the code, so we will continue with installing a package manager.
2. Mamba package manager
If you're not familiar with managing Python environments, please have a look at this
introduction
first. The bottom line is that it is good practice to manage your software environments
to avoid dependency conflicts. For the tutorial notebooks, we recommend to use the
lightweight package manager mambaforge
. The instructions to install this package
manager can be found in their
documentation, in which they
refer to the Conda Forge GitHub
page to download the software.
Windows
- Download the mambaforge executable file for Windows from Miniforge GitHub
page. On that page there are also
binaries for Mac and Linux; and for
conda
package managers, so make sure you download themambaforge
executable file for Windows. Install the executable by clicking on it; you can stay with the default settings by just clicking next through the installation client. - Now that mambaforge is installed, you can open a
Miniforge Prompt
. You can open this shell by opening the start window and search for "Miniforge".
Known issues: Some users have their firewalls configured in such way that the mambaforge installation is blocked. If you have trouble installing mambaforge, please make sure to temporarily disable your firewall.
Unix like - Mac and Linux
- We recommend to install Mambaforge on Linux and Mac using a terminal. On Mac, you can
open a terminal by searching for "terminal" or "iterm". On Linux the hotkey to open a
terminal is "cntrl + shift + t". The commands to
install the package manager are copied from their documentation and can be run by
copying the commands below over to your terminal and pressing enter:
curl -L -O "https://github.com/conda-forge/miniforge/releases/latest/download/Mambaforge-$(uname)-$(uname -m).sh" bash Mambaforge-$(uname)-$(uname -m).sh
- Accept the user agreements, and allow the installation script to edit your profile
file. The profile file (
~/.bashrc
on Linux or possibly~/.zshrc
on Mac) is the first script which is being executed when you open a new terminal. The installation script will add a few lines to that file to make themamba
command available every time open a new terminal. - Close the terminal.
3. Software environments
To run the tutorial notebooks we need several packages. To avoid dependency conflicts it is good practice to seperate your environments; that was the reason for installing a package manager. Now that we have our package manager we will create the software environments. We will create one environment that runs the JupyterLab IDE, including several extensions; and another one that contains the packages that we need for the tutorials.
-
Now that mambaforge is available on your machine, open a terminal. On Windows you should open the Miniforge prompt, which you can find by searching for it in the Start window. On Mac you can open a terminal by searching for "terminal" or "iterm". For Linux it's "cntrl + shift + t".
-
You can check if mamba was installed by running the following command in the terminal:
mamba --version
It should output something like:
~ (base) mamba --version mamba 1.1.0 conda 22.9.0
-
Now that mambaforge is installed, navigate in the terminal to the directory where you cloned the GitHub CoastalCodeBook repository. You can navigate the terminal using
cd
, which stands for "change directory".- Windows: if you are on Windows and you installed the GitHub client using their default settings you can
simply run
cd %userprofile%\Documents\GitHub\CoastalCodeBook
. - Linux/Mac: change to the directory where you cloned the GitHub repository. This
will be something like
cd ~/path/to/github/repository
.
- Windows: if you are on Windows and you installed the GitHub client using their default settings you can
simply run
-
The CoastalCodeBook root directory contains an environment.yml file that describes the software dependencies. This environment contains several packages and extension to build an interactive Jupyter lab environment that you can use to run the tutorial notebooks.
You can create the software environment using this command:
mamba env create -f environment.yml
Running the tutorial notebooks
Now that you have access to the code (cloning this Github repository), installed a package manager and created your environments we can start running the notebooks in Jupyterlab. If you are new to JupyterLab we encourage you to have a look at this introduction.
- Open a terminal or Miniforge prompt.
- Change to the directory where you cloned the repository
cd </path/to/local/repo>
. Note, on Windows you should use backslashes (see sec 2). - Activate your environment by running:
mamba activate coastal
- Open Jupyterlab by running the following command:
jupyter lab
This will open a Jupyterlab client in your browser. - In the JupyterLab IDE you can browse to the
notebooks
directory and open one of the notebooks, for instance, 01_coastal_classification.ipynb. - Once the notebook is open you can activate the
coastal
environment in the upper-right corner; changePython 3 (ipykernel)
toPython [conda env:coastal]
. - Now you can run the cells and do some interactive coastal analysis!
Questions
If you have a question about the installation process or notebooks, feel free to open an issue in the GitHub repository. If that's your first time, have a look at these instructions. We choose to use the GitHub issue-tracker because your fellow students probably have similar problems. We will not troubleshoot the tutorial notebooks by email.
Building the book
If you'd like to develop and/or build the CoastalCodeBook book, you should:
- Clone this repository
- Run
mamba env create -f environment-coastal.yml
- Run
mamba activate coastal
- Run
jupyter-book build book
A fully-rendered HTML version of the book will be built in
book/_build/html/
.
Known issues: If you use nb_conda_kernels
to expose your environments, you might run
into kernelspec errors when building the book. Until
https://github.com/executablebooks/jupyter-book/issues/1348 is fixed, a workaround is to
add the environments manually to the kernselspec:
- Run
mamba activate coastal
- Run
python -m ipykernel install --user --name conda-env-coastal-py --display-name "conda-env-coastal-py"
Contributors
We welcome and recognize all contributions. You can see a list of current contributors in the contributors tab.
Credits
This project is created using the excellent open source Jupyter Book project and the executablebooks/cookiecutter-jupyter-book template.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
File details
Details for the file coastalbook-0.1.3.tar.gz
.
File metadata
- Download URL: coastalbook-0.1.3.tar.gz
- Upload date:
- Size: 13.8 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/4.0.2 CPython/3.11.6
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | f53a8f4773d14c9a49929ccaf664f3139a116394009de092630ee8d20533d02d |
|
MD5 | 4f74c2d21d7e205b5f2a80fcbd5d7214 |
|
BLAKE2b-256 | afb8d447596a4b27236053c6c6882c2a1c2b61699af220b28d51b237bb83b034 |
Provenance
File details
Details for the file coastalbook-0.1.3-py3-none-any.whl
.
File metadata
- Download URL: coastalbook-0.1.3-py3-none-any.whl
- Upload date:
- Size: 11.2 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/4.0.2 CPython/3.11.6
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 8a462bd0d1fdae7f9b5cc0d320bbb922bdc7d52f32ce8840ab9bf20daf7c2df9 |
|
MD5 | eb82104e87e868b1c665e7d96770d47a |
|
BLAKE2b-256 | f07b936d7f0d2f97785deee99d672009759601bb7a61f9f6fc3679c6d3c95c64 |