Welcome to the Scan and revieW of Open Research Data and Software (SWORDS) project. The SWORDS project is a powerful framework to gain insights in the open source activities of your, but not limited to, university or research institute. This repository is the start of your own implementation for your organisation! Read this part carefully. For any questions, please use the issue tracker.
This repository consists of 2 parts, the instruction and the template. The instruction is what you are reading right now, the template starts after <<< The template starts here >>> below. To implement the SWORDS framework to your organisation easily, we recommend to make use of the template function in GitHub. The instruction below helps you to implement SWORDS for your organisation in step-by-step manner.
- Define a name for your project. The recommended name is SWORDS@{INSERT YOUR ORGANISATION NAME ABBRAVATION}.
- Create a repository from the SWORDS template with the name as defined in step 1.
- Replace all fields in the README of your repostitory starting with
{INSERT ...}by your details of your project and organisation. Use search{INSERT, because some can be harder to find. - Delete in this README everything between
<!-- REMOVE EVERYTHING BEFORE THIS LINE IN STEP 4 -->.
This repository implements for the Scan and revieW of Open Research Data and Software (SWORDS) framework. SWORDS is a powerful tool to gain insights in the open source activities of your, but not limited to, university or research institute. Studies show that open source contributions can be very benificial for organisations and society. SWORDS is divided into 3 stages that can be exectued and analyzed standalone: finding user profiles associated to your organisation, extract relevant repositories, and study the contents of the respositories.
This repository is an implementation of SWORDS for {INSERT YOUR ORGANISATION NAME}.
SWORDS@{INSERT YOUR ORGANISATION NAME ABBRAVATION}
Conducting science in an open and collaborative way is very important for greater scientific and societal impact (https://www.nwo.nl/en/open-science). The Open Science movement is therefore actively promoting and advancing openness in academic publications, data, software, and other types of output. Major steps have been taken in the last years, however, there is still a lot to improve and win. A result of this movement towards more open research output is the increase of code and software published by researchers on online platforms. The use and reuse of open source (research) software and code is widespread nowadays.
For (research) organisations, it can be interesting to have insights into the contributions and activities in open source software projects. Especially because activities of members, researchers, or employees can be divided over multiple user profiles and platforms (e.g. GitHub and GitLab). Having an overview of the activity, contents, and quality can be useful for various reasons like connecting initiatives, improve quality, and reward and recognize contributions. The SWORDS framework was introduced to help with collecting insights and assessing quality.
- Its goal is to analyze the FAIRness of GitHub repositories of {INSERT YOUR ORGANISATION NAME} researchers and see how they develop and manage software. The purpose of this research is to serve as a template for other researchers to scan and review repositories for their organisation as well.
The SWORDS framework consists of three mostly-independent steps. Each step is described below and detailed information and instructions can be found in the links.
- Find user profiles associated to organisation. In this first step of the framework, multiple strategies are available to find users on GitHub and GitLab that are members or employees of your organisation. By using multiple collection strategies, the recall is considered to be high. The findability of members or employees is one of the output variables of this step. A structured list of users is used as input for the next step.
- Collect relevant repositories. In the second step, the repositories of the users collected in the previous step are collected and filtered. Not all repositories are research output. These repositories are filted out automatically and/or manually.
- Study and analyze repositories. In this step, further variables of research repositories are gathered. These are then examined and studied on various quantitiative and qualitative properties. One can think about quality assesments, documentation availablity, FAIRness scores.
The SWORDS framework is written in Python 3.6+. The SWORDS framework implements the reproducible project structure as proposed by Wilson et al. (2017) for each step of the framework. For more information about the phases, please look into the corresponding subfolders for further information on installation and usage. All output data is stored in output folders. There is also a corresponding interactive data analysis jupyter notebook file in each step. This notebook can be used for results.
The results of the three steps of the SWORDS framework can be found in each of the subfolders of the project. Each step contains a Jupyter notebook with results, code, and narrative. Output data files can be found in the output folder in each step.
Results of step 1: Find user profiles associated to organisation
Results of step 2: Collect relevant repositories
Results of step 3: Study and analyze repositories
In the normal use case, you start with phase 1 and go through each phase as the output of phase 1 can be used for phase 2. However, if you already have collected a list of users for example, you can skip phase 1 and use that collected list as input for phase 2. Since the phases are independent of each other, this approach is possible. For details on how to execute each phase, look into the corresponding subfolder.
Use this citation for citing the SWORDS implementation for paper Software FAIRness, Documentation and Development Practices in Potsdam Researchers' GitHub Repositories .
@software{Devkate_SWORDS_template_UP_2024,
author = {Devkate, Akshay and Lamprecht, Anna-Lena},
title = {{SWORDS template UP: Adopted and extended (software development practices)}},
institution = {University of Potsdam},
version = {v1.0.0},
year = {2024},
month = {8},
abstract = {This repository is used to collect and analyse GitHub repositories of researchers affiliated with organisations in Potsdam, aiming to analyse various aspects of software FAIRness, documentation quality, and software development practices.},
url = {https://github.com/Software-Engineering-Group-UP/SWORDS-template-UP/releases/tag/v1.0.0},
orcid = {https://orcid.org/0009-0004-9608-4479, https://orcid.org/0000-0003-1953-5606},
keywords = {research software, Software quality, empirical software engineering, FAIR4RS},
license = {MIT}
}
To cite the SWORDS project and the SWORDS template, use
@software{de_Bruin_Scan_and_revieW_2022,
author = {de Bruin, Jonathan and Quach, Keven and Slewe, Christopher and Lamprecht, Anna-Lena},
month = {2},
title = {{Template of Scan and revieW of Open Research Data and Software}},
url = {https://github.com/UtrechtUniversity/SWORDS-template},
version = {1.0.0},
year = {2022}
}
The SWORDS project template is published under the MIT License.
Icons of the banner are made by Freepik from www.flaticon.com.
For contact about this implementation of the SWORDS project, SWORDS@{INSERT YOUR ORGANISATION NAME ABBRAVATION}, post an issue on the issue tracker or contact {INSERT YOUR EMAIL}.
For general questions and remarks about the SWORDS project and the template can be posted on the issue tracker of the SWORDS template. You can also contact either Jonathan de Bruin or Keven Quach.
The SWORDS project is an idea of the FAIR Data and Software working group of the Utrecht University Open Science Programme.