Package: coastalbook
Coastal Systems Open CodebookTutorial notebooks for Delft University of Technology Coastal Systems course. The book is
availableonlinein both
PDF and markdown.UsageFor the tuturial sessions we will use an interactive computing environment, that is built
on theJupyterecosystem and mostly rely on software that is supported by numfocus. We will communicate the tutorial content
usinggitversion 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. GitIf you are not familiar with using Git, please have a look this short but excellentintroductionfirst.Please refer to theGitHub Client documentationto
install the GitHub client, or seethese
instructionsto install git using the
command line.Clone this repository to your local
computer using either of the following options.GitHub client: Browse to thewebpage, 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 gitis
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. Followthese
instructionsto 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 managerIf you're not familiar with managing Python environments, please have a look at thisintroductionfirst. 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 managermambaforge. The instructions to install this package
manager can be found intheir
documentation, in which they
refer to theConda Forge GitHubpage to download the software.WindowsDownload the mambaforge executable file for Windows fromMiniforge GitHub
page. On that page there are also
binaries for Mac and Linux; and forcondapackage managers, so make sure you download
themambaforgeexecutable 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 aMiniforge 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 LinuxWe 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"bashMambaforge-$(uname)-$(uname-m).shAccept the user agreements, and allow the installation script to edit your profile
file. The profile file (~/.bashrcon Linux or possibly~/.zshrcon 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 themambacommand available every
time open a new terminal.Close the terminal.3. Software environmentsTo 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--versionIt should output something like:~ (base) mamba --versionmamba 1.1.0conda 22.9.0Now that mambaforge is installed, navigate in the terminal to the directory
where you cloned the GitHub CoastalCodeBook repository. You can navigate the terminal
usingcd, which stands for "change directory".Windows: if you are on Windows and you installed the GitHub client using their default settings you can
simply runcd %userprofile%\Documents\GitHub\CoastalCodeBook.Linux/Mac: change to the directory where you cloned the GitHub repository. This
will be something likecd ~/path/to/github/repository.The CoastalCodeBook root directory contains anenvironment.ymlfile 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:mambaenvcreate-fenvironment.ymlRunning the tutorial notebooksNow 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 atthis
introduction.Open a terminal or Miniforge prompt.Change to the directory where you cloned the repositorycd </path/to/local/repo>.
Note, on Windows you should use backslashes (see sec 2).Activate your environment by running:mambaactivatecoastalOpen Jupyterlab by running the following command:jupyterlabThis will open a Jupyterlab client in your browser.In the JupyterLab IDE you can browse to thenotebooksdirectory and open
one of the notebooks, for instance,01_coastal_classification.ipynb.Once the notebook is open you can activate thecoastalenvironment in the
upper-right corner; changePython 3 (ipykernel)toPython [conda env:coastal].Now you can run the cells and do some interactive coastal analysis!QuestionsIf you have a question about the installation process or notebooks, feel free to open an
issue in theGitHub repository. If
that's your first time, have a look atthese
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 bookIf you'd like to develop and/or build the CoastalCodeBook book, you should:Clone this repositoryRunmamba env create -f environment-coastal.ymlRunmamba activate coastalRunjupyter-book build bookA fully-rendered HTML version of the book will be built inbook/_build/html/.Known issues: If you usenb_conda_kernelsto expose your environments, you might run
into kernelspec errors when building the book. Untilhttps://github.com/executablebooks/jupyter-book/issues/1348is fixed, a workaround is to
add the environments manually to the kernselspec:Runmamba activate coastalRunpython -m ipykernel install --user --name conda-env-coastal-py --display-name "conda-env-coastal-py"ContributorsWe welcome and recognize all contributions. You can see a list of current contributors in
thecontributors
tab.CreditsThis project is created using the excellent open sourceJupyter Book
projectand theexecutablebooks/cookiecutter-jupyter-book
template.