Update on the metadata episode, first draft of introduction & setup #52

fpsom · 2018-09-03T10:46:03Z

Metadata episode

Added the "movie" exercise REC2: Stress out the importance of meta-data in software #9
Added bio.tool figure and info using dev instance to teach bio.tools #15 REC2: Be aware of the registry platforms and the respective standards #11
Added more definitions
Added explanation of controlled vocabulary vs ontology REC2: Highlight the use of vocabularies for machine-readability in metadata #10
General fixes, typos and timing
Addressed some of the issues in Metadata episode - review after the hackathon utrecht August 1-3 #51

Introduction episode

first draft

Setup page

create accounts on GitHub and bio.tools

Guide page

transferred points from the metadata episode

- metadata: Added the "movie" exercise - metadata: Added bio.tool figure and info - metadata: Added more definitions - metadata: Added explanation of controlled vocabulary vs ontology - metadata: General fixes, typos and timing - introduction: first draft - setup: create accounts on GitHub and bio.tools - guide: added only metadata points

mkuzak · 2018-09-03T13:51:38Z

_episodes/01-introduction.md

 objectives:
- "First objective."
+- "What are the basics of Open Science in research software"
+- "What are the FAIR principles"


Change objectives from questions to statements.

Comment addressed.

mkuzak · 2018-09-03T13:52:18Z

_episodes/01-introduction.md

 exercises: 0
 questions:
- "Key question"
+- "Why are best practices necessary in research software"


add "How Open Source can help with better quality of software?"

Comment addressed.

mkuzak · 2018-09-03T13:59:30Z

_episodes/03-use-registry.md

+- System documentation and
+- User documentation
+
+_System documentation_ represents documents that describe the system itself and its parts. It includes requirements documents, design decisions, architecture descriptions, program source code, and help guides. On the other hand, _User documentation_ covers manuals that are mainly prepared for end-users of the product and system administrators. User documentation includes tutorials, user guides, troubleshooting manuals, installation, and reference manuals.


for me this documentation section is very formal

Comment addressed. Hopefully, the new text captures the same content but in a more simple format.

mkuzak · 2018-09-03T15:15:36Z

_extras/guide.md

+
+- Notes from the metadata episode
+  - [Local Installation of Zenodo](https://github.com/zenodo/zenodo/blob/master/INSTALL.rst)
+    It may be interesting to have a local installation of zenodo to play around. The instructions using Docker are available on the link above.


under the link

Comment addressed

mkuzak · 2018-09-03T15:16:15Z

_extras/guide.md

+    It may be interesting to have a local installation of zenodo to play around. The instructions using Docker are available on the link above.
+
+  - [Bio-Linux](http://environmentalomics.org/bio-linux-software-list/)
+    It is a final OS containing tools that have been already published, connected metadata, etc


what does "final OS" mean?

Comment addressed.

mkuzak · 2018-09-03T15:16:47Z

setup.md

@@ -3,4 +3,15 @@ layout: page
 title: Setup
 root: .
 ---
-FIXME
+
+In order to be prepared for the lesson, you need to have accounts to the following (free) services:


accounts on

Comment addressed.

mkuzak · 2018-09-03T15:17:40Z

setup.md

+
+2. BioTools
+
+[bio.tools](https://bio.tools/) is a portal to bioinformatics resources worldwide, aimed to help bioinformaticians and scientists, find, understand, compare and select resources as well as use and connect them in workflows.


they don't need bio.tools account only dev.bio.tools

We are actually explicitly requesting for participants to create an account on the dev instance in the next sentence. However, I thought it made sense to include an intro to the actual platform. If that is redundant, we can delete it.

fpsom · 2018-09-04T07:12:36Z

Thanks for the review @mkuzak ! I think I've addressed all the issues (with the possible exception of the bio.tools one, but we can revisit this for sure).

fpsom · 2018-09-04T12:43:33Z

Updated PR to reflect @tobyhodges comment in #44.

ljgarcia · 2018-09-04T09:29:10Z

_episodes/01-introduction.md

 objectives:
- "First objective."
+- "Basics of Open Science in research software"
+- "Introduction to the FAIR principles"


FAIR principles are related to metadata, I suggest to add a key question about the role played by metadata in research software

Given that this introduction is for all four of the best practices, I think that it may be too specific to have a question just for metadata. Thoughts?

Totally agree, you are right, no need to add anything here

ljgarcia · 2018-09-04T09:33:43Z

_episodes/01-introduction.md

 keypoints:
- "First key point."
+- "Best practices in research software are tied to the FAIR principles"
+- "They are not tailored to software developers, but rather to a wider audience"


Not sure whether "they" here refers to the best practices or the FAIR principles.

I've addressed this with a new commit.

ljgarcia · 2018-09-04T09:34:48Z

_episodes/01-introduction.md

 ---
+
+Scientific research relies on computer software, yet software is not always developed following practices that ensure its quality and sustainability. One of the most recent publications ([Four simple recommendations to encourage best practices in research software](https://f1000research.com/articles/6-876/v1)) provided a simple, yet robust framework of simple recommendations that encourage the adoption of existing best practices in developing research software. These recommendations are designed around Open Science values, and provide practical suggestions that contribute to making research software and its source code more discoverable, reusable and transparent.


"Scientific research relies on computer software" Do you mean it relies on regular software development practices?

Rephrased to better reflect the original intention.

ljgarcia · 2018-09-04T09:39:52Z

_episodes/01-introduction.md

 ---
+
+Scientific research relies on computer software, yet software is not always developed following practices that ensure its quality and sustainability. One of the most recent publications ([Four simple recommendations to encourage best practices in research software](https://f1000research.com/articles/6-876/v1)) provided a simple, yet robust framework of simple recommendations that encourage the adoption of existing best practices in developing research software. These recommendations are designed around Open Science values, and provide practical suggestions that contribute to making research software and its source code more discoverable, reusable and transparent.


"One of the most recent publications" I would suggest to omit "most".

I've addressed this with a new commit.

ljgarcia · 2018-09-04T09:40:41Z

_episodes/01-introduction.md

+
+Scientific research relies on computer software, yet software is not always developed following practices that ensure its quality and sustainability. One of the most recent publications ([Four simple recommendations to encourage best practices in research software](https://f1000research.com/articles/6-876/v1)) provided a simple, yet robust framework of simple recommendations that encourage the adoption of existing best practices in developing research software. These recommendations are designed around Open Science values, and provide practical suggestions that contribute to making research software and its source code more discoverable, reusable and transparent.
+
+Based on these recommendations, this lesson focuses on providing both the underlying context as well as some practical exercises towards establishing their usefulness in the long term. The consequent episodes of this lesson are structured in the form of one episode per recommendation;


Colon rather than semi-colon at the end of this paragraph?

Fixed in the new commit.

ljgarcia · 2018-09-04T09:42:07Z

_episodes/01-introduction.md

+
+"_When all researchers are aware of Open Science, and are trained, supported and guided at all career stages to practice Open Science, the potential is there to fundamentally change the way research is performed and disseminated, fostering a scientific ecosystem in which research gains increased visibility, is shared more efficiently, and is performed with enhanced research integrity._" [Open Science Skills Working Group Report (2017)](https://ec.europa.eu/research/openscience/pdf/os_skills_wgreport_final.pdf#view=fit&pagemode=none)
+
+Discussing best practices in developing research software, one is bound to touch on the subject of Open Science. Modern research relies on software, and building upon—or reproducing—that research requires access to the full source code behind that software ([ref](https://open-science-training-handbook.gitbook.io)). Sharing software used for research (whether computational in nature, or that relies on any software-based analysis/interpretation) is a necessary, though not sufficient, condition for reproducibility. In addition to reproducibility, sharing software openly allows developers to receive career credit for their efforts, either through direct citation or via published software articles. We are going to be discussing all these aspects in the following lesson.


upon-or? Not sure if should be upon -or (long dash there)

Fixed in the new commit

ljgarcia · 2018-09-04T09:46:41Z

_episodes/01-introduction.md

+
+Discussing best practices in developing research software, one is bound to touch on the subject of Open Science. Modern research relies on software, and building upon—or reproducing—that research requires access to the full source code behind that software ([ref](https://open-science-training-handbook.gitbook.io)). Sharing software used for research (whether computational in nature, or that relies on any software-based analysis/interpretation) is a necessary, though not sufficient, condition for reproducibility. In addition to reproducibility, sharing software openly allows developers to receive career credit for their efforts, either through direct citation or via published software articles. We are going to be discussing all these aspects in the following lesson.
+
+## FAIR principles


I suggest to make explicit the relation between the 4OSS and FAIR, otherwise is kind of disconnected

Fixed in the new commit.

ljgarcia · 2018-09-04T09:58:07Z

_episodes/03-use-registry.md

@@ -78,25 +101,21 @@ A standard can be defined as "a structure agreed and adopted by a community" or
 >
 {: .callout}

-TODO: difference between control vocabulary and ontology.
-
+**Controlled vocabularies** provide a way to organize knowledge for subsequent retrieval. It is usually a carefully selected list of words and phrases, which are used to tag units of information (document or work) so that they may be more easily retrieved by a search. The fundamental difference between an **ontology** and a **controlled vocabulary** is the level of abstraction and relationships among concept. A formal ontology is a controlled vocabulary expressed in an ontology representation language. ([ref](https://semwebtec.wordpress.com/2010/11/23/contolled-vocabulary-vs-ontology/))


If we are going to explicitlely mention ontologies, we might mention as well others, explaining how they go from soft/weak representations to those with stronger logic in it, and then move to ontologies and their importance.

I left this unresolved as I think it may be too technical. Thoughts?

It would be indeed too technical. What about "The fundamental difference between and ontology and other controlled vocabularies, e.g., thesauri, is the [...]"?

That is a great point! Fixed in a new commit.

ljgarcia · 2018-09-04T13:07:32Z

_episodes/03-use-registry.md

-
- [Bio-Linux](http://environmentalomics.org/bio-linux-software-list/)
-It is a final OS containing tools that have been already published, connected metadata, etc
+By adding good enough metadata to our research software, we are directly supporting its findability, thus increasing the overall visibility of the software. This is tied to the **findable** aspect of the FAIR principles mentioned in the introductory episode of this lesson.


Metadate can also support accessibility if you include a license there, or interoperability if you include input/output data types or format. There might be some metadata supporting as well reusability.

That would be a nice exercise, asking attendees to map the metadata they have identified to FAIR principles... but maybe not enough time for it though...

Fixed in the new commit. And excellent idea for an optional challenge @ljgarcia ! :)

fpsom · 2018-09-04T16:47:58Z

Thanks for the comments @ljgarcia ! I've addressed most of them in a new commit, with the exception of two.

fpsom · 2018-09-05T08:21:11Z

Thanks @tobyhodges , @ljgarcia and @mkuzak for the comments and the review. If you are happy with the current version, feel free to merge.

fpsom · 2018-09-07T12:06:15Z

I'll take the silence as acceptance, so I'll merge the PR by the end of day today. :)

FatmaZG · 2018-09-10T14:57:49Z

Thanks to all for the great improvements I've seen to the first draft. @fpsom we might still have to shrink down a bit the list of examples (great new ones added by @orchid00). Any final timing for each section/sub-section?

fpsom added the Metadata-episode label Sep 3, 2018

fpsom mentioned this pull request Sep 3, 2018

Metadata episode - review after the hackathon utrecht August 1-3 #51

Open

6 tasks

Fixed minor typo.

5071a71

mkuzak requested changes Sep 3, 2018

View reviewed changes

Fixed points raised by @mkuzak

7962664

fpsom mentioned this pull request Sep 4, 2018

Content of introduction #44

Closed

Merge branch 'gh-pages' into fpsom-general-patch

95be7b0

ljgarcia reviewed Sep 4, 2018

View reviewed changes

fpsom added 2 commits September 4, 2018 19:36

Addressed some of the comments raised by @ljgarcia

7581dfc

Additional fixes proposed by @ljgarcia

3855794

Additional fix addressing @ljgarcia comment

4e6afc6

orchid00 mentioned this pull request Sep 7, 2018

Licence episode - review after the hackathon utrecht August 1-3 #54

Open

fpsom merged commit ce1fc7b into gh-pages Sep 7, 2018

orchid00 deleted the fpsom-general-patch branch November 21, 2018 23:53


		2. BioTools

		[bio.tools](https://bio.tools/) is a portal to bioinformatics resources worldwide, aimed to help bioinformaticians and scientists, find, understand, compare and select resources as well as use and connect them in workflows.

		---

		Scientific research relies on computer software, yet software is not always developed following practices that ensure its quality and sustainability. One of the most recent publications ([Four simple recommendations to encourage best practices in research software](https://f1000research.com/articles/6-876/v1)) provided a simple, yet robust framework of simple recommendations that encourage the adoption of existing best practices in developing research software. These recommendations are designed around Open Science values, and provide practical suggestions that contribute to making research software and its source code more discoverable, reusable and transparent.


		Scientific research relies on computer software, yet software is not always developed following practices that ensure its quality and sustainability. One of the most recent publications ([Four simple recommendations to encourage best practices in research software](https://f1000research.com/articles/6-876/v1)) provided a simple, yet robust framework of simple recommendations that encourage the adoption of existing best practices in developing research software. These recommendations are designed around Open Science values, and provide practical suggestions that contribute to making research software and its source code more discoverable, reusable and transparent.

		Based on these recommendations, this lesson focuses on providing both the underlying context as well as some practical exercises towards establishing their usefulness in the long term. The consequent episodes of this lesson are structured in the form of one episode per recommendation;


		"_When all researchers are aware of Open Science, and are trained, supported and guided at all career stages to practice Open Science, the potential is there to fundamentally change the way research is performed and disseminated, fostering a scientific ecosystem in which research gains increased visibility, is shared more efficiently, and is performed with enhanced research integrity._" [Open Science Skills Working Group Report (2017)](https://ec.europa.eu/research/openscience/pdf/os_skills_wgreport_final.pdf#view=fit&pagemode=none)

		Discussing best practices in developing research software, one is bound to touch on the subject of Open Science. Modern research relies on software, and building upon—or reproducing—that research requires access to the full source code behind that software ([ref](https://open-science-training-handbook.gitbook.io)). Sharing software used for research (whether computational in nature, or that relies on any software-based analysis/interpretation) is a necessary, though not sufficient, condition for reproducibility. In addition to reproducibility, sharing software openly allows developers to receive career credit for their efforts, either through direct citation or via published software articles. We are going to be discussing all these aspects in the following lesson.


		Discussing best practices in developing research software, one is bound to touch on the subject of Open Science. Modern research relies on software, and building upon—or reproducing—that research requires access to the full source code behind that software ([ref](https://open-science-training-handbook.gitbook.io)). Sharing software used for research (whether computational in nature, or that relies on any software-based analysis/interpretation) is a necessary, though not sufficient, condition for reproducibility. In addition to reproducibility, sharing software openly allows developers to receive career credit for their efforts, either through direct citation or via published software articles. We are going to be discussing all these aspects in the following lesson.

		## FAIR principles

Update on the metadata episode, first draft of introduction & setup #52

Update on the metadata episode, first draft of introduction & setup #52

Conversation

fpsom commented Sep 3, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

fpsom commented Sep 4, 2018

fpsom commented Sep 4, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

fpsom commented Sep 4, 2018

fpsom commented Sep 5, 2018

fpsom commented Sep 7, 2018

FatmaZG commented Sep 10, 2018