Scientific software | Victor Boussange

AMJAX

Thu, 01 Jan 2026 00:00:00 +0000

jaxscape

Thu, 01 Jan 2026 00:00:00 +0000

A course on reproducible research, data pipelines, and scientific computing

Tue, 11 Jun 2024 00:00:00 +0000

Practical introduction to Julia for biodiversity research

Wed, 01 Mar 2023 00:00:00 +0000

HybridDynamicModels.jl

Wed, 01 Jan 2025 00:00:00 +0000

yDiv workshop funding

Thu, 01 Aug 2024 00:00:00 +0000

Course On Reproducible Research, Data Pipelines, and Scientific Computing

Tue, 11 Jun 2024 00:00:00 +0000

WSL Biodiversity Center Innovative Workshop Grant

Wed, 01 Mar 2023 00:00:00 +0000

EcoEvoModelZoo.jl

Sun, 26 Mar 2023 00:00:00 +0000

EvoId.jl

Fri, 01 Jan 2021 00:00:00 +0000

Developing an algebraic multigrid solver in JAX

Wed, 19 Nov 2025 00:00:00 +0000

Multigrid methods represent the state-of-the-art for solving large-scale linear systems arising from discretized partial differential equations, offering optimal computational complexity for many problem classes.

Established implementations such as pyAMG and AMG.jl provide robust solvers but lack two critical capabilities for modern scientific machine learning: GPU acceleration and automatic differentiation compatibility. These features are essential for scientific machine learning workflows where differentiable simulation components (e.g., neural networks embedded in physical models) require efficient iterative solves with gradient backpropagation for end-to-end optimization.

This project aims to develop an algebraic multigrid (AMG) solver in JAX that natively supports automatic differentiation and GPU acceleration. The work involves analyzing existing Python and Julia implementations to design an architecture compatible with JAX’s functional programming paradigm and just-in-time compilation model. A successful implementation could have substantial impact on the JAX ecosystem, from accelerating finite element packages to accelerating ecological connectivity analysis tools.

The project scope is flexible and can emphasize software engineering or algorithmic optimization depending on the student’s background and interests. Prior experience with JAX or advanced numerical linear algebra is beneficial but not required; students will gain deep expertise in iterative solvers, functional programming patterns, and best practices for scientific open-source software development.

A multi-language overview on how to document your research project code

Tue, 11 Jun 2024 00:00:00 +0000

Documentation serves multiple purposes and may be useful for various audiences, including your future self, collaborators, users and contributors - should you aim at packaging some of your code into a general-purpose library.

This post is part of a series of posts on best practices for managing research project code. Much of this material was developed in collaboration with Mauro Werder as part of the Course On Reproducible Research, Data Pipelines, and Scientific Computing (CORDS). If you have experiences to share or spot any errors, please reach out!

Content

Content

Style guides

The best documentation starts by writing self-explanatory code with good conventions.

Correctly naming your variables enhances code clarity.

There are only two hard things in Computer Science: cache invalidation and naming things. Martin Fowler

Instead of using generic names like l for a list:

for l in L:
    pass

Use descriptive names like

for line in lines:
    pass

Using style guides for your chosen language ensures consistency and readability in your code. Here are some resources:

Do not hesitate to refactor your code regularly and remove dead code to prevent confusion for yourself and others.

Comments

In-line comments should be used sparingly. Aim to write self-explanatory code instead. Use comments to provide context not apparent from the code itself, such as references to papers, Stack Overflow topics, or TODOs.

Use single-line comments for brief explanations and multi-line comments for more detailed information.

julia

#=
This is a multi-line
comment
=#

python

"""
This is a multi-line
comment
"""

Tip: use vscode rewrap comment/text to nicely format multiline comments.

On top of nicely formatting your code and appending comments where necessary, a literal documentation greatly facilitates the maintenance, understandability and reproducibility of your code.

Literal documentation

Literal documentation helps users understand your tool and get started with it.

README

A README file is essential for any research repository. It is displayed on under the code structure when accessing a GitHub repo. It should contain:

(Badges showing tests, and a nice logo)
A one-sentence description of your project
A longer description
An overview of the repository structure and files
A Getting started or Examples section
An Installation section with dependencies
A Citation/Reference section
(A link to the documentation)
(A How to contribute section)
An Acknowledgement section
A License section

Some examples:

API documentation / doc strings

API documentation describes the usage of functions, classes (types) and modules (packages). Parsers usually support markdown styles, which also enhances raw readability for humans. In short, markdown styles consists in using

backticks ` for variable names
# for titles,
…
See here for an introduction to markdown

Doc strings in python live inside the function

def best_function_ever(a_param, another_parameter):
    """
    this is the docstring
    """
    # do some stuff

But above the function or type definition in Julia

"""
this is the docstring
"""
function best_function_ever(a_param, another_parameter)
# do some stuff
end

"Tell whether there are too foo items in the array."
foo(xs::Array) = ...

Best practice for docstrings include

(in Julia: insert the signature of your function )
Short description
Arguments (Args, Input,…)
Returns
Examples

Several flavours may be used, even for a single language.

python 3 Different documentation style flavours

Google style is easier to read for humans

def add(a, b):
    """
    Add two integers.

    This function takes two integer arguments and returns their sum.

    # Parameters:
    a: The first integer to be added.
    b: The second integer to be added.

    # Return:
    int: The sum of the two integers.

    # Raise:
    TypeError: If either of the arguments is not an integer.

    Examples:
    >>> add(2, 3)
    5
    >>> add(-1, 1)
    0
    >>> add('a', 1)
    Traceback (most recent call last):
        ...
    TypeError: Both arguments must be integers.
    """
    if not isinstance(a, int) or not isinstance(b, int):
        raise TypeError("Both arguments must be integers")
    return a + b

julia

"""
    add(a, b)

Adds two integers.

This function takes two integer arguments and returns their sum.

# Arguments
- `a`: The first integer to be added.
- `b`: The second integer to be added.

# Returns
- The sum of the two integers.

# Examples

```julia-repl
julia> add(2, 3)
5

julia> add(-1, 1)
0
```
"""
function add(a, b)
    return a + b
end

You may use tools like Documenter.jl or Sphinx to automatically render your API documentation on a website. Github actions can automatize the process of building the documentation for you, similarly to how it can automate testing.

Docstrings may be accompanied by typing.

Type annotations

Typing refers to the specification of variable types and function return types within a programming language. It helps define what kind of data a function or variable can handle, ensuring type safety and reducing runtime errors. It

clearly indicates the expected input and output types, making the code easier to understand.
helps catch type-related errors early in the development process.
encourages consistent usage of types throughout the codebase.

python

def add(a: int, b: int) -> int:
    return a + b

In Python, using typing does not enforce type checking at runtime! You may use decorators to enforce it.

julia

function add(a::Int, b::Int)
    return a + b
end

In Julia, types are enforced at runtime! Type annotations help the Julia compiler optimize performance by making type inferences easier.

Consider raising errors

We do not like reading manuals. But we are foreced to read error messages. Use assertions and error messages to handle unexpected inputs and guide users.

python

assert: When an assert doesn’t pass, it raises an AssertionError. You can optionally add an error message at the end.
NotImplementedError, ValueError, NameError: Commonly used, generic errors you can raise. I probably overuse NotImplementedError compared to other types.

def convolve_vectors(vec1, vec2):
    if not isinstance(vec1, list) or not isinstance(vec2, list):
        raise ValueError("Both inputs must be lists.")
    # convolve the vectors

Tutorials

Create tutorial Jupyter notebooks or vignettes in R to demonstrate the usage of your code. Those can be placed in a folder examples or tutorials. Format them as e.g.

vignettes in R,
or using Jupyter notebooks, which are the perfect format for tutorials

Accessing documentation

julia

?cos
?@time
?r""

python

help(myfun)

But e.g. VSCode can be also quite helpful, and this works also with your own code!

Doc testing

Doc testing, or doctest, allows you to test your code by running examples embedded in the documentation (docstrings). It compares the output of the examples with the expected results given in the docstrings, ensuring the code works as documented.

Why doc testing?

Ensures that the code examples in your documentation are accurate and up-to-date.
Simple to write and understand, making it accessible for both writing and reading tests.
Promotes writing comprehensive docstrings which enhance code readability and maintainability.

Python

def add(a, b):
    """
    Adds two numbers.

    >>> add(2, 3)
    5
    >>> add(-1, 1)
    0
    """
    return a + b

To run the test:

python -m doctest your_module.py

or from within a script

if __name__ == "__main__":
    import doctest
    doctest.testmod()

julia Available through Documenter.jl

"""
Adds two numbers.

```jldoctest
julia> add(2, 3)
5

julia> add(-1, 1)
0
```
"""

function add(a, b)
    return a + b
end

Useful packages to help you write and lint your documentation

Better Comments
Automatic doc string generation
Python test explorer

More resources

Take home messages

Good documentation helps maintain the long-term memory of a project.
Refactor code to reduce complexity instead of documenting tricky code.
Writing unit tests is often more productive than extensive documentation.
Types of documentation include literal, API, and tutorial/example documentation.
Literal documentation explains the big picture and setup.
API documentation lives in docstrings and explains function usage.
Examples connect the details to common tasks.
Consider using tools like ChatGPT to assist with documenting your functions.

A multi-language overview on how to handle dependencies within a research project

Tue, 11 Jun 2024 00:00:00 +0000

Your future self and others should be able to recreate the minimal environment to run the scripts in your research project. This is best achieved using package managers and virtual environments.

Content

Some definitions

What is a dependency?

A dependency is an external package that a project requires to run.

What is a package manager?

A package manager like conda, Pkg or renv automates the process of installing, upgrading, configuring, and managing dependencies. It usually relies on a package repository, which is a central location that stores in one place the source code of packages or where to find it.

What is a virtual environment?

A virtual environment is an isolated environment where you can install and manage dependencies separately from the system-wide installation. This isolation ensures that different projects can have different dependencies and versions of packages without causing conflicts. Why use a virtual environment?

For yourself, to best deal with multiple projects and to prevent your code from breaking down overtime.
- Without specifying a virtual environment, you install packages in your base environment, which is shared across all your projects.
- Imagine you are working with Project A and Project B, which both depend on Package1 (currently @v1.1).
- You leave aside Project A for a few months, and focus on Project B.
- A new feature in Package1 motivate you to upgrade to v1.2, which modifies the API or the behavior of one function used in both projects.
- You then want to come back to Project A, but now everything is broken! Because your code has been formatted to work with Package1@v1.1.
- Hence, you want to make sure to compartmentalize environments.
To share your environment with others individuals and machines.
- A virtual environement tracks the minimum dependencies, which can easily be shared and installed on other machines (e.g., a HPC).

Package managers

Multilanguage overview

	Python	R	Julia
Package Manager	`pip`, `conda` (see also `mamba`), `poetry`	`install.packages()` (base R)	`Pkg`
Package Repository	PyPI (Python Package Index), `conda-forge`	CRAN (Comprehensive R Archive Network)	General registry
Distribution Format	`.whl` (wheel, incl binaries) or `tar.gz` (source)	`.tar.gz` (source and/or binary)	`Pkg` will git clone from source, and download (binary) artifacts
Virtual Environment	`venv`, `virtualenv`, `conda env`	`renv`	Built-in in the `Pkg` module
Dependency Management	`requirements.txt` or `Pipfile` (`pip`), or `environment.yml` (`conda env`) or `pyproject.toml` (`poetry`)	`DESCRIPTION`, `NAMESPACE`	`Project.toml`, `Manifest.toml`, `Artifacts.toml`

This table is very much inspired by The Scientific Coder article on package managers.

Julia or R have built-in package managers which can be called within the REPL but Python package managers are called from outside the language.

`conda`

conda is a very appropriate package manager for scientific projects in Python. Over its older concurrent pip, it can handle python versions and all sorts non-python dependencies artifacts. With two lines of code, it allows someone to quickly install the virtual environment, without any pre-requiste python installation.

Here are some essential conda commands.

conda create --name myenv # creates new virtual environment
conda activate myenv # activate the environment
conda install numpy -c conda-forge # install a package
conda deactivate

Note that not using -c conda-forge will do just fine, but what is it? conda-forge is a community-driven channel (repository in the python jargon) that often has more up-to-date packages and a broader selection than the default Anaconda repository. You should use for several reasons, but mostly because conda-forge generally has the largest volume of packages and the most up-to-date versions

Note that some packages are only available through PyPi (pip). But you are covered for that: You can install pip packages within a conda env, by first activating the conda env and then normally using pip. pip should be part of your dependencies though. Always try to install packages using conda first.

We highly recommend using mamba as a drop-in replacement for conda, for much faster use.

Some useful resources

`renv`

Here are some basics on how to use renv, but see the renv vignette and documentation for more advanced usage.

# Initialize renv in your project
renv::init(project = "path/to/environment")

# Install a package and snapshot the environment
install.packages("dplyr")
renv::snapshot()

# Load the renv environment for the project
renv::activate()

# Restore the project's dependencies
renv::restore()

renv::update()

renv::history()
renv::revert()

`Pkg`

using Pkg

# Create a new project environment
Pkg.activate("path/to/MyProject")

# Add packages to the project environment
Pkg.add("DataFrames")

You can also use the Julia REPL by typing ]

(@v1.10) pkg> add DataFrames

or string macros pkg"add DataFrames"

Not that in Julia, the global shared environment is inherited in custom environment. This can be useful! It is a good idea to install utility packages that you will use for development but that are not mandatory to run your code in the global environment. For instance, the macro @btime from BenchmarkTools is very handy to profile code. But you may not want to have BenchmarkTools in your dependencies. Just install it in base, and then you will be able to call julia using BenchmarkTools within your custom environment. Other utility packages to consider having in your global environments are

Test,
TestEnv,
Revise
LocalRegistry

Environment files

Environment files specify the exact versions of the dependencies in your virtual environment, and are used by package managers to instantiate the environment. They are usually .txt, .toml or .yml files.

Always version control your environment files!

Julia

In Julia, the environment is defined using two files: the Project.toml and Manifest.toml. The Project.toml file lists the direct dependencies, while the Manifest.toml file captures the full dependency graph, including all transitive dependencies. The Manifest.toml file may not be tracked in a project, and will be reconstructed if missing. It specifies the exact version of the environment. For reproducibility, you want to include Manifest.toml in your git repo. Artifacts.toml is used to handle non-Julia package dependencies.

Project.toml example


authors = ["Some One ",
           "Foo Bar "]
name = "MyEnv"
uuid = "7876af07-990d-54b4-ab0e-23690620f79a" # mandatory for packages
version = "1.2.5"
[deps]
DataFrames = “7876af07-990d-54b4-ab0e-23690620f79a”
Plots = “8dfed614-e22c-5e08-85e1-65c5234f0b40”
[compat]
CUDA = “4.4, 5”
julia = “1.10”

When you are located within the project root folder containing the .toml file, start julia with

$ julia --project=.

This will load the environment. If it is the first time that you use it, you need to instantiate it with

(Example) pkg> instantiate

Some useful resources

see here for more info on Julia .toml files here

Python

conda env reads .yml, which can take any names. .yml files are not created automatically! Create environment.yml with

conda env export --name machine-learning-env --from-history --file environment.yml

This creates an environment.yml file

environment.yml example


name: machine-learning-env
channels:

pytorch
conda-forge

dependencies:

pytorch=1.1

Not using --from-history will result in listing all dependencies, those installed explicitly AND implicitly. This may be a bit messier.

To specify pip packages, just insert in the .toml

  - pip=19.1
  - pip:
    - kaggle==1.5
    - yellowbrick==0.9

Note the double ‘==’ instead of ‘=’ for the pip installation and that you should include pip itself as a dependency and then a subsection denoting those packages to be installed via pip. Also, note that --from-history won’t catch the pip dependencies. So the best way to proceed is to specify the dependencies by hand.

Installing from environment.yml

mamba env create --prefix ./.env --file environment.yml

Some additional resources

Good resource on managing packages with pip

R

Environments with renv are specified in a renv.lock and DESCRIPTION files. It is a JSON file that has two main components: R and Packages. The R component specifies the R version used and the list of repositories where packages were installed. The Packages component includes a record for each package used in the project, with all necessary details for reinstalling that exact version. These details are derived from the installed package’s DESCRIPTION file and cover installations from any source, including CRAN, Bioconductor, GitHub, Gitlab, and Bitbucket. For more information on supported sources, refer to vignette(“package-sources”).

renv.lock


{
  "R": {
    "Version": "4.3.3",
    "Repositories": [
      {
        "Name": "CRAN",
        "URL": "https://cloud.r-project.org"
      }
    ]
  },
  "Packages": {
    "markdown": {
      "Package": "markdown",
      "Version": "1.0",
      "Source": "Repository",
      "Repository": "CRAN",
      "Hash": "4584a57f565dd7987d59dda3a02cfb41"
    },
    "mime": {
      "Package": "mime",
      "Version": "0.12.1",
      "Source": "GitHub",
      "RemoteType": "github",
      "RemoteHost": "api.github.com",
      "RemoteUsername": "yihui",
      "RemoteRepo": "mime",
      "RemoteRef": "main",
      "RemoteSha": "1763e0dcb72fb58d97bab97bb834fc71f1e012bc",
      "Requirements": [
        "tools"
      ],
      "Hash": "c2772b6269924dad6784aaa1d99dbb86"
    }
  }
}

Working with interactive environments

Jupyter notebooks can use Pkg, conda and renv environments, but you may need some extra steps (see how to make Jupyter aware of your Conda environments here and there. You do not need to follow these steps if you are using Visual Studio Code.

Other interactive notebooks solutions store directly the environemnts in the files, which is great for reproducibility purposes. This is the case of Pluto notebooks, which are designed to be reproducible. Under the hood they contain the package environment inside them Binder notebooks also ship with a virtual environment, but using Docker (see below and a tutorial here).

I personally do not like notebooks, and prefer using scripts in Visual Studio Code, executing them line by line for development with whether the Julia extension or the Jupyter extension with "jupyter.interactiveWindow.textEditor.executeSelection": true. With such an approach, you can specify which virtual environment should be used at login, and never worry again with that later.

Caveats of virtual environments

Some packages/libraries rely on system libraries and utilities; for instance pytorch relies on CUDA drivers, which are specific to a certain machine (see how you can deal with CUDA drivers with conda here), or the behavior of the packages my be dependent on system environmental variables. As such, by replicating a virtual environment, you won’t necessarily reproduce the same exact computing environment. To reproduce more closely a computing environment, containers may be used. Containers virtualize layers of the operating system, replicating to a deeper lever your environment and making it more reproducible. Docker or Singularity are popular solutions. Unfortunately, building containers may be difficult, and the virtualization may add a layer of complexity to your pipeline… But see Using singularity as a development environment and How to remote dev with vscode and singularity. Note that you could use both a container and a virtual environment… See here a tutorial with renv.

Some additional resources For more information, check Reproducible Computational Environments Using Containers: Introduction to Docker.

Advanced topic: package development

It can make sense for research projects to distinguish between scripts placed in scripts/ and reused functions, models, etc., placed in src. We’ll cover that more broadly in another post. In such case, it is best to compartmentalize dependencies so as to have a minimal working environment for the src/ functions and classes, independent of that for your scripts. One practical approach for this is to specify the src folder as a package. This has a few advantages, including

not having to deal with relative position of files to call the functions in src/
maximizing your productivity by creating a generic package additionally to your main research project.

You can achieve this easily with development tools.

For Python, tools like setuptools and poetry facilitate package development. If you’re working in R, devtools is the go-to tool for developing packages. In Julia, the Pkg tool serves a similar purpose.

Package templates can be useful to simplify the creation of packages by generating package skeletons. In Python, checkout out cookiecutter. In R, check usethis. For Julia, use the Pkg.generate() built-in functionality, or the more advanced PkgTemplates.jl package.

Note that you may want at some point to locate your src/ (and associated tests, docs, etc…) in a separate git repo.

Some additional resources

goodresearch tutorial on how to install a project package
the Python Packages book offers comprehensive guidance using poetry.
the R Packages book covers all aspects of package development.
the Pkg documentation and this how-to guide for detailed instructions.

Take-home messages

Make sure you understand what are package managers, virtual environments, and dependencies both within your project scripts and at the system level.
Clearly document all dependencies and environment setup instructions in project repositories.
Provide instructions in an Installation section in the readme.md on how to set up the virtual environment.
Check out these toy research repositories in Julia (which uses relative paths for importing the src functions), Python (which has src as package), and R (which has src as package) that implement what I believe good examples of research projects!

A multi-language overview on how to organise your research project code and documents

Tue, 11 Jun 2024 00:00:00 +0000

I personally find that one of the biggest challenge when doing research is to keep things neat and organized. Having a good management system for your code and resources is key to optimizing time and brain resources. In this post, I discuss various methods for structuring a research project folder that includes code, data, publications, and more. Additionally, I discuss the specifics of organizing your research code. As I started my PhD, I wish I could have had some of such guidelines. But starting from scratch allowed me to build, with trials and errors, a good system for my later life. Hopefully, some of this can apply to you!

This post is part of a series of posts on best practices for managing research code. Much of this material was developed in collaboration with Mauro Werder as part of the Course On Reproducible Research, Data Pipelines, and Scientific Computing (CORDS). If you have experiences to share or spot any errors, please reach out!

Content

Project folder structures

I quite like this project folder structure, which keeps apart raw data and results from the code, but still place them relatively close, together with admin and publications. Having a separate git repo for the paper is something I would recommend as well (possibly linked to an Overleaf project).

|-- code/
|-- data/
|-- results
|-- publications
|    |-- talks
|    |-- posters
|    |-- papers
|-- admin
|-- meetings
|-- more-folders
 -- README.md

You may want to place results within code, together with data (which you should not git track) The structure of code/ deserves here some attention.

`code/` structure

Programming languages typically have their own conventions, but often the folders follow this scheme

a README.md file at the top level
a src/ folder, containing models and other generic function and classes, that will be used in script/ files,
example usages, e.g. examples/
scripts to run models, evaluation, etc., e.g. scripts/
documentation (often generated), e.g. docs/

It can make sense for research projects to distinguish between scripts placed in scripts/ and reused functions, models, etc., placed in src.

Python Folder structure

|-- src/            # package code
|-- scripts/        # Custom analysis or processing scripts
|-- tests/
|-- examples/       # Example scripts using the package
|-- docs/           # documentation
 -- environment.yml # to handle project dependencies
 -- README.md

R Folder structure

|-- R/               # R scripts and functions (package code)
|-- scripts/         # Custom analysis or processing scripts
|-- man/             # Documentation files
|-- tests/
|-- examples/        # Example scripts using the package
|-- vignettes/       # Long-form documentation
 -- DESCRIPTION      # Package description and metadata
 -- NAMESPACE        # Namespace file for package
 -- README.md        # Project overview and details

Julia Folder structure

|-- src/            # package code
|-- scripts/        # Custom analysis or processing scripts
|-- test/
|-- examples/       # Example scripts using the package
|-- docs/           # documentation
 -- Project.toml    # to handle project dependencies
 -- README.md

Turning your `code/` into a “package”

You may want to specify the src folder as a package. This has a few advantages, including

not having to deal with relative position of files to call the functions in src/
maximizing your productivity by creating a generic package additionally to your main research project.

To import functions and classes (types) located in the src folder, you typically need to indicate in each script the relative path of src. In Julia, you would typically do something like include("../src/path/to/your/src_file.jl"). In Python, you would do something like:

import sys
sys.path.append("../src/")

from src.path.to.your.src_file import my_fun

If src/ directory grows, it’s beneficial to convert it into a separate package. Although this process is a bit more complex, it eliminates the need for path specifications, simplifies the import of functions and classes, and makes the codebase easily accessible for other research projects.

There are typically ways to turn a code-project into an installable package. This is in particular useful for code which other people (or yourself) use for different projects.

You can achieve this easily with development tools.

Note that you may want at some point to locate your src/ (and associated tests, docs, etc…) in a separate git repo.

Wrapping up

Explore these exemplary toy research repositories in different programming languages:

Julia, using relative paths for importing src functions.
Python, implementing src as a package.
R, also implementing src as a package.

These repositories showcase what I consider to be best practices in research project organization.

Take-home messages

There is not one way to structure your research project folders, but general guidelines. Create the one that makes most sense for you!
A chosen structure should be suitable to both work during the development of your project, and to submit (parts) of it to a repository in a future stage.
Consider turning your src/ into a folder. This can increase your academic productivity, as you could eventually be the developer of a cool package that people re-use, with minimum efforts!

A multi-language overview on how to test your research project code

Tue, 11 Jun 2024 00:00:00 +0000

Code testing is essential to identify and fix potential issues, to maintain sanity over the course of the development of the project and quickly identify bugs, and to ensure the reliability and sanity of your experiment overtime.

Content

Unit testing

Unit testing involves testing a unit of code, typically a single function, to ensure its correctness. Here are some key aspects to consider:

Test for correctness with typical inputs.
Test edge cases.
Test for errors with bad inputs.

Some developers start writing unit tests before writing the actual function, a practice known as Test-Driven Development (TDD). Define upstream on a piece of paper the behavior of the function, write corresponding tests, and when all tests pass, you are done. This philosophy ensures that you have a well-tested implementation, and avoids unnecessary feature development, forcing you to focus only on what is needed. While TDD is a powerful idea, it can be challenging to follow strictly.

A good idea is to write an additional test when you find a bug in your code.

Lightweight formal tests with `assert`

The simplest form of unit testing involves some sort of assert statement.

Python

def fib(x):
    if x <= 2:
        return 1
    else:
        return fib(x - 1) + fib(x - 2)

assert fib(0) == 0
assert fib(1) == 1
assert fib(2) == 1

Julia

@assert 1 == 0

When one test is broken, you’ll get an error for the corresponding test, which you’ll need to fix to check the following tests.

In Julia or Python, you could directly place the assert statement after your functions. This way, tests are run each time you execute the script. Here is nother pythonic approach, which can be used to decouple the test

def fib(x):
    if x <= 2:
        return 1
    else:
        return fib(x - 1) + fib(x - 2)

if __name__ == '__main__':
    assert fib(0) == 0
    assert fib(1) == 1
    assert fib(2) == 1
    assert fib(6) == 8
    assert fib(40) == 102334155
    print("Tests passed")

Consider using np.isclose, np.testing.assert_allclose (Python) or approx (Julia) for floating point comparisons.

Testing with a test suite

Once you have many tests, it makes sense to group them into a test suite and run them with a test runner. This approach will run all tests, even though some are broken, and retrieve and informative statements on those tests that passed, and those that did not. As you’ll see, it also allows to automatically run the test at each commit, with continuous integration.

Python

Two main frameworks for unit tests in Python are pytest and unittest, with pytest being more popular.

Example using pytest:

from src.fib import fib
import pytest

def test_typical():
    assert fib(1) == 1
    assert fib(2) == 1
    assert fib(6) == 8
    assert fib(40) == 102334155

def test_edge_case():
    assert fib(0) == 0

def test_raises():
    with pytest.raises(NotImplementedError):
        fib(-1)

    with pytest.raises(NotImplementedError):
        fib(1.5)

Run the tests with:

pytest test_fib.py

Julia

Built in module Test, relying on the macro @test. Consider grouping your tests with

julia> @testset "trigonometric identities" begin
          θ = 2/3*π
          @test sin(-θ) ≈ -sin(θ)
          @test cos(-θ) ≈ cos(θ)
          @test sin(2θ) ≈ 2*sin(θ)*cos(θ)
          @test cos(2θ) ≈ cos(θ)^2 - sin(θ)^2
      end;

This will nicely output

Test Summary:            | Pass  Total  Time
trigonometric identities |    4      4  0.2s

which comes handy for grouping tests applied to a single function or concept. Test functions may require additional packages to your minimum working environment specified at your package root folder. An additional virtual environment may be specified for tests! To develop my tests interactively, I like using TestEnv. Unfortunately, using Pkg.activate in tests would not work there, you. You need TestEnv to have access to your package functions;

In your package environment,

using TestEnv
TestEnv.activate()

will activate the test environment.

To reactivate the normal environment,

Pkg.activate(".")

Here is a nice thread to read more on that.

R

testhat

Testing non-pure functions and classes

For nondeterministic functions, provide the random seed or variables needed by the function as arguments to make them deterministic. For stateful functions, test postconditions to ensure the internal state changes as expected. For functions with I/O side effects, create mock files to verify proper input reading and expected output.

Python

def file_to_upper(in_file, out_file):
    fout = open(out_file, 'w')
    with open(in_file, 'r') as f:
        for line in f:
            fout.write(line.upper())
    fout.close()

import tempfile
import os

def test_file_to_upper():
    in_file = tempfile.NamedTemporaryFile(delete=False, mode='w')
    out_file = tempfile.NamedTemporaryFile(delete=False)
    out_file.close()
    in_file.write("test123\nthetest")
    in_file.close()
    file_to_upper(in_file.name, out_file.name)
    with open(out_file.name, 'r') as f:
        data = f.read()
        assert data == "TEST123\nTHETEST"
    os.unlink(in_file.name)
    os.unlink(out_file.name)

Continuous integration

Automated testing on local machines is useful, but you can do better with continuous integration (CI). In fact, CI is essential for projects involving multiple developers and various target platforms. CI consists in running tests whenever changes are committed. CI can also be used to automatically build documentation, check for code coverage, and more. GitHub Actions is a popular CI tool available within GitHub. CI is based on .yaml files, which specify the environment to run the script. You can build matrices to test across different environments (e.g. Linux, Windows and MacOS, with different versino of python or Julia). Jobs will be created that run our tests for each permutation of these.

An example CI.yaml file for Julia


name: Run tests
on:
push:
branches:
- master
- main
pull_request:
permissions:
actions: write
contents: read
jobs:
test:
runs-on: ${{ matrix.os }}
strategy:
matrix:
julia-version: [‘1.6’, ‘1’, ’nightly’]
julia-arch: [x64, x86]
os: [ubuntu-latest, windows-latest, macOS-latest]
exclude:
- os: macOS-latest
julia-arch: x86
steps:
  - uses: actions/checkout@v4
  - uses: julia-actions/setup-julia@v1
    with:
      version: ${{ matrix.julia-version }}
      arch: ${{ matrix.julia-arch }}
  - uses: julia-actions/cache@v1
  - uses: julia-actions/julia-buildpkg@v1
  - uses: julia-actions/julia-runtest@v1

An example CI.yaml file for Python

This action installs the conda environment called glacier-mass-balance, specified in the environment.yml file. It then runs pytest, supposing that you have a test/ folder where your functions are located. First try whether pytest works locally. Do not forget to have pytest in your dependencies.


name: Run tests
on: push

jobs:
  miniconda:
    name: Miniconda ${{ matrix.os }}
    runs-on: ${{ matrix.os }}
    strategy:
        matrix:
            os: ["ubuntu-latest"]
    steps:
      - uses: actions/checkout@v2
      - uses: conda-incubator/setup-miniconda@v2
        with:
          environment-file: environment.yml
          activate-environment: glacier-mass-balance
          auto-activate-base: false
      - name: Run pytest
        shell: bash -l {0}
        run: | 
          pytest

Cool tip

You can include a cool badge to show visually whether your tests are passing or failing, like so

You can get the code for this badge by going on your github repo, then Actions. Click on the test action, then on top right click on the ... and `Create status badge```.

Cool right?

Other types of tests

Docstring tests: Unit tests embedded in docstrings.
Integration tests: Test whether multiple functions work correctly together.
Regression tests: Ensure your code produces the same outputs as previous versions.

Resources

Take-home messages

Systematically implementing testing allows you to ensure the sanity of your code
The overhead cost of testing is usually well balanced by the reduced time spent downstream in identifying bugs

Open source navigation system for sailing

Fri, 26 May 2023 00:00:00 +0000

Back in the days, people used to orient themselves with paper maps and the stars or with a sextant. Unfortunately, we have lost this knowledge. It would now be difficult, at least for me, to live without a digital map and a GPS. In this blog post, I detail how to set up a handy navigation system for sailing, using a Raspberry Pi and OpenPlotter to transmit GPS and AIS signals over Wifi to the Navionics Boating app.

Choosing the Right Chart Maps

There are plenty of digital chart map options available for navigation, and we had to figure out which one would fit our need on the boat. After careful consideration, we narrowed down our choices to two alternatives: o-charts charts, to be used in combination with OpenCPN, an open source navigation software, or Navionics charts, to be used with the “Navionics Boating” application. Both had a similar pricing for what we wanted (charts for Germany, Denmark, Sweden, Norway, Shetland Islands, UK, Ireland and France): around 120-150EUR, with a slight advantage for Navionics. Pros for o-charts is that you can use them more than one year, although the update option is only valid for a year (I think, although I am not 100% sure). Navionics charts is only valid for a year, the period of the subscription. Pros for Navionics is that you can use your subscription on many devices (at least 5, I think), while you cannot use o-charts on iOS devices and on more than 2 devices. Because we wanted to have charts on our smartphones, we decided to go for Navionics.

The Importance of Accurate GPS and AIS

While our smartphones’ GPS serves us well in our daily lives, accurate positioning becomes critical when sailing. It ensures that we navigate safely, avoiding shallow waters and potential collisions. Additionally, during nighttime navigation, an instrument called AIS (Automatic Identification System) proves invaluable by providing information about nearby large ships.

In the following, I explain how I installed a server on our boat that transmits GPS and AIS to the “Navionics Boating” application our smartphone and tablets through Wifi. For this, I used a Raspberry Pi 4, OpenPlotter, and a GPS beacon and a radio antenna fixed on the outside of the boat and connected to the Raspberry.

Installing OpenPlotter on the Raspberry Pi

To get started, you need to install OpenPlotter, a Linux distribution designed for Raspberry Pi and that contains the essential software for navigation. I used the 64-bit OpenPlotter Starting image that contains an appropriate pre-built kernel. To install it, you’ll need a less than 32GB SD-card, to be formatted in FAT32. My problem was that the SD card I had had already been used on a Raspberry Pi, and as such contained an EXT4 partition. EXT4 partitions are used by Linux systems, but are not recognized by MacOS. This prevented me to format the card in FAT32. To allow formatting, I used the diskutil utility from MacOS.

First run

diskutil list

in the Terminal. This allows you to identify your SD card, in my case /dev/disk4. I had previously installed ext4fuse, not sure if this is a required step. To format the SD card, execute the command

sudo diskutil eraseDisk FAT32 RASPBERRY MBRFormat /dev/disk4

You can change RASPBERRY with any name you like best. More details of this command in this thread.

Now the SD card is ready to be used. Download the Raspberry Pi Imager to install the image on the SD card. You first need to unzip the image, then execute Raspberry Pi Imager, click “Choose OS” and click on “Use custom”. Locate the .img file, then choose the SD card in “Choose storage” and hit “Write”. The SD card is ready. Insert it in the Raspberry Pi and swith the power on. The system is going boot on the SD card and set up OpenPlotter. This took a relatively short amount of time.

Setting up OpenPlotter

I had an external monitor that I could use for the Raspberry Pi. I encountered a minor hurdle as OpenPlotter failed to identify it correctly, and did not properly display. I had to adjust the resolution of the screen by hitting the raspberry, then “Preferences” and “Screen configuration”. Check also the configuration of the monitor, that may be set to zoom in the visual signal.

Setting up the GPS

Configuring the GPS was a straightforward process that involved following this tutorial.

Setting up the AIS

Similar to configuring the GPS, we followed this video tutorial (in French, with translation available) to set up the AIS system. At first, I did not correctly calibrate the PPM offset, and although I did follow the rest of the procedure correctly, I had an “inactive” AIS process. I then redid the whole procedure, properly waiting for more than an hour to get the PPM initial guess correct, and with this value, I did manage to make it work.

Getting the signal on Navionics through OpenPlotter Access Point

To transmit the GPS and AIS data to the Navionics application, we established an access point using the Raspberry Pi. This allowed us to create a Wi-Fi network, enabling our devices to receive the signals. We followed this this video to set up the access point, which provided clear instructions for this setup.

I did struggle to switch off the access point to connect back the Raspberry Pi to a Wifi network with Internet in order to do some updates and download a few stuff. It turns out it is quite easy. Go to the Network app, and on the Network mode tab, select back for “AP” “non” instead of “xx:xx:..:xx on board”. Then hit the pen and sd card button, and reboot. Now you can connect back to a wifi network.

Setting up a SSH connection to transfer big files

I could not properly download the charts I needed on the Raspberry Pi because the wifi on the boat was too weak. So I decided to download it on my smartphone that I could bring closer to the hotspot, and then transfer the files to the Raspberry Pi. In order to facilitate the process, I installed a SSH connection between my laptop and the Pi, then transferred through Airdrop the charts from my phone to my laptop, and then from the laptop to the Pi with SSH and the scp command. To enable the SSH access, click on the Raspberry, then “Raspberry Pi Configuration”, the go to the “Interfaces” tab and enable SSH. From your laptop, connect to the Raspberry AP, go to the terminal and run

ssh pi@openplotter.local

The password by default is raspberry (this is indicated here). Then you can use the following command to transfer any folder to the Pi

scp -r path/to/folder/on/laptop pi@openplotter.local:/home/pi/path/you/want/to/drop/the/folder

Useful links

Inverse ecosystem modeling made easy with PiecewiseInference.jl

Sun, 26 Mar 2023 00:00:00 +0000

Mechanistic ecosystem models permit to quantiatively describe how population, species or communities grow, interact and evolve. Yet calibrating them to fit real-world data is a daunting task. That’s why I’m excited to introduce PiecewiseInference.jl, a new Julia package that provides a user-friendly and efficient framework for inverse ecosystem modeling. In this blog post, I will guide you through the main features of PiecewiseInference.jl and provide a step-by-step tutorial on how to use it with a three-compartment ecosystem model. Whether you’re a quantitative ecologist or a curious data scientist, I hope this post will encourage you to join the effort and use and develop inverse ecosystem modelling methods to improve our understanding and predictions of ecosystems.

Preliminary steps

This tutorial relies on three packages that I have authored but are (yet) not registered on the official Julia registry. Those are

PiecewiseInference,
EcoEvoModelZoo: a package which provides access to a collection of ecosystem models,
ParametricModels: a wrapper package to manipulate dynamical models. Specifically, ParametricModels avoids the hassle of specifying, at each time you want to simulate an ODE model, boring details such as the algorithm to solve it, the time span, etc…

To easily install them on your machine, you’ll have to add my personal registry by doing the following:

using Pkg; Pkg.Registry.add(RegistrySpec(url = "https://github.com/vboussange/VBoussangeRegistry.git"))

Once this is done, let’s import those together with other necessary Julia packages for this tutorial.

using Graphs
using EcoEvoModelZoo
using ParametricModels
using LinearAlgebra
using UnPack
using OrdinaryDiffEq
using Statistics
using SparseArrays
using ComponentArrays
using PythonPlot

We use Graphs to create a directed graph to represent the food web to be considered The OrdinaryDiffEq package provides tools for solving ordinary differential equations, while the LinearAlgebra package is used for linear algebraic computations. The UnPack package provides a convenient way to extract fields from structures, and the ComponentArrays package is used to store and manipulate the model parameters conveniently. Finally, the PythonCall package is used to interface with Python’s Matplotlib library for visualization.

Definition of the forward model

Defining hyperparameters for the forward simulation of the model.

Next, we define the algorithm used for solving the ODE model. We also define the absolute tolerance (abstol) and relative tolerance (reltol) for the solver. tspan is a tuple representing the time range we will simulate the system for, and tsteps is a vector representing the times we want to output the simulated data.

alg = BS3()
abstol = 1e-6
reltol = 1e-6
tspan = (0.0, 600)
tsteps = range(300, tspan[end], length=100)

300.0:3.0303030303030303:600.0

Defining the foodweb structure

We’ll define a 3-compartment ecosystem as presented in McCann et al. (1994). We will use SimpleEcosystemModel from EcoEvoModeZoo.jl, which requires as input a foodweb structure. Let’s use a DiGraph to represent it.

N = 3 # number of compartment

foodweb = DiGraph(N)
add_edge!(foodweb, 2 => 1) # C to R
add_edge!(foodweb, 3 => 2) # P to C

true

The N variable specifies the number of compartments in the model. The add_edge! function is used to add edges to the graph, specifying the flow of resources between compartments.

For fun, let’s just plot the foodweb. Here we use the PythonCall and PythonPlot packages to visualize the food web as a directed graph using networkx and numpy. We create a color list for the different species, and then create a directed graph g_nx with networkx using the adjacency matrix of the food web. We also specify the position of each node in the graph, and use nx.draw to draw the graph with

using PythonCall
nx = pyimport("networkx")
np = pyimport("numpy")
species_colors = ["tab:red", "tab:green", "tab:blue"]

g_nx = nx.DiGraph(np.array(adjacency_matrix(foodweb)))
pos = Dict(0 => [0, 0], 1 => [0.2, 1], 2 => [0, 2])
labs = Dict(0 => "Resource", 1 => "Consumer", 2 => "Prey")

fig, ax = subplots(1)
nx.draw(g_nx, pos, ax=ax, node_color=species_colors, node_size=1000, labels=labs)
display(fig)

Defining the ecosystem model

Now that we have defined the foodweb structure, we can build the ecosystem model, which will be a SimpleEcosystemModel from EcoEvoModelZoo.

The next several functions are required by SimpleEcosystemModel and define the specific dynamics of the model. The intinsic_growth_rate function specifies the intrinsic growth rate of each compartment, while the carrying_capacity function specifies the carrying capacity of each compartment. The competition function specifies the competition between and within compartments, while the resource_conversion_efficiency function specifies the efficiency with which resources are converted into consumer biomass. The feeding function specifies the feeding interactions between compartments.

intinsic_growth_rate(p, t) = p.r

function carrying_capacity(p, t)
    @unpack K₁₁ = p
    K = vcat(K₁₁, ones(N - 1))
    return K
end

function competition(u, p, t)
    @unpack A₁₁ = p
    A = spdiagm(vcat(A₁₁, 0, 0))
    return A * u
end

resource_conversion_efficiency(p, t) = ones(N)

resource_conversion_efficiency (generic function with 1 method)

To define the feeding processes, we use adjacency_matrix to get the adjacency matrix of the food web. We then use findnz from SparseArrays to get the row and column indices of the non-zero entries in the adjacency matrix, which we store in I and J. Those are then used to generate sparse matrices required for defining the functional responses of each species considered. The sparse matrices’ non-zero coefficients are the model parameters to be fitted.

using SparseArrays
W = adjacency_matrix(foodweb)
I, J, _ = findnz(W)

([2, 3], [1, 2], [1, 1])

function feeding(u, p, t)
    @unpack H₂₁, H₃₂, q₂₁, q₃₂ = p

    # handling time
    H = sparse(I, J, vcat(H₂₁, H₃₂), N, N)

    # attack rates
    q = sparse(I, J, vcat(q₂₁, q₃₂), N, N)

    return q .* W ./ (one(eltype(u)) .+ q .* H .* (W * u))
end

feeding (generic function with 1 method)

We are done defining the ecological processes.

Defining the ecosystem model parameters for generating a dataset

The parameters for the ecosystem model are defined using a ComponentArray. The u0_true variable specifies the initial conditions for the simulation. The ModelParams type from the ParametricModels package is used to specify the model parameters and simulation settings. Finally, the SimpleEcosystemModel type from the EcoEvoModelZoo package is used to define the ecosystem model.

p_true = ComponentArray(H₂₁=[1.24],
                        H₃₂=[2.5],
                        q₂₁=[4.98],
                        q₃₂=[0.8],
                        r=[1.0, -0.4, -0.08],
                        K₁₁=[1.0],
                        A₁₁=[1.0])

u0_true = [0.77, 0.060, 0.945]

mp = ModelParams(; p=p_true,
    tspan,
    u0=u0_true,
    alg,
    reltol,
    abstol,
    saveat=tsteps,
    verbose=false, # suppresses warnings for maxiters
    maxiters=50_000
)
model = SimpleEcosystemModel(; mp, intinsic_growth_rate,
    carrying_capacity,
    competition,
    resource_conversion_efficiency,
    feeding)

`Model` SimpleEcosystemModel

Let’s run the model to generate a dataset! There is nothing more simple than that. Let’s also plot it, to get a sense of what it looks like.

data = simulate(model, u0=u0_true) |> Array

# plotting
using PythonPlot;
function plot_time_series(data)
    fig, ax = subplots()
    for i in 1:N
        ax.plot(data[i, :], label="Species $i", color = species_colors[i])
    end
    # ax.set_yscale("log")
    ax.set_ylabel("Species abundance")
    ax.set_xlabel("Time (days)")
    fig.set_facecolor("None")
    ax.set_facecolor("None")
    fig.legend()
    return fig
end

display(plot_time_series(data))

Let’s add a bit of noise to the data to simulate experimental errors. We proceed by adding log normally distributed noise, so that abundance are always positive (negative abundance would not make sense, but could happen when adding normally distributed noise!).

data = data .* exp.(0.1 * randn(size(data)))

display(plot_time_series(data))

Inversion with `PiecewiseInference.jl`

Now that we have set up our model and generated some data, we can proceed with the inverse modelling using PiecewiseInference.jl.

PiecewiseInference.jl allows to perform inversion based on a segmentation method that partitions the data into short time series (segments), each treated independently and matched against simulations of the model considered. The segmentation approach helps to avoid the ill-behaved loss functions that arise from the strong nonlinearities of ecosystem models, when formulation the inference problem. Note that during the inversion, not only the parameters are inferred, but also the initial conditions, which are necessary to simulate the ODE model.

Definition of the `InferenceProblem`

We first import the packages required for the inversion. PiecewiseInference is the main package used, but we also need OptimizationFlux for the Adam optimizer, and SciMLSensitivity to define the sensitivity method used to differentiate the forward model.

using PiecewiseInference
using OptimizationFlux
using SciMLSensitivity

To initialize the inversion, we set the initial values for the parameters in p_init to those of p_true but modify the H₂₁ parameter.

p_init = p_true
p_init.H₂₁ .= 2.0 #

1-element view(::Vector{Float64}, 1:1) with eltype Float64:
 2.0

Next, we define a loss function loss_likelihood that compares the observed data with the predicted data. Here, we use a simple mean-squared error loss function while log transforming the abundance, since the noise is log-normally distributed.

loss_likelihood(data, pred, rg) = sum((log.(data) .- log.(pred)) .^ 2)# loss_fn_lognormal_distrib(data, pred, noise_distrib)

loss_likelihood (generic function with 1 method)

We then define the InferenceProblem, which contains the forward model, the initial parameter values, and the loss function.

infprob = InferenceProblem(model, p_init; loss_likelihood);

It is also handy to use a callback function, that will be called after each iteration of the optimization routine, for visualizing the progress of the inference. Here, we use it to track the loss value and plot the data against the model predictions.

info_per_its = 50
include("cb.jl") # defines the `plotting_fit` function
function callback(p_trained, losses, pred, ranges)
    if length(losses) % info_per_its == 0
        plotting_fit(losses, pred, ranges, data, tsteps)
    end
end

callback (generic function with 1 method)

`piecewise_MLE` hyperparameters

To use piecewise_MLE, the main function of PiecewiseInference to estimate the parameters that fit the observed data, we need to decide on two critical hyperparameters

group_size: the number of data points that define an interval, or segment. This number is usually small, but should be decided upon the dynamics of the model: to more nonlinear is the model, the lower group_size should be. We set it here to 11
batch_size: the number of intervals, or segments, to consider on a single epoch. The higher the batch_size, the more computationally expensive a single iteration of piecewise_MLE, but the faster the convergence. Here, we set it to 5, but could increase it to 10, which is the total number of segments that we have.

Another critical parameter to be decided upon is the automatic differentiation backend used to differentiate the ODE model. Two are supported, Optimization.AutoForwardDiff() and Optimization.Autozygote(). Simply put, Optimization.AutoForwardDiff() is used for forward mode sensitivity analysis, while Optimization.Autozygote() is used for backward mode sensitivity analysis. For more information on those, please refer to the documentation of Optimization.jl.

Other parameters required by piecewise_MLE are

optimizers specifies the optimization algorithm to be used for each batch. We use the Adam optimizer, which is the go-to optimizer to train deep learning models. It has a learning rate parameter that controls the step size at each iteration. We have chosen a value of 1e-2 because it provides good convergence without causing numerical instability,
epochs specifies the number of epochs to be used for each batch. We chose a value of 500 because it is sufficient to achieve good convergence,
info_per_its specifies after how many iterations the callback function should be called
verbose_loss prints the value of the loss function during training,

@time res = piecewise_MLE(infprob;
                        adtype = Optimization.AutoZygote(),
                        group_size = 11,
                        batchsizes = [5],
                        data = data,
                        tsteps = tsteps,
                        optimizers = [Adam(1e-2)],
                        epochs = [500],
                        verbose_loss = true,
                        info_per_its = info_per_its,
                        multi_threading = false,
                        cb = callback)

piecewise_MLE with 100 points and 10 groups.
Current loss after 50 iterations: 36.745952018526495
Current loss after 100 iterations: 15.064711239454626
Current loss after 150 iterations: 9.993029255013324
Current loss after 200 iterations: 7.994491307947515
Current loss after 250 iterations: 6.500818892986831
Current loss after 300 iterations: 5.3892647156988565
Current loss after 350 iterations: 3.0351181646280514
Current loss after 400 iterations: 2.674445730720996
Current loss after 450 iterations: 3.1591980829795676
Current loss after 500 iterations: 2.4343376293865995
157.765049 seconds (1.70 G allocations: 154.827 GiB, 10.16% gc time, 31.31%
 compilation time: 1% of which was recompilation)
`InferenceResult` with model SimpleEcosystemModel

Finally, we can examine the results of the inversion. We can look at the final parameters, and the initial conditions inferred for each segement:

# Some more code
p_trained = res.p_trained
u0s_trained = res.u0s_trained

function print_param_values(p_trained, p_true)
    for k in keys(p_trained)
        println(string(k))
        println("trained value = "); display(p_trained[k])
        println("true value ="); display(p_true[k])
    end
end

print_param_values(p_trained, p_true)

H₂₁
trained value = 
1-element Vector{Float64}:
 1.4786844814887716
true value =
1-element Vector{Float64}:
 2.0
H₃₂
trained value = 
1-element Vector{Float64}:
 1.891238277791975
true value =
1-element Vector{Float64}:
 2.5
q₂₁
trained value = 
1-element Vector{Float64}:
 4.550896291686214
true value =
1-element Vector{Float64}:
 4.98
q₃₂
trained value = 
1-element Vector{Float64}:
 0.7250599871665505
true value =
1-element Vector{Float64}:
 0.8
r
trained value = 
3-element Vector{Float64}:
  0.8705446490535288
 -0.30124597815843823
 -0.08241879418666838
true value =
3-element Vector{Float64}:
  1.0
 -0.4
 -0.08
K₁₁
trained value = 
1-element Vector{Float64}:
 1.0397189294700315
true value =
1-element Vector{Float64}:
 1.0
A₁₁
trained value = 
1-element Vector{Float64}:
 0.972947353012839
true value =
1-element Vector{Float64}:
 1.0

Your turn to play!

You can try to change e.g. the batch_sizes and the group_size. How do those parameters influence the quality of the inversion?

Conclusion

PiecewiseInference.jl provides an efficient and flexible way to perform inference on complex ecological models, making use of automatic differentiation and optimizers traditionally used in Machine Learning. The segmentation method implemented in PiecewiseInference.jl regularizes the inference problem and enables inverse modelling of complex dynamical systems, for which standard methods would otherwise fail.

Furthermore, PiecewiseInference.jl together with EcoEvoModelZoo.jl offer a powerful toolkit for ecologists and evolutionary biologists to benchmark and validate models against data. The combination of theoretical modelling and data can provide new insights into complex ecological systems, helping us to better understand and predict the dynamics of biodiversity.

We invite users to explore these packages and contribute to their development, by adding new models to the EcoEvoModelZoo.jl and improve the features of PiecewiseInference.jl. With these tools, we can continue to push the boundaries of ecological modelling and make important strides towards a more sustainable future.

Appendix

You can find the corresponding tutorial as a .jmd file at https://github.com/vboussange/MyTutorials. Please contact me, if you have found a mistake, or if you have any comment or suggestion on how to improve this tutorial.

Create and deploy your Hugo website

Sun, 27 Mar 2022 17:40:15 +0200

This website is based on the wowchemy template that relies on Hugo, a fast framework for building static websites. Although Hugo has many advantages over its brother Jekyll, a Hugo website is not as easy to deploy on GitHub Pages, the free service offered by GitHub to host a personal website. If you want to build your Hugo website and deploy it easily, here is the recipe.

Build your Hugo website

Fork the github repo of the wowchemy template.
Rename the repo as your-username.github.io
Clone the repo and customise the template following your own taste, following the wowchemy tutorial.
You can locally build the website with the command hugo server and access it at the adress indicated in the the text printed after the execution of the command.
Once you are satified with your local website, it is time to publish it! I found out that the easiest way to do so is to create a GitHub Action.

Deploy automatically a Hugo website on GitHub pages

Here I detail how to set up a workflow that will build your website and publish it at each new commit. The idea is to set up a GitHub Action, which job will be to

Clone the master from your repo
Build the Hugo website
Create / clone a gh-pages branch
Copy the static files generated in 2. to the gh-pages repo
Push those changes to the gh-pages.

To do so, first create a file .github/workflows/gh-pages.yml and add the following content, replacing your-username by your … username.

name: Build and Deploy

on:
  push:
    branches:
      - master

jobs:
  build:

    runs-on: ubuntu-latest

    steps:
    - name: Checkout master
      uses: actions/checkout@v1
      with:
        submodules: true

    - name: Hugo Deploy GitHub Pages
      uses: benmatselby/hugo-deploy-gh-pages@master
      env:
        GO_VERSION: 1.17
        HUGO_VERSION: 0.95.0
        HUGO_EXTENDED: true
        TARGET_REPO: your-username/your-username.github.io
        TARGET_BRANCH: gh-pages
        TOKEN: ${{ secrets.TOKEN_HUGO_DEPLOY }}
        CNAME: vboussange.github.io

You then need to generate a personnal access token. Here is a tutorial to do so. Tick the box “repo”, to grant full control of private repo. More details on why you need to do so are given in Jame Wright post (see below). Copy the generated code, and go in the settings of your “your-username.github.io” repo. There, create a secret, call it TOKEN_HUGO_DEPLOY and paste the previously generated token.

You are almost all set! Make your first commit. Wait for the action to execute. Once you see the green badge symbolising the success of the deployment Action, go to the Settings of your repo, and in “Pages” in the left side bar, under “Source” select the branch gh-pages. After a few minutes, your website should be available at https://your-username.github.io/.

Enjoy!

This post was greatly inspired by James Wright blog post on the same topic, although his Github Action was not quite working for me.

Scientific software | Victor Boussange

AMJAX

jaxscape

A course on reproducible research, data pipelines, and scientific computing

Practical introduction to Julia for biodiversity research

HybridDynamicModels.jl

yDiv workshop funding

Course On Reproducible Research, Data Pipelines, and Scientific Computing

WSL Biodiversity Center Innovative Workshop Grant

EcoEvoModelZoo.jl

EvoId.jl

Developing an algebraic multigrid solver in JAX

A multi-language overview on how to document your research project code

Content

Style guides

Comments

Literal documentation

README

API documentation / doc strings

Type annotations

Consider raising errors

Tutorials

Accessing documentation

Doc testing

Useful packages to help you write and lint your documentation

More resources

Take home messages

A multi-language overview on how to handle dependencies within a research project

Content

Some definitions

What is a dependency?

What is a package manager?

What is a virtual environment?

Package managers

Multilanguage overview

conda

renv

Pkg

Environment files

Julia

Python

R

Working with interactive environments

Caveats of virtual environments

Advanced topic: package development

Take-home messages

A multi-language overview on how to organise your research project code and documents

Content

Project folder structures

code/ structure

Turning your code/ into a “package”

Wrapping up

Take-home messages

A multi-language overview on how to test your research project code

Content

Unit testing

Lightweight formal tests with assert

Python

Julia

Testing with a test suite

Python

Julia

R

Testing non-pure functions and classes

Python

Continuous integration

Cool tip

Other types of tests

Resources

Take-home messages

Open source navigation system for sailing

Choosing the Right Chart Maps

The Importance of Accurate GPS and AIS

Installing OpenPlotter on the Raspberry Pi

Setting up OpenPlotter

Setting up the GPS

Setting up the AIS

Getting the signal on Navionics through OpenPlotter Access Point

Setting up a SSH connection to transfer big files

Useful links

`conda`

`renv`

`Pkg`

`code/` structure

Turning your `code/` into a “package”

Lightweight formal tests with `assert`

Inversion with `PiecewiseInference.jl`

Definition of the `InferenceProblem`

`piecewise_MLE` hyperparameters