From 22f411b1fabf6cd8d8daee09d2b93807aca1bb6c Mon Sep 17 00:00:00 2001 From: Maurits Kok Date: Tue, 16 Jul 2024 16:45:18 +0200 Subject: [PATCH 1/2] Minor general fixes --- docs/_toc.yml | 1 - docs/community/maintainers.md | 2 +- docs/data/storage_options.md | 2 +- docs/infrastructure/gitlab/gitlab_docker.md | 9 +++++---- docs/infrastructure/moving_data.md | 2 +- environment.yml | 3 ++- 6 files changed, 10 insertions(+), 9 deletions(-) diff --git a/docs/_toc.yml b/docs/_toc.yml index a8d16bb..f13e780 100644 --- a/docs/_toc.yml +++ b/docs/_toc.yml @@ -59,6 +59,5 @@ parts: - caption: 🤝 Community chapters: - file: community/dcc - - file: community/dcc_projects - file: community/contribute - file: community/code_of_conduct diff --git a/docs/community/maintainers.md b/docs/community/maintainers.md index 7e5299b..a62bfa7 100644 --- a/docs/community/maintainers.md +++ b/docs/community/maintainers.md @@ -5,7 +5,7 @@ _This content is automatically generated, all changes made will be lost._ | Section | Title | Lead maintainer | Backup maintainer | |:---------------|:------------------------------------------|:----------------------|:--------------------| | containers | Docker users | Maurits Kok | | -| data | Request Project Drive | Ashley Cryan | | +| data | RequestProject Drive | Ashley Cryan | | | data | Sync with Unison | Ashley Cryan | | | data | Mount Project Drive | Raúl Ortiz Merino | Maurits Kok | | data | Data publishing | Aleksandra Wilczynska | | diff --git a/docs/data/storage_options.md b/docs/data/storage_options.md index 1177ddc..d222301 100644 --- a/docs/data/storage_options.md +++ b/docs/data/storage_options.md @@ -1,6 +1,6 @@ # TU Delft data storage -Storing your data in a secure location is a key element of a successful project with a data component. TU Delft recommends using a [Project Drive]((https://tudelft.topdesk.net/tas/public/ssp/content/detail/service?unid=846ebb16181c43b5836c063a917dd199&from=03aa10b9-c5aa-4e0a-80b1-28ee7ab383df)) for storing research data. This solution enables secure data storage and facilitates access to your data to other researchers from your research group during the duration of the project. It also allows TU Delft researchers to have access to the data after your PhD contract is completed. +Storing your data in a secure location is a key element of a successful project with a data component. TU Delft recommends using a [Project Drive](https://tudelft.topdesk.net/tas/public/ssp/content/detail/service?unid=846ebb16181c43b5836c063a917dd199&from=03aa10b9-c5aa-4e0a-80b1-28ee7ab383df) for storing research data. This solution enables secure data storage and facilitates access to your data to other researchers from your research group during the duration of the project. It also allows TU Delft researchers to have access to the data after your PhD contract is completed. The TU Delft offers various data storage options. A complete list is available throught the [Service desk](https://tudelft.topdesk.net/tas/public/ssp/content/detail/service?unid=f359caaa60264f99b0084941736786ae&from=feffb489-e1f9-49cd-8223-53ae0b70b609) (TU delft login required). diff --git a/docs/infrastructure/gitlab/gitlab_docker.md b/docs/infrastructure/gitlab/gitlab_docker.md index dc348ec..044ec4f 100644 --- a/docs/infrastructure/gitlab/gitlab_docker.md +++ b/docs/infrastructure/gitlab/gitlab_docker.md @@ -151,14 +151,15 @@ In response to this command you will be prompted to answer the following questio - Enter name of the runner: example-runner - Type of executor: docker - Default Docker image: Specify the same image as the one specified in the 'image' field of the .gitlab-ci.yml file. - ``` -See an example below. -```shell -~$ docker run --rm -it -v /srv/gitlab-runner/config:/etc/gitlab-runner gitlab/gitlab-runner register +See an example below. +```bash +docker run --rm -it -v /srv/gitlab-runner/config:/etc/gitlab-runner gitlab/gitlab-runner register +``` +``` Enter the GitLab instance URL (for example, https://gitlab.com/): https://gitlab.tudelft.nl Enter the registration token: diff --git a/docs/infrastructure/moving_data.md b/docs/infrastructure/moving_data.md index 2a9dd09..37fe810 100644 --- a/docs/infrastructure/moving_data.md +++ b/docs/infrastructure/moving_data.md @@ -13,7 +13,7 @@ $ scp -o "ProxyCommand ssh -W %h:%p @linux-bastion-ex.tudelft. ## Copy Data using SSH Tunneling -If a default [ssh tunneling](##ssh-tunneling) was configured correctly. Data can be copied to and from a remote host as follows: +If a default [ssh tunneling](VPS_SSH.md) was configured correctly. Data can be copied to and from a remote host as follows: ```bash # Copy TO Remote Host diff --git a/environment.yml b/environment.yml index 2edc205..731a4f2 100644 --- a/environment.yml +++ b/environment.yml @@ -4,7 +4,7 @@ channels: - bioconda - defaults dependencies: - - python=3.8 + - python=3.12 - numpy - pandas - tabulate @@ -14,6 +14,7 @@ dependencies: - sphinx-inline-tabs - sphinx-panels - sphinx-togglebutton + - pip - pip: - linkify - python-frontmatter \ No newline at end of file From 7c844b2dacd1eb5f9c1ecdf6e5de14287ee557a9 Mon Sep 17 00:00:00 2001 From: Maurits Kok Date: Tue, 16 Jul 2024 17:10:10 +0200 Subject: [PATCH 2/2] Update software checklist --- docs/community/maintainers.md | 2 +- docs/software/checklist.md | 144 +++++++++++++++++++++------------- 2 files changed, 90 insertions(+), 56 deletions(-) diff --git a/docs/community/maintainers.md b/docs/community/maintainers.md index a62bfa7..80c8895 100644 --- a/docs/community/maintainers.md +++ b/docs/community/maintainers.md @@ -17,7 +17,7 @@ _This content is automatically generated, all changes made will be lost._ | infrastructure | Request VPS | Ashley Cryan | | | infrastructure | Set up an Apache web server | Ashley Cryan | | | resources | Curriculum | Ashley Cryan | Maurits Kok | -| software | FAIR checklist | Maurits Kok | | +| software | FAIR4RS checklist | Maurits Kok | Elviss Dvinskis | | software | Software Management Plan | Maurits Kok | | | software | Branch management | Maurits Kok | | | testing | Testing with MATLAB | Maurits Kok | | \ No newline at end of file diff --git a/docs/software/checklist.md b/docs/software/checklist.md index b706b02..894dfe9 100644 --- a/docs/software/checklist.md +++ b/docs/software/checklist.md @@ -1,100 +1,134 @@ --- section: software -title: FAIR checklist +title: FAIR4RS checklist author_1: Maurits Kok -author_2: +author_2: Elviss Dvinskis --- -# FAIR software checklist +# FAIR checklist for research software -To ensure your research software is findable and usable by other researchers, we have compiled a checklist to improve its FAIRness (Findable, Accessible, Interoperable, Reusable). +The goal of the FAIR principles is to improve research transparency, reproducibility and reusability. To achieve this, your research needs to be described through metadata, should be open for inspection, well-documented, and well structured. This ensures that it can be replicated, expanded upon, merged, reinterpreted, or reimplemented. The acronym FAIR stands for: +- **F**indable: Your research software can be easily found (i.e. has rich metadata, unique identifiers). +- **A**ccessible: Once found, it can be accessed, ideally through well-defined and open protocols. +- **I**nteroperable: Your research is compatible with other datasets, tools, and workflows, allowing for integration and reuse across various applications and fields. +- **R**eusable: The ultimate goal is that your research outputs can be reused in different contexts. This requires comprehensive documentation, clear licensing, and a modular structure. -## Checklist +While originally targetting data management, the FAIR for Research Software (FAIR4RS) extends these principles to research software, which, unlike data, is executable and evolves over time. Ensuring the findability of software involves metadata, identifiers, and version control systems, while accessibility includes guidelines for obtaining, installing, and running the software. Interoperability involves adherence to community-driven standards or protocols, and reusability requires detailed documentation and user guides to effectively apply the software in new research projects. -The checklist below is in part based on the checklist provided by the [eScience Center](https://guide.esciencecenter.nl/#/nlesc_specific/checklist_matrix), licensed under CC BY 4.0. +:::{seealso} -### Version Control -_Essential_ +- [FAIR Guiding Principles for scientific data management and stewardship to research software](https://zenodo.org/records/6623556) +- [FAIR4RS community in Zenodo](https://zenodo.org/communities/fair4rs/records?q=&l=list&p=1&s=10&sort=newest) +- [FAIR Software Checklist](https://fair-software.nl/) - five recommendations for FAIR (scientific) software +::: + + +## Checklist + +:::{admonition} Version Control +_Essential_ - [ ] Use [git](https://www.atlassian.com/git) as a version control system - [ ] Upload your project on [GitHub](https://github.com/) or [TU Delft GitLab](https://gitlab.tudelft.nl/) _Recommended_ - [ ] Make your repository [public](https://coderefinery.github.io/social-coding/) -- [ ] [Branch hygiene](https://coderefinery.github.io/git-branch-design/) -- [ ] Use a branching model ([GitFlow](https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow)) -- [ ] [Meaningful commit messages](https://www.git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines) +- [ ] Consider your [branch hygiene](https://coderefinery.github.io/git-branch-design/) +- [ ] Use a branching model (e.g. [GitFlow](https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow)) +- [ ] Use [meaningful commit messages](https://www.git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines) +::: +:::{admonition} Collaboration +_Essential_ +- [ ] Make use of [GitHub issues](https://docs.github.com/en/issues/tracking-your-work-with-issues/about-issues) -### Documentation - Repository +_Recommended_ +- [ ] [Contribution guidelines](https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/setting-guidelines-for-repository-contributors) +- [ ] [Code of conduct](https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/adding-a-code-of-conduct-to-your-project) + +::: + +:::{admonition} Project documentation _Essential_ -- [ ] [README](https://github.com/18F/open-source-guide/blob/18f-pages/pages/making-readmes-readable.md) -- [ ] [LICENSE](https://doi.org/10.5281/zenodo.4629662) +- [ ] [README](https://www.makeareadme.com) +- [ ] Apply a TU Delft pre-approved [LICENSE](https://zenodo.org/records/4629635) - [ ] [CITATION](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-citation-files) +::: -_Recommended_ -- [ ] Make use of [Github issues](https://docs.github.com/en/issues/tracking-your-work-with-issues/about-issues) -- [ ] Contribution [guidelines](https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/setting-guidelines-for-repository-contributors) -- [ ] [Code of conduct](https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/adding-a-code-of-conduct-to-your-project) - -### Documentation - Software +:::{admonition} Software documentation _Essential_ - [ ] Source code documentation ([docstrings](https://numpydoc.readthedocs.io/en/latest/format.html)) +- [ ] Document your project dependencies - [ ] Installation instructions -- [ ] Usage documentation -- [ ] Developer setup +- [ ] User documentation _Recommended_ -- [ ] Examples and tutorials (Jupyter notebooks, videos, screencasts) -- [ ] Website ([github.io pages](https://pages.github.com/), [Readthedocs](https://readthedocs.org/), [JupyterBook](https://jupyterbook.org/intro.html) -- [ ] Build [API reference](https://developer.lsst.io/python/numpydoc.html) from docstrings +- [ ] Developer documentation and setup +- [ ] Examples and tutorials (e.g. Jupyter Notebooks) +_Optional_ +- [ ] Documentation tools ([Sphinx](https://coderefinery.github.io/documentation/sphinx/), [JupyterBook](https://jupyterbook.org/intro.html), [Quarto](https://quarto.org/docs/guide/)) +- [ ] Build an [API reference](https://developer.lsst.io/python/numpydoc.html) from docstrings +- [ ] Hosting ([GitHub Pages](https://pages.github.com/), [Readthedocs](https://readthedocs.org/)) +::: -### Testing -_Recommended_ +:::{admonition} Software testing +_Essential_ +- [ ] Installation/execution verification + +_Recommended_ - [ ] [Defensive programming](https://swcarpentry.github.io/python-novice-inflammation/10-defensive.html) - [ ] Test your software with [integration tests](https://the-turing-way.netlify.app/reproducible-research/testing/testing-integrationtest.html) and [unit tests](https://the-turing-way.netlify.app/reproducible-research/testing/testing-unittest.html) -- [ ] User installation test -- [ ] Make use of [Continuous Integration](https://the-turing-way.netlify.app/reproducible-research/ci/ci-options.html) -- [ ] Code coverage check ([Codecov](https://about.codecov.io/), [Sonarcloud](https://sonarcloud.io/), [Travis](https://www.travis-ci.com/)) - +- [ ] Make use of [Continuous Integration](https://coderefinery.github.io/testing/continuous-integration/) to automate testing -### Releases -_Essential_ -- [ ] Obtain a DOI ([Zenodo](https://zenodo.org/) or [4TU.ResearchData](https://data.4tu.nl/info/about-your-data/getting-started)) +_Optional_ +- [ ] Code coverage check (e.g. [Sonarcloud](https://sonarcloud.io/), [codecov](https://about.codecov.io)) +::: -_Recommended_ -- [ ] [Semantic versioning](https://semver.org/) -- [ ] Tagged releases ([GitHub](https://docs.github.com/en/repositories/releasing-projects-on-github)) -- [ ] [CHANGELOG](https://keepachangelog.com/en/1.0.0/) -- [ ] Upload to registry ([PyPI](https://realpython.com/pypi-publish-python-package/), [conda](https://conda.io/projects/conda-build/en/latest/user-guide/tutorials/build-pkgs.html), [DockerHub](https://docs.docker.com/docker-hub/repos/)) -- [ ] [Release guide](https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository) -- [ ] Continuous Integration for build and release - -### Code quality +:::{admonition} Software quality _Essential_ -- [ ] Project [organisation](https://coderefinery.github.io/reproducible-research/organizing-projects/) -- [ ] Record [software dependencies](https://coderefinery.github.io/reproducible-research/dependencies/) +- [ ] [Organize](https://coderefinery.github.io/reproducible-research/organizing-projects/) your project for reproducibility +- [ ] [Record and manage](https://coderefinery.github.io/reproducible-research/dependencies/) your software dependencies _Recommended_ +- [ ] Make [refactoring](https://refactoring.guru/refactoring) part of your workflow +- [ ] Follow [best coding practices](https://alan-turing-institute.github.io/rse-course/html/module07_construction_and_design/index.html) + +_Recommended for Python_ - [ ] Follow [PEP8 guidelines](https://realpython.com/python-pep8/) +- [ ] Use a tool for dependency management (e.g. [poetry](https://the-turing-way.netlify.app/reproducible-research/renv/renv-package.html)) - [ ] Use linter (e.g. [pylint](https://pypi.org/project/pylint/), [flake8](https://pypi.org/project/flake8/)) -- [ ] Use a formatter (e.g. [black](https://github.com/psf/black), [yapf](https://github.com/google/yapf)) -- [ ] Follow [best coding practices](https://alan-turing-institute.github.io/rse-course/html/module07_construction_and_design/index.html) +- [ ] Use a formatter (e.g. [black](https://github.com/psf/black)) +::: + +:::{admonition} Releases +_Essential_ +- [ ] Obtain a DOI ([Zenodo](https://zenodo.org/) or [4TU.ResearchData](https://data.4tu.nl/info/about-your-data/getting-started)) + +_Recommended_ +- [ ] Use [semantic versioning](https://semver.org/) +- [ ] Create tagged releases ([GitHub](https://docs.github.com/en/repositories/releasing-projects-on-github)) +- [ ] [CHANGELOG](https://keepachangelog.com/en/1.0.0/) +- [ ] Upload to [registry](https://github.com/NLeSC/awesome-research-software-registries) (e.g. [PyPI](https://realpython.com/pypi-publish-python-package/), [conda](https://conda.io/projects/conda-build/en/latest/user-guide/tutorials/build-pkgs.html)) +- [ ] [Releasing guide](https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository) - +_Optional_ +- [ ] [Continuous Integration](https://the-turing-way.netlify.app/reproducible-research/ci/ci-options.html) for automated build and release +::: ## Example repositories * [eScience Center - matchms](https://github.com/matchms/matchms) - Matchms is an open-source Python package to import, process, clean, and compare mass spectrometry data. * [TU Delft - Transposonmapper](https://github.com/SATAY-LL/Transposonmapper) - Transposonmapper is an open-source python package and Docker image for mapping transposons from sequencing data. -## References +:::{seealso} +For more information on the principles behind FAIR software, please have a look at the following resources: -For a full overview of the principles behind FAIR software, please have a look at the following resources: +- [The Turing Way - Guide for Reproducible Research](https://the-turing-way.netlify.app/reproducible-research/reproducible-research.html) - general guide to reproducible research +- [Towards FAIR principles for research software](https://content.iospress.com/articles/data-science/ds190026) - publication on the translation of FAIR principles for data to FAIR principles for software +- [From FAIR research data toward FAIR and open research software](https://doi.org/10.1515/itit-2019-0040) +- [FAIR Principles for Research Software](https://zenodo.org/records/6623556) +::: -* [FAIR software checklist](https://fair-software.nl/) - five recommendations for FAIR (scientific) software -* [Towards FAIR principles for research software](https://content.iospress.com/articles/data-science/ds190026) - publication on the translation of FAIR principles for data to FAIR principles for software. -* [Guide for Reproducible Research](https://the-turing-way.netlify.app/reproducible-research/reproducible-research.html) - general guide to reproducible research -* [The Zen of Scientific Computing](https://scicomp.aalto.fi/scicomp/zen-of-scicomp/#) - Scientific computing tips from Aalto University -* [From FAIR research data toward FAIR and open research software](https://doi.org/10.1515/itit-2019-0040) +## Acknowledgements +The checklist was in part based on the checklist provided by the [eScience Center](https://guide.esciencecenter.nl/#/nlesc_specific/checklist_matrix), licensed under CC BY 4.0. \ No newline at end of file