Skip to content

Commit a4e97c4

Browse files
martijnkerslootmartijnkersloot
authored
Merge pull request #136 from AmsterdamUMC/FAIR-Software
FAIR Software Lesson Plans
2 parents 498944d + 1ef6f63 commit a4e97c4

File tree

10 files changed

+410
-34
lines changed

10 files changed

+410
-34
lines changed

‎_data/contributors.yaml‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -204,3 +204,15 @@
204204
firstName: "Ana"
205205
lastName: "Konrad"
206206
git: "konradana"
207+
208+
- id: "0000-0002-1322-1553"
209+
orcid: "0000-0002-1322-1553"
210+
firstName: "Samuel"
211+
lastName: "Langton"
212+
git: "langtonhugh"
213+
214+
- id: "0000-0001-9334-7190"
215+
orcid: "0000-0001-9334-7190"
216+
firstName: "Thomas"
217+
lastName: "Pronk"
218+
git: "tpronk"

‎_lesson-plans/fair-software/topics/1-Defining-research-software.md‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
---
2+
number: 6.1
3+
title: Defining research software
4+
status: in_progress
5+
layout: lesson-plan
6+
authors:
7+
- "0000-0001-9334-7190"
8+
- "0000-0002-1322-1553"
9+
10+
reviewers:
11+
12+
fair_elements:
13+
- F
14+
- A
15+
- I
16+
- R
17+
18+
audience:
19+
- Data stewards
20+
- Software stewards
21+
- Research software consultants
22+
23+
learning_outcomes:
24+
1:
25+
outcome: Provide a concise definition of research software.
26+
2:
27+
outcome: Differentiate between research software and 'software in research'.
28+
3:
29+
outcome: Provide examples of research software (e.g., a GitHub repository, a file on your local machine).
30+
4:
31+
outcome: Understand the challenges facing the development of research software in the current academic landscape.
32+
33+
prerequisites:
34+
- Have basic knowledge of the FAIR Principles.
35+
36+
---
37+
38+
## Topic, definition and scope
39+
40+
* Differentiating research software and software in research
41+
* Where research software lies in the research cycle
42+
* Identifying the role of research software in research outputs (e.g., publications)
43+
* The challenges facing research software
44+
* Ways in which reseach software can be credited
45+
46+
47+
---
48+
49+
## Exercises
50+
51+
* Identify an example of software in research
52+
* Identify an example of research software
53+
* What were some of the challenges you faced in developing research software?
54+
* How might researchers get 'credit' for developing research software?
55+
* How can researchers give credit to others when using research software?
56+
57+
---
58+
59+
## Recommended reading
60+
61+
* Defining Research Software: a controversial discussion [(Gruenpeter et al., 2021)](https://doi.org/10.5281/zenodo.5504015)

‎_lesson-plans/fair-software/topics/1-FAIR-software.md‎

Lines changed: 0 additions & 34 deletions
This file was deleted.

‎_lesson-plans/fair-software/topics/2-FAIR-software.md‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
---
2+
number: 6.2
3+
title: FAIR Software
4+
status: in_progress
5+
layout: lesson-plan
6+
authors:
7+
- "0000-0001-9334-7190"
8+
- "0000-0002-1322-1553"
9+
10+
reviewers:
11+
12+
fair_elements:
13+
- F
14+
- A
15+
- I
16+
- R
17+
18+
audience:
19+
- Data stewards
20+
- Software stewards
21+
- Research software consultants
22+
23+
learning_outcomes:
24+
1:
25+
outcome: Map FAIR principles to research software.
26+
2:
27+
outcome: Understand the benefits of ensuring research software is FAIR.
28+
29+
---
30+
31+
## Topic, definition and scope
32+
33+
* Re-cap FAIR generics
34+
* Why apply FAIR to research software?
35+
* Reproducibility
36+
* Replication
37+
* Scientific progress
38+
* Re-use
39+
* Saving time
40+
41+
---
42+
43+
## Exercises
44+
45+
* Try to reproduce the analysis of a well-known publication in your field. How challenging/easy was it to undertake in terms of FAIR principles?
46+
* Provide a brief definition for each FAIR principle. Match each principle to an aspect of research software that it could improve.
47+
48+
---
49+
50+
## Recommended reading
51+
52+
* Introducing the FAIR Principles for research software [(Barker et al., 2022)](https://doi.org/10.1038/s41597-022-01710-x)
53+
* The FAIR for Research Software Principles after two years: an adoption update [(Barker et al., 2024)](https://www.researchsoft.org/blog/2024-03/)

‎_lesson-plans/fair-software/topics/3-Findable-software.md‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
---
2+
number: 6.3
3+
title: Findable Software
4+
status: in_progress
5+
layout: lesson-plan
6+
authors:
7+
- "0000-0001-9334-7190"
8+
- "0000-0002-1322-1553"
9+
10+
reviewers:
11+
12+
fair_elements:
13+
- F
14+
15+
audience:
16+
- Data stewards
17+
- Software stewards
18+
- Research software consultants
19+
20+
learning_outcomes:
21+
1:
22+
outcome: Name and navigate through a software directory, such as [RSD](https://research-software-directory.org/).
23+
2:
24+
outcome: Understand why metadata can help make research software more findable.
25+
3:
26+
outcome: List the important components of a README file.
27+
28+
---
29+
30+
## Topic, definition and scope
31+
32+
* Software directories
33+
* Personal identifiers
34+
* Metadata
35+
* Descriptive information (e.g., README)
36+
37+
---
38+
39+
## Exercises
40+
41+
* Discuss what a good README must, should, and could contain
42+
* Which identifiers, registries, catalogs are most authorative in your field?
43+
44+
---
45+
46+
## Recommended reading
47+
48+
* Nine best practices for research software registries and repositories [(Gajiro et at., 2022)](https://doi.org/10.7717/peerj-cs.1023)

‎_lesson-plans/fair-software/topics/4-Accessible-software.md‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
---
2+
number: 6.4
3+
title: Accessible Software
4+
status: in_progress
5+
layout: lesson-plan
6+
authors:
7+
- "0000-0001-9334-7190"
8+
- "0000-0002-1322-1553"
9+
10+
reviewers:
11+
12+
fair_elements:
13+
- A
14+
15+
audience:
16+
- Data stewards
17+
- Software stewards
18+
- Research software consultants
19+
20+
learning_outcomes:
21+
1:
22+
outcome: Understand the importance of licences and the implications of not having one.
23+
2:
24+
outcome: Know how to create a CFF file.
25+
3:
26+
outcome: List some the pros and cons of popular software repositories, such as GitHub and GitLab.
27+
28+
---
29+
30+
## Topic, definition and scope
31+
32+
* Licencing
33+
* Software repositories
34+
* Comparing different software repositories
35+
36+
---
37+
38+
## Exercises
39+
40+
* Identify a research software
41+
* Does it have a licence? If so, which one?
42+
* List some advantages of using GitHub and GitLab, respectively
43+
44+
---
45+
46+
## Recommended reading
47+
48+
* TU Delft guidelines on research software [(Akhmerov et at., 2021)](https://doi.org/10.5281/zenodo.4629634)

‎_lesson-plans/fair-software/topics/5-Interoperable-software.md‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
---
2+
number: 6.5
3+
title: Interoperable Software
4+
status: in_progress
5+
layout: lesson-plan
6+
authors:
7+
- "0000-0001-9334-7190"
8+
- "0000-0002-1322-1553"
9+
10+
reviewers:
11+
12+
fair_elements:
13+
- I
14+
15+
audience:
16+
- Data stewards
17+
- Software stewards
18+
- Research software consultants
19+
20+
learning_outcomes:
21+
1:
22+
outcome: Be able to define vendor locking and why it is important to FAIR research software.
23+
2:
24+
outcome: Understand why the programming language itself can determine interoperability.
25+
3:
26+
outcome: Critique common data formats (e.g., csv) in the context of research software.
27+
28+
---
29+
30+
## Topic, definition and scope
31+
32+
* Open-source programming languages
33+
* Input/output data
34+
* Instructional documentation
35+
* Vendor locking
36+
37+
---
38+
39+
## Exercises
40+
41+
* What programming languages do your research colleagues typically use? Are they open?
42+
* What data formats are recommended within your organisation? Do they align with DANS?
43+
* How might a research software be 'locked' (untentionally or unintentionally) by the developer?
44+
45+
---
46+
47+
## Recommended reading
48+
49+
* Dealing with software collapse [(Hinsen, 2019)](https://doi.org/10.1109/MCSE.2019.2900945)

‎_lesson-plans/fair-software/topics/6-Reusable-software.md‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
---
2+
number: 6.6
3+
title: Reusable Software
4+
status: in_progress
5+
layout: lesson-plan
6+
authors:
7+
- "0000-0001-9334-7190"
8+
- "0000-0002-1322-1553"
9+
10+
reviewers:
11+
12+
fair_elements:
13+
- R
14+
15+
audience:
16+
- Data stewards
17+
- Software stewards
18+
- Research software consultants
19+
20+
learning_outcomes:
21+
1:
22+
outcome: Understand the benefits of virtual environments for reusability.
23+
2:
24+
outcome: Have sufficient understanding of modular scripting to identify it within a repository and translate a single (large) script into multiple (smaller) modules.
25+
3:
26+
outcome: Define version control and have a basic understanding of how git operates.
27+
4:
28+
outcome: Be able to critically assess whether automated testing might be worth implementing for a research software project.
29+
30+
---
31+
32+
## Topic, definition and scope
33+
34+
* Licences
35+
* Public software repositories
36+
* Documentation
37+
* Modular scripting
38+
* Version control
39+
* Virtual environments
40+
* (Automated) testing
41+
42+
43+
---
44+
45+
## Exercises
46+
47+
* How might a virtual environment (e.g., venv, renv) enhance re-usability?
48+
* What factors might determine whether you create automated tests for research software?
49+
50+
---
51+
52+
## Recommended reading
53+
54+
* A large-scale study on research code quality and execution [(Trisovic et al., 2022)](https://doi.org/10.1038/s41597-022-01143-6)

0 commit comments

Comments
 (0)