| Title: | Assess the FAIRness of Research Data Objects and Software |
|---|---|
| Description: | A native R implementation of the F-UJI (FAIRsFAIR Research Data Object Assessment) and FRSM (FAIR for Research Software) metrics for evaluating how well a research data object or piece of research software satisfies the FAIR principles (Findable, Accessible, Interoperable, Reusable). The software metrics operationalize the FAIR Principles for Research Software (FAIR4RS) of Chue Hong et al. (2022) <doi:10.15497/RDA00068>. Given a persistent identifier, URL, or code repository, 'rfair' resolves it, harvests metadata from landing pages and registries, and scores it against the FAIRsFAIR metrics of Devaraju and Huber (2020) <doi:10.5281/zenodo.3775793> entirely in R, without requiring an external assessment server. 'rfair' began as a fork of the 'rfuji' F-UJI API client and reimplements the assessment engine natively. |
| Authors: | Ahmad Sofi-Mahmudi [aut, cre] (ORCID: <https://orcid.org/0000-0001-6829-0823>), Steffen Neumann [ctb] (Author of the original rfuji F-UJI API client that rfair grew from), PANGAEA [cph] (Copyright holder of the F-UJI service whose metrics rfair reimplements) |
| Maintainer: | Ahmad Sofi-Mahmudi <[email protected]> |
| License: | GPL-3 |
| Version: | 0.2.0 |
| Built: | 2026-11-18 04:13:41 UTC |
| Source: | https://github.com/choxos/rfair |
Produces a payload matching the upstream F-UJI FAIRResults schema, so the
output can be consumed by tools built for the F-UJI service.
as_fuji_json(x, pretty = TRUE)as_fuji_json(x, pretty = TRUE)
x |
A fair_assessment object. |
pretty |
Whether to pretty-print the JSON. |
A JSON string (class json).
a <- assess_fair("https://doi.org/10.5281/zenodo.8347772") cat(as_fuji_json(a))a <- assess_fair("https://doi.org/10.5281/zenodo.8347772") cat(as_fuji_json(a))
Emits the assessment as W3C Data Quality Vocabulary quality measurements (one
per FAIR category and one per metric) plus a schema.org Rating, the
machine-readable form the F-UJI service publishes, and one FAIR Test Result
per metric test using the OSTrails FAIR Testing Resource vocabulary
(https://w3id.org/ftr/, version 1.3.0): prov:value pass or fail,
ftr:completion, the evidence as ftr:log, and for failed tests the
fair_recommendations() action as an ftr:suggestion. Metrics and tests are
identified within the metric specification (for example
https://doi.org/10.5281/zenodo.6461229#FsF-F1-01MD-1).
as_rdf(x, format = c("jsonld", "turtle"))as_rdf(x, format = c("jsonld", "turtle"))
x |
A fair_assessment object. |
format |
|
A character scalar of serialized RDF.
a <- assess_fair("https://doi.org/10.5281/zenodo.8347772") cat(as_rdf(a))a <- assess_fair("https://doi.org/10.5281/zenodo.8347772") cat(as_rdf(a))
Convert a FAIR assessment to a per-metric data frame.
## S3 method for class 'fair_assessment' as.data.frame(x, ...)## S3 method for class 'fair_assessment' as.data.frame(x, ...)
x |
A |
... |
Ignored. |
A data frame with one row per metric.
Bridges rtransparent and rfair: takes the data/code identifiers
rtransparent extracts from articles (its open_data_links and
open_code_links columns) and scores each against the FAIR metrics. Data
identifiers are scored with the FsF data metrics and code repositories with
the FRSM software metrics.
assess_data_code( x, id_col = NULL, data_metric_version = "0.8", code_metric_version = "0.7_software", data_col = "open_data_links", code_col = "open_code_links", sep = " ; ", quiet = FALSE, workers = 1L, keep = FALSE, previous = NULL, ... )assess_data_code( x, id_col = NULL, data_metric_version = "0.8", code_metric_version = "0.7_software", data_col = "open_data_links", code_col = "open_code_links", sep = " ; ", quiet = FALSE, workers = 1L, keep = FALSE, previous = NULL, ... )
x |
One of: a data frame from |
id_col |
Optional name of a column in |
data_metric_version |
Metric version for data identifiers (default
|
code_metric_version |
Metric version for code repositories (default
|
data_col, code_col
|
Column/element names holding the joined links
(defaults match rtransparent: |
sep |
Separator rtransparent uses to join identifiers (default |
quiet |
If |
workers, keep
|
See |
previous |
Optional result of an earlier |
... |
Passed to |
A data frame with one row per (article, kind, identifier): source
(article id), kind ("data" or "code"), and the columns of
assess_fair_batch(). Each unique identifier is assessed once.
assess_fair_batch(), split_identifiers(), assess_fair()
assess_data_code(list(open_data_links = "https://doi.org/10.5281/zenodo.8347772", open_code_links = "https://github.com/pangaea-data-publisher/fuji"))assess_data_code(list(open_data_links = "https://doi.org/10.5281/zenodo.8347772", open_code_links = "https://github.com/pangaea-data-publisher/fuji"))
Resolves a persistent identifier or URL, harvests its metadata, and scores it against the FAIRsFAIR metrics, entirely in R.
assess_fair( id, metric_version = "0.8", use_datacite = TRUE, metadata_service_endpoint = NULL, metadata_service_type = metadata_service_types(), test_debug = FALSE, resolve = TRUE, timeout = 15, use_headless = FALSE, max_time = Inf )assess_fair( id, metric_version = "0.8", use_datacite = TRUE, metadata_service_endpoint = NULL, metadata_service_type = metadata_service_types(), test_debug = FALSE, resolve = TRUE, timeout = 15, use_headless = FALSE, max_time = Inf )
id |
A persistent identifier or URL (DOI, Handle, ARK, URN, ...). |
metric_version |
Metric version to use (see |
use_datacite |
Whether to query DataCite for registry metadata. |
metadata_service_endpoint |
Optional URL of an additional metadata
document to harvest, or a ready protocol query URL (for example an OAI-PMH
|
metadata_service_type |
Type hint for |
test_debug |
If |
resolve |
If |
timeout |
Per-request timeout in seconds. |
use_headless |
If |
max_time |
Time budget for the whole assessment, in seconds. Metadata
sources not yet harvested when it runs out are skipped and listed in
|
A fair_assessment object.
a <- assess_fair("https://doi.org/10.5281/zenodo.8347772") summary(a)a <- assess_fair("https://doi.org/10.5281/zenodo.8347772") summary(a)
Runs assess_fair() over a vector of identifiers and returns one tidy row per
identifier (deduplicated). Failures are captured in an error column rather
than aborting the batch.
assess_fair_batch( ids, metric_version = "0.8", quiet = FALSE, workers = 1L, keep = FALSE, previous = NULL, ... )assess_fair_batch( ids, metric_version = "0.8", quiet = FALSE, workers = 1L, keep = FALSE, previous = NULL, ... )
ids |
Character vector of DOIs, PIDs, URLs, or identifiers.org codes. |
metric_version |
Metric version (see |
quiet |
If |
workers |
Number of identifiers to assess at once. Values above 1 fork
worker processes with |
keep |
If |
previous |
Optional result of an earlier |
... |
Passed to |
A data frame with one row per unique identifier: identifier,
metric_version, scheme, is_persistent, resolved (did the
identifier resolve; NA when resolve = FALSE), http_status,
resolved_url, fair_percent, F, A, I, R, maturity, n_pass,
n_metrics, error.
assess_data_code(), assess_fair()
res <- assess_fair_batch(c("https://doi.org/10.5281/zenodo.8347772", "geo:GSE12345"), keep = TRUE) attr(res, "assessments")[[1]]res <- assess_fair_batch(c("https://doi.org/10.5281/zenodo.8347772", "geo:GSE12345"), keep = TRUE) attr(res, "assessments")[[1]]
Classify the access level and sensitivity of a data object.
classify_access(access_level = NULL, urls = NULL, source = NULL)classify_access(access_level = NULL, urls = NULL, source = NULL)
access_level |
Access codes/URIs harvested from metadata (character). |
urls |
Landing-page and content URLs (for host-based detection). |
source |
Optional source name/id. |
A list with access (public/embargoed/restricted/closed/
metadataonly/unknown), controlled_access, sensitive, the matched
reusabledata record (or NULL), and a human-readable note.
classify_access(access_level = "info:eu-repo/semantics/openAccess")$accessclassify_access(access_level = "info:eu-repo/semantics/openAccess")$access
fair_assessment objectassess_fair() returns an object of class fair_assessment. It has
print(), format(), summary(), and
as.data.frame() methods, and can be exported
with as_fuji_json() and as_rdf().
Useful list elements: summary (F/A/I/R scores), results (per-metric),
metadata (harvested), reuse (license reusability), access
(access/sensitivity), identifier_hygiene, resolution (the identifier's
resolution attempt: url, final_url, HTTP status, ok, error), and
harvest_errors (metadata sources that failed, for example a GitHub rate
limit), and software (the repository signals the FRSM software metrics
score, when a code repository was harvested), and reference_data (when and
from which F-UJI release the bundled reference tables were built).
resolved_url is NA when the identifier did not resolve.
Joins two assessments, for example of the same record before and after a metadata fix, or under two metric versions, and reports what changed.
fair_compare(a, b, level = c("metric", "test"))fair_compare(a, b, level = c("metric", "test"))
a, b
|
fair_assessment objects; |
level |
|
A data frame with the identifiers, earned_a, earned_b,
status_a, status_b, delta (earned_b - earned_a), and change
("improved", "worse", "same", or "only in a"/"only in b"), in
the metric order of a.
data(fair_example) fixed <- fair_example fixed$results[[1]]$score$earned <- fixed$results[[1]]$score$total fair_compare(fair_example, fixed)[1:3, ]data(fair_example) fixed <- fair_example fixed$results[[1]]$score$earned <- fixed$results[[1]]$score$total fair_compare(fair_example, fixed)[1:3, ]
A stored fair_assessment object, produced by running
assess_fair() on a stable Zenodo deposit
(doi:10.5281/zenodo.8347772). It is bundled so the plotting examples and
the vignette("illustrating-fairness") can run offline and reproducibly,
without contacting any network service.
data(fair_example)data(fair_example)
A fair_assessment object (a list with S3 class fair_assessment);
see fair_assessment for its structure.
The verbose per-test debug log has been stripped to keep the installed size
small; all elements used by the print, summary, as.data.frame,
plot, as_fuji_json(), and as_rdf() methods are
retained.
assess_fair() on doi:10.5281/zenodo.8347772,
rebuilt by data-raw/06-build-example-assessment.R.
assess_fair(), plot.fair_assessment()
data(fair_example) summary(fair_example) plot(fair_example)data(fair_example) summary(fair_example) plot(fair_example)
The canonical FAIR (sub)principles.
fair_principles(category = NULL)fair_principles(category = NULL)
category |
Optional filter: one or more of "F", "A", "I", "R". |
A data frame with id, label, category, definition, and uri
(the w3id.org/fair/principles term URI).
fair_principles() fair_principles("R")fair_principles() fair_principles("R")
Lists every metric test that did not pass, with one concrete action a data curator or software maintainer can take to pass it (for example "Add a license to the metadata as a URL or SPDX identifier"). Actions come from a curated table covering the FsF data metrics and the FRSM software metrics; tests of legacy metric versions fall back to a metric-level action.
fair_recommendations(x)fair_recommendations(x)
x |
A fair_assessment from |
A data frame, most valuable fixes first, with columns
metric_identifier, test_identifier, test_name, points (the score
passing the test would add, given the metric's cap), and recommendation.
fair_compare() to check the effect of a fix.
data(fair_example) head(fair_recommendations(fair_example))data(fair_example) head(fair_recommendations(fair_example))
Computes the three "FAIR+" indicators proposed by Haendel and colleagues in the Monarch Initiative / NCATS TransMed response to the NIH RFI on biomedical repository value metrics (doi:10.5281/zenodo.203295), building on the (Re)usable Data Project (doi:10.1371/journal.pone.0213090). They extend FAIR with the provenance and legal dimensions that automated FAIR tools usually miss: whether data is Traceable (provenance, attribution), Licensed (clearly documented and actually reusable), and Connected (qualified links to related entities).
fair_tlc(x)fair_tlc(x)
x |
A fair_assessment from |
A data frame with columns dimension, indicator, met (logical),
and detail, plus a "source" attribute citing the framework.
a <- assess_fair("https://doi.org/10.5281/zenodo.8347772") fair_tlc(a)a <- assess_fair("https://doi.org/10.5281/zenodo.8347772") fair_tlc(a)
The canonical FAIR4RS (sub)principles that rfair's software metrics (the FRSM
metric set, metric_version = "0.7_software") operationalize. Principle
statements are reproduced from the FAIR4RS Principles version 1.0.
fair4rs_principles(category = NULL)fair4rs_principles(category = NULL)
category |
Optional filter: one or more of |
A data frame with id, category, statement (the principle text),
and explanation. The four foundational F/A/I/R statements and the source
citation are attached as the "foundational" and "source" attributes.
Chue Hong, N. P., Katz, D. S., Barker, M., Lamprecht, A.-L., Martinez, C., Psomopoulos, F. E., Harrow, J., Castro, L. J., Gruenpeter, M., Martinez, P. A., Honeyman, T., et al. (2022). FAIR Principles for Research Software (FAIR4RS Principles) (1.0). Research Data Alliance. doi:10.15497/RDA00068
fair_principles() for the data FAIR principles.
fair4rs_principles() fair4rs_principles("R")fair4rs_principles() fair4rs_principles("R")
rfair scores the FRSM software metrics from repository signals (file names,
API fields, metadata files). These heuristics have not yet been validated
against expert judgement, so every FRSM result carries
evidence_type = "heuristic". frsm_agreement() supports that validation:
raters judge each FRSM test for a sample of repositories (start from the
template in system.file("extdata", "frsm_validation_template.csv", package = "rfair")), and the function compares rfair's pass/fail result with
the raters' majority judgement, test by test.
frsm_agreement(assessments, ratings)frsm_agreement(assessments, ratings)
assessments |
A list of fair_assessment objects scored with an FRSM
metric version (for example the |
ratings |
A data frame with columns |
A data frame with one row per test: test_identifier, n (rated
items), rfair_pass and rater_pass (pass rates), agreement (share of
items where rfair matches the raters' majority), kappa (Cohen's kappa of
rfair against the majority), and rater_kappa (kappa between the first two
raters, when two or more rated the test). Ties between raters are dropped.
data(fair_example) ratings <- data.frame(identifier = fair_example$id, test_identifier = "FsF-F1-01MD-1", rater = "A", passed = TRUE) # fair_example is a data assessment, so this only shows the shape of the output frsm_agreement(fair_example, ratings)data(fair_example) ratings <- data.frame(identifier = fair_example$id, test_identifier = "FsF-F1-01MD-1", rater = "A", passed = TRUE) # fair_example is a data assessment, so this only shows the shape of the output frsm_agreement(fair_example, ratings)
Resolves the identifier scheme, normalizes it, and constructs its resolver
URL, mirroring IdentifierHelper in F-UJI.
id_parse(idstring)id_parse(idstring)
idstring |
A DOI, Handle, ARK, URN, UUID, identifiers.org PID, or URL. |
A list with identifier, normalized_id, identifier_url,
preferred_schema, identifier_schemes, and is_persistent.
id_parse("https://doi.org/10.5281/zenodo.8347772")$preferred_schemaid_parse("https://doi.org/10.5281/zenodo.8347772")$preferred_schema
Check an identifier against best-practice / hygiene heuristics.
identifier_hygiene(id)identifier_hygiene(id)
id |
A persistent identifier or URL. |
A list with identifier, scheme, is_persistent, hygiene_ok,
and a character vector of issues.
identifier_hygiene("RRID:MGI:5577054")$issues identifier_hygiene("https://doi.org/10.5281/zenodo.8347772")$hygiene_okidentifier_hygiene("RRID:MGI:5577054")$issues identifier_hygiene("https://doi.org/10.5281/zenodo.8347772")$hygiene_ok
Opens an interactive app to assess the FAIRness of a research data object and explore the per-metric results, license reusability, access/sensitivity, and identifier hygiene.
launch_rfair(...)launch_rfair(...)
... |
Passed to |
Runs the app (called for its side effect); invisibly NULL.
if (interactive()) { launch_rfair() }if (interactive()) { launch_rfair() }
Goes beyond detecting that a license exists: classifies whether it actually permits redistribution, commercial use, and derivative works, and whether it meets the Open Definition. Useful for judging real reusability of data.
license_reuse(license)license_reuse(license)
license |
A license name, SPDX id, or URL (e.g. from an assessment). |
A list describing the license's reuse terms, including is_open,
permits_redistribution, permits_commercial, permits_derivatives,
requires_attribution, requires_share_alike, category, and note.
license_reuse("https://creativecommons.org/licenses/by-nc-nd/4.0/")$is_open license_reuse("CC-BY-4.0")$is_openlicense_reuse("https://creativecommons.org/licenses/by-nc-nd/4.0/")$is_open license_reuse("CC-BY-4.0")$is_open
Draws a compact, readable scorecard of a fair_assessment
using base graphics (no extra package dependencies). It is the quickest way to
see an assessment: a horizontal progress bar per FAIR category (or per
metric), each annotated with its score and CMMI maturity level. See
vignette("illustrating-fairness") for worked examples.
## S3 method for class 'fair_assessment' plot( x, type = c("category", "metric", "sunburst"), colors = .fair_cat_colors, show_maturity = (match.arg(type) == "category"), main = NULL, ... )## S3 method for class 'fair_assessment' plot( x, type = c("category", "metric", "sunburst"), colors = .fair_cat_colors, show_maturity = (match.arg(type) == "category"), main = NULL, ... )
x |
A |
type |
What to draw. |
colors |
Named character vector of category fill colors, with names
|
show_maturity |
Logical; annotate each bar with its maturity level.
Defaults to |
main |
Title. Defaults to the resolved identifier (or the input id). |
... |
Ignored (for S3 method compatibility). |
x, invisibly. Called for the side effect of drawing a plot.
assess_fair(), summary.fair_assessment(), fair_example
# A stored example assessment (no network needed): data(fair_example) plot(fair_example) plot(fair_example, type = "metric") plot(fair_example, type = "sunburst")# A stored example assessment (no network needed): data(fair_example) plot(fair_example) plot(fair_example, type = "metric") plot(fair_example, type = "sunburst")
For data metrics (FsF-*) this returns the FAIR Guiding Principle definition;
for software metrics (FRSM-*) it returns the corresponding FAIR4RS Principle
statement (see fair4rs_principles()).
principle_definition(metric_identifier)principle_definition(metric_identifier)
metric_identifier |
A metric identifier (e.g. "FsF-F1-01MD" or "FRSM-17-R1.2"). |
The principle's definition string, or NA.
principle_definition("FsF-R1.1-01M") principle_definition("FRSM-17-R1.2")principle_definition("FsF-R1.1-01M") principle_definition("FRSM-17-R1.2")
Look up a (Re)usable Data Project curation for a source.
reusabledata_rating(urls = NULL, source = NULL)reusabledata_rating(urls = NULL, source = NULL)
urls |
Character vector of URLs (e.g. landing page, content URLs). |
source |
Optional source name or id to match. |
The matched curation record (list) or NULL.
reusabledata_rating(source = "dbgap")$license_typereusabledata_rating(source = "dbgap")$license_type
List the metric versions bundled with rfair.
rfair_metric_versions()rfair_metric_versions()
Character vector of available metric versions (e.g. "0.8").
rfair_metric_versions()rfair_metric_versions()
rtransparent joins the data/code identifiers it extracts with " ; ". This
splits such a string (or a vector of them) into a trimmed character vector,
dropping empties. rfair's id_parse() already understands the forms it emits
(doi.org URLs, repository URLs, and identifiers.org prefix:accession codes
such as geo:GSE123 or bioproject:PRJEB123).
split_identifiers(x, sep = " ; ")split_identifiers(x, sep = " ; ")
x |
A character vector of identifier strings (each possibly joined). |
sep |
Separator used to join identifiers (default |
A character vector of individual identifiers.
split_identifiers("https://doi.org/10.5061/dryad.x ; geo:GSE12345")split_identifiers("https://doi.org/10.5061/dryad.x ; geo:GSE12345")
Summarize a FAIR assessment as an F/A/I/R score table.
## S3 method for class 'fair_assessment' summary(object, ...)## S3 method for class 'fair_assessment' summary(object, ...)
object |
A |
... |
Ignored. |
A data frame with earned, total, percent, and maturity per FAIR category and overall.