Metadata-Version: 2.4
Name: rsfc
Version: 0.1.4
Summary: EVERSE Research Software Fairness Checks
License: MIT
License-File: LICENSE
Author: Andres Montero
Author-email: andres.montero.martin@upm.es
Requires-Python: >=3.10,<=3.13
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Dist: anyascii (==0.3.2)
Requires-Dist: attrs (==25.3.0)
Requires-Dist: beautifulsoup4 (==4.13.4)
Requires-Dist: bibtexparser (==1.4.3)
Requires-Dist: bs4 (==0.0.1)
Requires-Dist: build (==1.2.2.post1)
Requires-Dist: certifi (==2025.6.15)
Requires-Dist: chardet (==5.2.0)
Requires-Dist: charset-normalizer (==3.4.2)
Requires-Dist: click (==8.2.1)
Requires-Dist: click-option-group (==0.5.7)
Requires-Dist: contourpy (==1.3.2)
Requires-Dist: contractions (==0.1.73)
Requires-Dist: cycler (==0.12.1)
Requires-Dist: duckdb (==1.3.1)
Requires-Dist: elementpath (==4.8.0)
Requires-Dist: falcon (==3.1.3)
Requires-Dist: fastjsonschema (==2.21.1)
Requires-Dist: fonttools (==4.58.4)
Requires-Dist: idna (==3.10)
Requires-Dist: imbalanced-learn (==0.11.0)
Requires-Dist: inflect (==7.5.0)
Requires-Dist: iniconfig (==2.1.0)
Requires-Dist: jinja2 (==3.1.6)
Requires-Dist: joblib (==1.5.1)
Requires-Dist: jsonpath-python (==1.0.6)
Requires-Dist: jsonschema (==4.24.0)
Requires-Dist: jsonschema-specifications (==2025.4.1)
Requires-Dist: jupyter-core (==5.8.1)
Requires-Dist: kiwisolver (==1.4.8)
Requires-Dist: lxml (==5.1.0)
Requires-Dist: markdown (==3.8.1)
Requires-Dist: markupsafe (==3.0.2)
Requires-Dist: matplotlib (==3.10.3)
Requires-Dist: more-itertools (==10.7.0)
Requires-Dist: morph-kgc (==2.8.1)
Requires-Dist: nbformat (==5.10.4)
Requires-Dist: nltk (==3.9.1)
Requires-Dist: numpy (==1.26.4)
Requires-Dist: packaging (==25.0)
Requires-Dist: pandas (==2.3.0)
Requires-Dist: pillow (==11.2.1)
Requires-Dist: platformdirs (==4.3.8)
Requires-Dist: pluggy (==1.6.0)
Requires-Dist: pyahocorasick (==2.2.0)
Requires-Dist: pyoxigraph (==0.3.22)
Requires-Dist: pyparsing (==3.2.3)
Requires-Dist: pyproject-hooks (==1.2.0)
Requires-Dist: pystache (==0.6.8)
Requires-Dist: pytest (==7.4.4)
Requires-Dist: python-dateutil (==2.9.0.post0)
Requires-Dist: pytz (==2025.2)
Requires-Dist: pyyaml (==6.0.2)
Requires-Dist: rdflib (==7.1.4)
Requires-Dist: rdflib-jsonld (==0.6.2)
Requires-Dist: referencing (==0.36.2)
Requires-Dist: regex (==2024.11.6)
Requires-Dist: requests (==2.32.4)
Requires-Dist: rpds-py (==0.25.1)
Requires-Dist: ruamel-yaml (==0.18.14)
Requires-Dist: ruamel-yaml-clib (==0.2.12)
Requires-Dist: scikit-learn (==1.3.2)
Requires-Dist: scipy (==1.15.3)
Requires-Dist: six (==1.17.0)
Requires-Dist: somef (==0.9.11)
Requires-Dist: soupsieve (==2.7)
Requires-Dist: tabulate (==0.9.0)
Requires-Dist: textblob (==0.17.1)
Requires-Dist: textsearch (==0.0.24)
Requires-Dist: threadpoolctl (==3.6.0)
Requires-Dist: toml (==0.10.2)
Requires-Dist: tomli (==2.2.1)
Requires-Dist: tqdm (==4.67.1)
Requires-Dist: traitlets (==5.14.3)
Requires-Dist: typeguard (==4.4.4)
Requires-Dist: typing-extensions (==4.14.0)
Requires-Dist: tzdata (==2025.2)
Requires-Dist: urllib3 (==2.5.0)
Requires-Dist: validators (==0.22.0)
Requires-Dist: xgboost (==2.1.4)
Project-URL: Homepage, https://github.com/oeg-upm/rsfc
Description-Content-Type: text/markdown

[![DOI](https://zenodo.org/badge/993095977.svg)](https://doi.org/10.5281/zenodo.16531481) [![Project Status: Active – The project has reached a stable, usable state and is being actively developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active) [![PyPI](https://img.shields.io/pypi/v/rsfc?label=PyPI)](https://pypi.org/project/rsfc/) [![RSFC_Coverage](https://img.shields.io/badge/rsfc-coverage_76%25-green)](./RSFC_REPORT.md)


# Research Software FAIRness Checks (RSFC)

A command line interface to automatically evaluate the fairness of a Github or Gitlab repository.

**Authors**: Daniel Garijo, Andrés Montero


## Features

Given a repository URL, RSFC will perform a series of checks based on a list of research software quality indicators (RSQI). The RSQIs currently covered by the package are:

- software_has_license
- software_has_citation
- has_releases
- repository_workflows
- version_control_use
- requirements_specified
- software_documentation
- persistent_and_unique_identifier
- descriptive_metadata
- software_tests
- archived_in_software_heritage
- versioning_standards_use
- support_issue_tracking
- has_contribution_guidelines

For more information about these RSQIs, you can check https://github.com/EVERSE-ResearchSoftware/indicators. We have plans to implement all of the RSQIs available in that repository.


## Available tests

RSFC offers a catalogue of its tests that you can check [here](https://oeg-upm.github.io/rsfc/doc/catalog.html#test)

**Note**: The short names stated in the catalogue will be the identifiers needed to run single-test assessments. More information later in the README


## Requirements

Python 3.10.8 or higher

Dependencies are available in the requirements.txt or pyproject.toml file located in the root of the repository

## Install from PyPI

Just run in your terminal the following command:

```
pip install rsfc
```

## Install from Github with Poetry

To install the package, first clone the repository in your machine.
This project uses Poetry for dependency and environment management.

```
git clone https://github.com/oeg-upm/rsfc.git
```

Go to the project's root directory

```
cd rsfc
```

Install Poetry (if you haven’t already)

```
curl -sSL https://install.python-poetry.org | python3 -
```

Make sure Poetry is available in your PATH

```
poetry --version
```

Create the virtual environment and install dependencies

```
poetry install
```

Activate the virtual environment (Optional)

```
source $(poetry env info --path)/bin/activate
```

Your terminal prompt should now show something like:

```
(rsfc-py3.11) your-user@your-machine rsfc %
```

With virtual environment activated you can tried like this:

```
rsfc --help
```

Without poetry virtual environment activated you need to use the poetry run:

```
poetry run rsfc --help
```

## Usage

Before anything, RSFC uses SOMEF internally. If this is your first time working with somef, you should run the following command in the root directory of the project:

```
somef configure -a
```

Now, you can use the package by running if you activated the poetry env

```
rsfc --repo <repo_url>
```

or like this without the poetry env

```
poetry run rsfc --repo <repo_url>
```

If you want the output in OSTrails format, you can use the following flag

```
rsfc --repo <repo_url> --ftr
```

And additionally, if you want to run only one test, you can indicate the test identifier when running RSFC like this

```
rsfc --repo <repo_url> --id <test_id>
```

RSFC also offers the possibility of using a personal Github token to avoid a rate limit issue with the Github API

```
rsfc --repo <repo_url> -t <token>
```

## RSFC Badge

Below the output table you will find a README badge that states what the total FAIR coverage you got in your assessment. It is already adapted to Markdown so you will just need to copy it.

### How is the coverage calculated?

The coverage is simply the rounded average percentage of the total tests passed. For example, if you passed 20 tests, the coverage will be (20/33)*100 = 61%

## Docker installation

RSFC also offers a Dockerfile which you can build using the following commmand:

```
docker build -t --no-cache -t rsfc-docker .
```

For comodity, we provide a bash script that runs the container along with the necessary configurations. To execute it just run

```
./run_rsfc.sh --repo <repo_url> [--ftr] [--id <test_id>] [-t <token>]
```

The parameters used for the script are the same as if you executed RSFC normally

# RSFC GitHub Action

This repository provides a **reusable GitHub Action** to run RSFC on a given repository.

## Workflows

There are two key workflows:

- **`run-rsfc.yml`**:  
  Defines the main RSFC execution logic.  
  Note: This workflow cannot be triggered directly because it uses `on: workflow_call`.  
  It is designed to be reusable and must be invoked from another workflow.

- **`use-rsfc.yml`**:  
  A workflow file that triggers `run-rsfc.yml`. 
  It must be placed in each repository that you want to analyze, since the repository where `use-rsfc.yml` is hosted is the one that will be processed.  
  No additional inputs are required because the repository context is automatically passed by the `call`. 
  This workflow can be triggered manually (`workflow_dispatch`) or automatically (e.g., on `push` events).
  - **Secrets**:  
  - `RSFC_TOKEN` is optional but recommended if you plan to run multiple analyses or expect heavy usage. It allows RSFC to access private repositories and avoid rate limits. 


## Usage

To use RSFC in a repository:

1. Copy `use-rsfc.yml` into `.github/workflows/` of the repository you want to analyze.
2. Ensure that the required secrets are defined (see below).
3. No inputs are needed — the workflow automatically uses the repository it resides in.


## Viewing RSFC Results in a Pull Request

When a Pull Request is opened or updated, the RSFC workflow runs automatically and adds a neutral check named **RSFC Results Summary**.

This check displays:
- the formatted RSFC console output, including the full assessment table  
- a link to the workflow job that executed the analysis  

### Accessing the JSON report

The workflow also generates an artifact named **`rsfc_assessment.json`**.

To download it:
1. Open the **Checks** tab of the Pull Request  
2. Select the job **Run RSFC Analysis**  
3. Download the artifact from the **Artifacts** section  

Example:

```yaml
name: Run RSFC analysis

on:
  workflow_dispatch: 
  pull_request: 
    types: [opened, synchronize, reopened]         

jobs:
  run-rsfc-checks:
    uses: oeg-upm/rsfc/.github/workflows/run-rsfc.yml@main
    with:
      repo_url: https://github.com/${{ github.repository }}
      is_fork: ${{ github.event.pull_request.head.repo.full_name != github.repository }}
      pr_sha: ${{ github.event.pull_request.head.sha }}
    secrets:
      RSFC_TOKEN: ${{ secrets.RSFC_TOKEN }}

