Getting Started#

Project structure#

You are welcome to contribute by improving the code for already existing methods or by adding new code for additional methods and diagnostics. In general, we aim to provide stand alone tutorial notebooks (in ./docs/tutorials/) by making use of the output of a set of very basic example particle simulations (to be found here: ./Simulations/). If the simulation data is not adequate for your analysis, you can generate your own using xarray or download it in the notebook.

Running the notebooks#

Locally#

  • Clone the git repository

    • cd to a location in your filesystem

    • git clone https://github.com/OceanParcels/Lagrangian_diags.git

  • Install and activate the conda environment:

    • conda env create -n lagrangian_diags -f requirements/environment.yml

    • conda activate lagrangian_diags

    • jupyter lab

Note

If you have difficulty running the notebooks/are getting errors from certain packages - it might be that the versions of the packages have been updated since the notebook was made. You can try instead to install an environment by doing conda env create -n lagrangian_diags -f requirements/environment-freeze.yml

Online via Binder#

The notebooks are available using Binder at this link

Development workflow: Adding a new notebook#

To get started contributing to Lagrangian Diags:

  1. Fork the repository

  2. Clone the repository and cd into the project folder

git clone <fork_url>
cd <project_folder>

  1. Create a working branch

git branch <branch_name>
git checkout <branch_name>

  1. Change existing code or add new code - do not forget to regularly commit your changes!

  • Follow the instructions for running the notebooks locally

  • Add your notebook

  • Make sure it runs top to bottom (with our provided environment)

  • commit your changes

  1. Push your changes and make a pull request

git push -u origin <branch_name>

Note

If you have write access to the Lagrangian Diags repository, you don’t have to create a fork. You just need to clone the repository and create a working branch. Just make sure that your working branch has a good naming so that others are aware of its contents (e.g., <your_initials>-dispersion).

Note

If you added a dependency (only do this if you’re on Mac/Linux - if on Windows ask for help), make sure to do the following:

  • re-export the lock file of the conda environment conda env export > requirements/environment-freeze.yml

  • list the dependencies added in requirements/environment.yml and .binder/environment.yml

OPTIONAL: Install documentation dependencies#

If you want to build the documentation locally, you will need to install the dependencies in the docs/environment_docs.yml file. You can create this environment (called diag-docs with the following command):

conda env create -n diag-docs -f docs/environment_docs.yml

Then you can build the documentation with:

sphinx-autobuild docs docs/_build

Credits#

Thank you to our contributors who make this project possible 🎉

Laura Gomez Navarro
Laura Gomez Navarro
💻		 Jimena Medina
Jimena Medina
💻		 sruehs
sruehs
🤔 💻 📆		 Bas Altena
Bas Altena
💻		 Nick Hodgskin (🦎 Vecko)
Nick Hodgskin (🦎 Vecko)
💻