Material for the AGU2018 workshop "Best practices for modern open-source research codes"
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
LICENSE
README.md
example-data-analysis.ipynb

README.md

Best practices for modern open-source research codes

Material for the workshop at the AGU 2018 Fall Meeting.

Conveners: Leonardo Uieda, Lindsey Heagy, Lion Krischer, Florian M. Wagner

Info
Location Grand Hyatt / Room: Penn Quarter
Time Wednesday, 12 December 2018 / 13:40 - 18:00
Workshop ID WS24
Shared notes Google Docs

Description

Modern science increasingly relies on code, ranging from small scripts to workflows with many interacting parts. Reproducibility and extension of studies employing these codes require that they are accessible. The open-source community has established modern best-practices for making software available, usable, and maintainable. In this workshop, we will demonstrate a workflow for publishing research code following these best-practices. We will cover open-source licenses, version control, automated testing, documentation, and continuous integration. The workshop will be hands-on: participants will work to set up a project using sample code provided by the instructors. By the end, participants will have the knowledge needed to continue learning independently and apply these practices to their own research code. These resources can be applied to any programming language or scientific discipline.

Learning Objectives

Our aim with this workshop is for participants to:

  1. Gain awareness of tools available to researchers within the open-source ecosystem including Jupyter, git, ReadTheDocs, continuous integration services (for testing), etc
  2. Learn modern best-practices for structuring a repository for research software that promotes accessibility, reusability, and reproducibility
  3. Learn about the tools available for testing, publishing documentation, and versioning that can be immediately applied to their own codes

Tentative Agenda

During the workshop, we'll introduce these topics by working through an example. The goal is to convert a notebook (or script) that does some data analysis into a Python library that is tested, documented, and can be reused. The final version of the library and a history of each step in the conversion process can be found at https://github.com/opengeophysics/2018-agu-oss-example-repo

Duration (min) Topic Tools
15 Introduce the motivations and problems that the workshop will address Example data analysis in Jupyter
30 Describe the example we will working through and provide an overview of the Jupyter notebook Jupyter notebook
45 Overview of version control with git and setting up an online repository GitHub, Slides
45 How to setup a small Python library (though the example is in python, participants are encouraged to use their own research code in whichever language they prefer) Python packaging guide
15 Discussion on choosing an open-source license Choose a license, OSI Licenses
15 Including a Code of Conduct and Contributing Guidelines Contributor Covenant
30 How to write automated tests in Python Pytest
30 Setup continuous integration services to check that the code is tested on every update TravisCI
30 Write and publish documentation on ReadTheDocs, a free hosting service for open source software projects ReadTheDocs
15 Overview of other resources available within the open source community

Before the workshop

If you would like to follow along interactively during the course, please do the following before the course starts:

  • Download and install Anaconda. Use the latest version of Python 3 and be sure to check the box that says "Add Anaconda to my PATH environment variable" if on Windows.

AnacondaPath

After the workshop

Since the time allocated for the workshop does not allow to cover scientific software development in its entirety, we provide links to some alternatives and guides to extend and deepen some of the taught concepts.

Further reading

Alternatives to the tools presented

  • Version control

    • GitLab: Version control for with private repositories and for your own server
  • Continous Integration

  • Documentation

    • MkDocs: Fast and simple project documentation using Markdown.

Recording

recording-AGU

Workshop - AGU 2018

License

Creative Commons License
This work is licensed under a Creative Commons Attribution 4.0 International License.