From fd7e7cd354960cfe342cd529bc5bdfeff46ec8bb Mon Sep 17 00:00:00 2001 From: Rantaharju Jarno Date: Tue, 27 Feb 2024 13:34:20 +0200 Subject: [PATCH] Add git to first section --- content/index.rst | 60 +++++++++++++++++++++++++--------- content/organizing-projects.md | 23 ++++++++++++- 2 files changed, 66 insertions(+), 17 deletions(-) diff --git a/content/index.rst b/content/index.rst index 1af87bd..2ea94e5 100644 --- a/content/index.rst +++ b/content/index.rst @@ -3,31 +3,60 @@ Reproducible research - Preparing code to be usable by you and others in the future =================================================================================== -Have you ever spent days **trying to repeat the results from few weeks or months -ago**? Or you have to do paper revisions, but you just can't get the results to -match up? It's unpleasant for both you and science. + +.. admonition:: Notes for the instructor: + + This course is for new researchers, bachelors and masters students, summer + workers and so on. The do not have a lot of experience with programming and + will not write long programs to start with. Emphasize reproducability of + workflows and saving your work (instead of just running commands and getting + results). + + Reproducability: + - record computational steps and dependencies + - keep data as raw as possible (in case of FIONA, raw data cannot be exported) + - keep data and code in the same place. + - write a workflow to reproduce the entrie paper + + Quick timings: + - intro and motivation: 10 minutes + - organizing-projects + git demo: 15 minutes + - workflow-management: 15 minutes + - dependencies and publishing: 10 minutes + - exercises and discussion: 10 minutes + + 10 + 15 + 15 + 10 + 10 = 60 minutes + +Have you ever **lost hours of work** when your computer decided to update itself? +Or a program crashed when you clicked save? Did you maybe delete a file by mistake? + +In this section we will look at ways of saving your work for yourself and saving +effort by making computational steps easy to repeat, share and modify. Making you +research project reproducable increase the quality of your work, but the main +motivation should be to make your life easier in the long run. In this lesson we will explore different methods and tools for better reproducibility in research software and data. We will demonstrate how version -control, workflows, containers, and package managers can be used to **record -reproducible environments and computational steps** for our future selves. +control, workflows, and package managers can be used to **record +reproducible environments and computational steps** for our future selves +and share those with other researchers. .. admonition:: Learning outcomes By the end of this lesson, learners should: - be able to apply well organized directory structure for their project - - remember the FAIR principles + - be able to document and reproduce computational steps - understand that code can have dependencies, and know how to document them - - if a computational studies contains several steps, be able to document them - - know about use cases for containers - - knowing the pros and cons of manual documentation vs. scripted automation vs. workflow management + - if a computational study contains several steps, be able to document them .. prereq:: - You need to install + In examples and demonstrations, we use `Git, Python, and Snakemake `__. + These are not required to follow the lesson, but trying them yourself is very + useful .. toctree:: @@ -39,13 +68,12 @@ reproducible environments and computational steps** for our future selves. organizing-projects.md workflow-management.md dependencies.md - environments.md where-to-go.md .. toctree:: :maxdepth: 1 - :caption: Reference + :caption: For Reference exercises guide @@ -53,8 +81,8 @@ reproducible environments and computational steps** for our future selves. .. toctree:: :maxdepth: 1 - :caption: About + :caption: See Also - All lessons - CodeRefinery - Reusing + Codefinery Lessons + This lesson is based on the `Reproducibility lesson `__ + CodeRefinery Organization diff --git a/content/organizing-projects.md b/content/organizing-projects.md index 9b8e04a..d12fa83 100644 --- a/content/organizing-projects.md +++ b/content/organizing-projects.md @@ -43,6 +43,28 @@ project_name/ ``` --- +## Tracking files with git + +### Demonstration with graphical user interface + +````{challenge} Demonstration +We use a simple word-count repository in demonstrations and exercises +(). We should clone the +repository already to prepare to work on it. + +On VSCode (many other interfaces exist and are just as good) + - Open command palette and type clone + - paste the URL of the repository to clone + - use the file dialog to find a place for it + - Create a new file and make a change to an existing one. + - Add them to the repository and push online. + - See the changes online. +```` + +* Check the [Git-intro lesson](https://coderefinery.github.io/git-intro/) for a lot more details. + + + ## Tracking source code, data, and results - All code is version controlled and goes in the `src/` or `source/` directory @@ -55,7 +77,6 @@ project_name/ ```console $ git tag -a thesis-submitted -m "this is the submitted version of my thesis" ``` -* Check the [Git-intro lesson](https://coderefinery.github.io/git-intro/) for a reminder. ---