This software was developed for EUMETSAT under contract EUM/CO/21/4600002620, funded by the European Union under the Copernicus component of the EU Space Programme.
The ocean-case-studies repository contains a series of Python-based Jupyter Notebooks on ocean phenomena that are generated by the Copernicus Marine Training Services to either accompany EUMETSAT website case studies or as standalone material.
For any questions about this repository, please contact ops@eumetsat.int.
This software and all associated intellectual property rights (IPRs) are owned by the European Union.
This code is licensed under an MIT license. See file LICENSE.txt for details on the usage and distribution terms. No dependencies are distributed as part of this package. Copyright 2024 European Union.
All product names, logos, and brands are property of their respective owners. All company, product and service names used in this website are for identification purposes only.
- Ben Loveday - EUMETSAT
- Hayley Evers-King - EUMETSAT
- Aida Alvera-Azcárate - EUMETSAT
- Charles Troupin - EUMETSAT
- Vinca Rosmorduc - EUMETSAT
- Marie Smith - CSIR
Please see the AUTHORS.txt file for more information.
You will require Jupyter Notebook to run this code. We recommend that you install
the latest Anaconda Python distribution for your
operating system. Anaconda Python distributions include Jupyter Notebook.
Note: The copernicusmarine module is distributed under the EUPL license. However, it is only used as a tool for its intended purpose, and does 9EB6 not affect the distribution license of this repository. Please see EUPL clarification for more details.
None
The simplest and best way to install these packages is via Git. Users can clone this repository by running the following commands from either their terminal (on Linux/OSx), or from the Anaconda prompt.
You can usually find your terminal in the start menu of most Linux distributions and in the Applications/Utilities folder on OSx. Alternatively, you should be able to find/open your Anaconda prompt from your start menu (or dock, or via running the Anaconda Navigator). Once you have opened a terminal/prompt, you should navigate to the directory where you want to put the code. Once you are in the correct directory, you should run the following command;
git clone --recurse-submodules --remote-submodules https://gitlab.eumetsat.int/eumetlab/oceans/ocean-training/applications/ocean-case-studies.git
This will make a local copy of all the relevant files.
Note: If you find that you are missing packages, you should check that you ran
git clone with both the --recurse-submodules and --remote-submodules options.
Note: if you are using an older version of git, you may find that your submodules are empty.
In this case, you need to remove the folder and re-run the line above with --recursive added to the end
Note: in some rare Anaconda instances, Git is not installed by default. To correct
this, you can install Git using conda install git from the Anaconda prompt (Windows)
or in your terminal (OSx/Linux).
This collection supports Python 3.10. Although many options are possible, the authors highly recommend that users install the appropriate Anaconda package for their operating system. In order to ensure that you have all the required dependencies, we recommend that you build a suitable Python environment, as discussed below.
Python allows users to create specific environments that suit their applications. This tutorials included in this collection require a number of non-standard packages - e.g. those that are not included by default in Anaconda. In this directory, users will find a environment.yaml file which can be used to construct an environment that will install all the required packages.
To construct the environment, you should open either terminal (Linux/OSx) or an Anaconda prompt window and navigate to repository folder you downloaded in the Installation section above. In this folder there is a file called environment.yml. This contains all the information we need to install the relevant packages.
Older versions of the conda package manager can be very slow, so we will install a new "solver" that speeds things up. To do this, from the Anaconda prompt (Windows) or in the terminal (OSx/Linux) you can run:
conda install -n base conda-libmamba-solver
Once the line above is run, to create out Python environment, we run:
conda env create -f environment.yml --solver=libmamba
This will create a Python environment called cmts_ocean_case_studies. The environment won't be activated by default. To activate it, run:
conda activate cmts_ocean_case_studies
Now you are ready to go!
Note: remember that you may need to reactivate the environment in every new window instance
Note: if you get a warning that "solver" is not a valid conda argument, you can
skip the libmamba install and run: conda env create -f environment.yml
Note: as you need to install libmamba solver in the conda base environment, this may not always be possible on cloud systems.
This module is based around a series of Jupyter Notebooks, designed to be run in Jupyter Lab.
Jupyter Notebooks support high-level interactive learning by allowing us to combine code, text description and data
visualisations. If you have not worked with Jupyter Notebooks before, please look at the Introduction to Python
and Project Jupyter module to get a short introduction to
their usage and benefits.
To run Jupyter Notebook, open a terminal or Anaconda prompt and make sure you have activated the correct environment. Again, navigate to the repository folder. Now you can run Jupyter using:
jupyter lab or jupyter-lab, depending on your operating system.
This should open Jupyter Lab in a browser window. On occasion, Jupyter may not be able to open a window and will give you a URL to past in your browser. Please do so, if required.
Note: Jupyter Lab is not able to find anything that is 'above' it in a directory tree, and you will unable to navigate to these. So make sure you run the line above from the correct directory!
Now you can run the notebooks! We recommend you start with the Index module.
Note: Jupyter Lab is not able to find anything that is 'above' it in a directory tree, and you will unable to navigate to these. So make sure you run the line above from the correct directory!
Now you can run the notebooks! We recommend you start with the Index module.
If you are running on a remote Jupyter Hub (e.g. WEkEO or Insula Code) you will need to perform some additional steps to ensure that you have the right python environment loaded in your notebook. When running locally, as long you have activated the correct environment, Jupyter will load it into your the "kernel" which runs your code by default. On cloud systems, we have to add the kernel to the system and apply it manually when we run. Below are the steps you need to run on WEkEO or the DestinE Insula Code platforms to configure this repository and run these notebooks;
-
Open JupyterHub: You will need a WEkEO or InsulaCode account to open their respective Jupyter Hubs. You can use the buttons at the top of this README to access the systems. For WEkEO you should choose the "Earth Observation Tools" server.
-
Open a terminal (you can use the + icon on the left hand side of the menu bar to do this)
-
If you are running on WEkEO, access the "work" directory by typing (you can skip this if running on DestinE);
cd ~/work
- Clone the code base to the system using
git clone --recurse-submodules --remote-submodules https://gitlab.eumetsat.int/eumetlab/oceans/ocean-training/applications/ocean-case-studies.git
- Enter the repository directory using
cd ocean-case-studies
- create the python environment using
conda env create -f environment.yml --solver=libmamba -y
- initialise the conda environment with
conda init zsh; source ~/.zshrc
- activate the environment with
conda activate cmts_ocean_case_studies
- add a kernel to your system with
ipython kernel install --name cmts_ocean_case_studies --user
- make some minor fixes
conda remove --force pyproj -y; pip install pyproj
- You should now be able to select the kernel from the menu bar in the top right hand side of any notebook you run.
Note: it sometimes takes a few seconds for the kernel to register in the notebook itself
If you would like to collaborate on a part of this code base or contribute to it please contact us on training@eumetsat.int. If you are have issues and need help, or you have found something that doesn't work, then please contact us at ops@eumetsat.int. We welcome your feedback!