forked from thefaylab/lab-manual
-
Notifications
You must be signed in to change notification settings - Fork 2
/
Copy path09-Realising-FAIR-Documentation.qmd
105 lines (68 loc) · 6.76 KB
/
09-Realising-FAIR-Documentation.qmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
# Realising FAIR: Data Documentation {#realisingFAIR2}
*Estimated time: 60 minutes*
In this module, we will focus on the realisation of FAIR data. We will explore some best practices and tools that can facilitate the implementation of the FAIR principles. At the end of this module you should be able to:
- Recognise the relevance of documentation and be familiar with diverse tools to document data
- Identify relevant tools to advance towards FAIR data
::: callout-important
## Activities
- Watch the presentation about Data Documentation tools
- Check out the relevant optional assignments and tools
:::
## Documentation tools
Now that you know more about how to organise your data and name your files, we can talk about documentation. Documentation is vital to making your work understandable, which is, in turn, necessary for your work to be reusable. Documentation is important not only for data, but for your projects in general, including the code you write. Your documentation should provide context for your project and its data and should, for example, provide information about the data collection, structure, and ownership.
In the next video we will talk about different methods and tools you can use to document projects, datasets, and code. We will also briefly talk about metadata.
- [04-2_Module-4_Video_Presentation_DataDocumentation](https://surfdrive.surf.nl/files/index.php/s/Y1ylaZYL1R3VPbR) (*12 minutes*, audio will play automatically in full presentation mode)
- [Read more about README files](https://estherplomp.github.io/TNW-OS-support/posts/readme/)
## Assignment: Create a ReadMe file (optional)
*Estimated time: 15 minutes*
1. Download the [Cornell template for a ReadMe file](https://cornell.app.box.com/v/ReadmeTemplate).
2. Adapt and start filling in the template to describe a dataset of your project. You are allowed to delete and add new fields. Not all of the questions in the template will be relevant to all of the data you work with.
3. If you are unsure about the meaning of a component of the ReadMe file, go to: [Guide to writing "ReadMe" style metadata - Cornell University](https://data.research.cornell.edu/content/readme#best_practices)
- For example, an ORCID is a persistent/unique identifier for you as a Researcher. You can have a look at [Esther's ORCID](https://orcid.org/0000-0003-3625-1357) to see what this profile looks like when you have several research outputs. You can [set up your own ORCID](https://orcid.org/register) if you do not have one yet.
## Assignment: Data Dictionaries (for tabular data - optional)
*Estimated time: 15 minutes*
1. Watch a [video on data dictionaries](https://www.youtube.com/watch?v=Fe3i9qyqPjo)
2. Go to a tabular dataset you are working on or have worked on.
3. In an excel spreadsheet, start creating your data dictionary. Save the data dictionary in the same folder as the dataset you're describing. List all the variables that you find in the dataset on column A. Then, add a clear and understandable description of that variable on column B.
Note that you can also [create a package for your data with Frictionless Data](https://create.frictionlessdata.io)
## Assignment: Electronic Lab Notebooks (optional)
*Estimated time: 20 minutes*
[TU Delft offers two different Electronic Lab Notebooks](https://www.tudelft.nl/en/library/research-data-management/r/manage/electronic-lab-notebook), eLABjournal and RSpace. Watch the short videos introducing them:
- [eLABjournal intro](https://www.youtube.com/watch?v=ys4BKEWWnEc&feature=youtu.be) (*4:11 minutes*)
- [RSpace intro](https://www.youtube.com/watch?v=q2CEnZRC1_o&t=5s) (*1:43 minutes*)
Try out one of the Electronic Lab Notebooks:
To access **eLABJournal**
- Go to <https://tudelft.elabjournal.com/>
- Select 'log in with your institute account' (below the login form)
- Login with your netID
Note: new ELN groups must be reported to support\[at\]elabnext.com to get full access to eLABJournal.
To access **RSpace**:
- Go to <https://rspace.tudelft.nl>
- On the first time you log in to this tool, following authentication, you will be directed to the RSpace signup page, pre-populated with some information released from your netID, where you need to confirm that you want an account. (On subsequent logins, you will go straight to RSpace after authentication using your netID.)
Answer the following questions to see if the Electronic Lab Notebooks are helpful to your work:
- Was there any specific feature in one or both of the ELNs that would be particularly useful?
- What are the pros and cons that you can already think of when using an ELN for documenting your lab work?
### Other Electronic Lab Note tools
If RSpace or eLabjournal are not ideal for your workflow, you can also try out some of the following tools that have been brought up by previous course participants:
- OneNote
- [Obsidian](https://obsidian.md/) (or [logseq](https://logseq.com/))
## Paper Lab Notebooks
In case you prefer to stick to paper, here are some organisation tips:
- State the name of the researcher and period of use on the cover of the notebook
- Number all pages consecutively
- All entries should be written with permanent ink (no pencils)
- Standard language should be English
- Each record requires a date
- Make sure that it is possible to separate the different experiments recorded (use meaningful titles)
- Add a note where the raw data linked to the experiment will be stored and the name of the corresponding data file
- Do not keep loose pages in your notebook. Fix to the notebook any relevant piece of paper and/or picture in a proper way
Make sure you scan your paper notebook so that you have a back up copy!
## Software/code documentation
- See the [example used in the presentation using JupyterLab](https://mybinder.org/v2/gh/jupyterlab/jupyterlab-demo/master?urlpath=lab/tree/demo)
- [Template to set up a GitHub (or GitLab) repository with all the relevant documentation about the project](https://github.com/manuGil/fair-code)
- [Code Refinery materials on Code Documentation](https://coderefinery.github.io/documentation/)
- Use the [CodeMeta creator](https://codemeta.github.io/codemeta-generator/) to create a .json metadata file to add to your repo
- Barbara Vreede's presentation on [Best Practices for Writing Reproducible Code](https://bvreede.github.io/presentations/presentations/2020-09-17_BestPractices-lecture.html#1)
- [Jupyter Notebooks](https://github.com/jupyter/jupyter/wiki)
- [Aim For Understandability If You Want To Write Good Research Software](https://www.software.ac.uk/blog/2022-07-04-aim-understandability-if-you-want-write-good-research-software)
- For Julia you can use [DrWatson](https://juliadynamics.github.io/DrWatson.jl/dev/) to create consistent folder structures. Particularly useful for simulation data.