Skip to main content

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.

  1. Please refer to the GitHub Client documentation to install the GitHub client, or see these instructions to install git using the command line.

  2. Clone this repository to your local computer using either of the following options.

    1. 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.

    2. 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.

  3. 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

  1. 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 the mambaforge 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.
  2. 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

  1. 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
    
  2. 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 the mamba command available every time open a new terminal.
  3. 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.

  1. 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".

  2. 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
    
  3. 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.
  4. 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.

  1. Open a terminal or Miniforge prompt.
  2. Change to the directory where you cloned the repository cd </path/to/local/repo>. Note, on Windows you should use backslashes (see sec 2).
  3. Activate your environment by running:
    mamba activate coastal
    
  4. Open Jupyterlab by running the following command:
    jupyter lab
    
    This will open a Jupyterlab client in your browser.
  5. In the JupyterLab IDE you can browse to the notebooks directory and open one of the notebooks, for instance, 01_coastal_classification.ipynb.
  6. Once the notebook is open you can activate the coastal environment in the upper-right corner; change Python 3 (ipykernel) to Python [conda env:coastal].
  7. 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:

  1. Clone this repository
  2. Run mamba env create -f environment-coastal.yml
  3. Run mamba activate coastal
  4. 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:

  1. Run mamba activate coastal
  2. 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.

Metadata

Release files for coastalbook 0.1.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for coastalbook 0.1.3
File Size Uploaded Provenance Actions
coastalbook-0.1.3.tar.gz 13.8 kB Without provenance Details for coastalbook-0.1.3.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for coastalbook 0.1.3
File Interpreter ABI Platform Actions
coastalbook-0.1.3-py3-none-any.whl Python 3 none any Details for coastalbook-0.1.3-py3-none-any.whl

Total release size: 25.0 kB

Release files / coastalbook-0.1.3.tar.gz

Download URL coastalbook-0.1.3.tar.gz
Size 13.8 kB
Tags Source
SHA-256 checksum
How to use checksums
f53a8f4773d14c9a49929ccaf664f3139a116394009de092630ee8d20533d02d
BLAKE2b-256 checksum
How to use checksums
afb8d447596a4b27236053c6c6882c2a1c2b61699af220b28d51b237bb83b034
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/4.0.2 CPython/3.11.6

Release files / coastalbook-0.1.3-py3-none-any.whl

Download URL coastalbook-0.1.3-py3-none-any.whl
Size 11.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
8a462bd0d1fdae7f9b5cc0d320bbb922bdc7d52f32ce8840ab9bf20daf7c2df9
BLAKE2b-256 checksum
How to use checksums
f07b936d7f0d2f97785deee99d672009759601bb7a61f9f6fc3679c6d3c95c64
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/4.0.2 CPython/3.11.6

Security for coastalbook 0.1.3

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.3 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page