Research Software - howfairis

howfairis

Oct 25, 2020. | By: @vsoch

Have you heard of the Fair principes? Or perhaps you’ve generally thought about what makes software:

Findable
Accessible
Interoperable
Reusable

This week we highlight an atypical piece of research software, fair-software/howfairis that helps to make some of these abstract ideas more concrete, meaning giving you actionable feedback about the status of your GitHub repository. Why is it atypical? Because likely some folks would not consider this research software. But perhaps others would, because it’s a meta library that has promise to be used in a research context to better understand our software.

/rseng/assets/img/posts/showcase/howfairis.png

Do you have an opinion? We encourage you to contribute to the research software encyclopedia and annotate the respository:

otherwise, keep reading!

What is howfairis?
How do I cite it?
How do I get started?
How do I contribute to the software survey
Where can I learn more?

What is Howfairis?

There are several attributes of software that are important for reproducibility. However, for the most part unless you do a manual evaluation of some software, you can’t easily evaluate some repository for these criteria. The goal of Howfairis is to make this evaluation possible. You can install the software:

pip install howfairis

And then immediately evaluate a repository for the four principles.

$ howfairis https://github.com/singularityhub/sregistry
Checking compliance with fair-software.eu...
url: https://github.com/singularityhub/sregistry
(1/5) repository
      ✓ has_open_repository
(2/5) license
      ✓ has_license
(3/5) registry
      × has_ascl_badge
      × has_bintray_badge
      × has_conda_badge
      × has_cran_badge
      × has_crates_badge
      × has_maven_badge
      × has_npm_badge
      × has_pypi_badge
      × has_rsd_badge
      × is_on_github_marketplace
(4/5) citation
      × has_citation_file
      × has_citationcff_file
      × has_codemeta_file
      ✓ has_zenodo_badge
      × has_zenodo_metadata_file
(5/5) checklist
      × has_core_infrastructures_badge
      × has_sonarcloud_badge

Calculated compliance: ● ● ○ ● ○

It seems you have not yet added the fair-software.eu badge to
your README.md. You can do so by pasting the following snippet:

[![fair-software.eu](https://img.shields.io/badge/fair--software.eu-%E2%97%8F%20%20%E2%97%8F%20%20%E2%97%8B%20%20%E2%97%8F%20%20%E2%97%8B-orange)](https://fair-software.eu)

How neat! And then if you own the software, you can also add the badge to your repository. For example, I did it for Singularity Registry Server:

Why is it useful?

I would actually suspect this to be useful from a research standpoint. Sure, it’s fun to evaluate our own software and add badges, but what if we could do this programatically for a bunch of repositories we want to study? I took a look at the code base, and wrote a little snippet to show how to programatically test a repository.

from howfairis.cli import Repo, Config, Checker, check_badge

# I suspect you could just define a path to a cloned repository here
repo = Repo(url="https://github.com/singularityhub/sregistry", branch="master", path=None)

# Use defaults
config = Config(repo)
checker = Checker(config)
checker.check_five_recommendations()

You then have the README from the repository

checker.readme
# <howfairis.Readme.Readme at 0x7ffbbb8708e0>
checker.readme.text

Along with the compliance

checker.compliance
<howfairis.Compliance.Compliance at 0x7ffbbb8607c0>

which you can parse for different attributes.

checker.compliance.checklist
False

checker.compliance.citation
True

checker.compliance.license
True

checker.compliance.registry
False

And you can also run a function to check for a badge.

check_badge(compliance=checker.compliance, readme=checker.readme)
Calculated compliance: ● ● ○ ● ○

Expected badge is equal to the actual badge. It's all good.

The function system exits because it’s intended to be run from a client, which might not be ideal design if you want to do this programatically.

How do I cite it?

The package has a record on Zenodo that you can use:

@software{spaaks_jurriaan_h_2020_4036809,
  author       = {Spaaks, Jurriaan H. and
                  Kuzak, Mateusz and
                  Martinez-Ortiz, Carlos and
                  van Werkhoven, Ben and
                  Etuk, Edidiong and
                  Saladi, Shyam and
                  Holding, Andrew},
  title        = {howfairis},
  month        = sep,
  year         = 2020,
  publisher    = {Zenodo},
  version      = {0.11.0},
  doi          = {10.5281/zenodo.4036809},
  url          = {https://doi.org/10.5281/zenodo.4036809}
}

How do I get started?

README Documentation is always a good place to start.

How do I contribute to the software survey?

or read more about annotation here. You can clone the software repository to do bulk annotation, or annotation any repository in the software database, We want annotation to be fun, straight-forward, and easy, so we will be showcasing one repository to annotate per week. If you’d like to request annotation of a particular repository (or addition to the software database) please don’t hesitate to open an issue or even a pull request.

Where can I learn more?

You might find these other resources useful:

The Research Software Database on GitHub
RSEpedia Documentation
Google Docs Manuscript you are invited to contribute to.
Annotation Documentation for RSEpedia
Annotation Tutorial in RSEng docs

For any resource, you are encouraged to give feedback and contribute!