Skip to content

Latest commit

 

History

History
297 lines (253 loc) · 13.7 KB

fair-software.md

File metadata and controls

297 lines (253 loc) · 13.7 KB
Raw

FAIR Software & Data

The following material is paraphrased from the NIST-internal Data Sponsorship repository by @tkphd.

Table of Contents

FAIR principles

What does FAIR even mean? The following sections reproduce the summary from Go FAIR, based on the original FAIR paper.

Think you know FAIR? Please use this tool to check your awareness!

Findable

The first step in (re)using data is to find them. Metadata and data should be easy to find for both humans and computers. Machine-readable metadata are essential for automatic discovery of datasets and services, so this is an essential component of the FAIRification process.

  1. (Meta)data are assigned a globally unique and persistent identifier
  2. Data are described with rich metadata (defined by R1 below)
  3. Metadata clearly and explicitly include the identifier of the data they describe
  4. (Meta)data are registered or indexed in a searchable resource

Accessible

Once the user finds the required data, she/he/they need to know how can they be accessed, possibly including authentication and authorisation.

  1. (Meta)data are retrievable by their identifier using a standardised communications protocol
    1. The protocol is open, free, and universally implementable
    2. The protocol allows for an authentication and authorisation procedure, where necessary
  2. Metadata are accessible, even when the data are no longer available

Interoperable

The data usually need to be integrated with other data. In addition, the data need to interoperate with applications or workflows for analysis, storage, and processing.

  1. (Meta)data use a formal, accessible, shared, and broadly applicable language for knowledge representation.
  2. (Meta)data use vocabularies that follow FAIR principles
  3. (Meta)data include qualified references to other (meta)data

Reusable

The ultimate goal of FAIR is to optimise the reuse of data. To achieve this, metadata and data should be well-described so that they can be replicated and/or combined in different settings.

  1. (Meta)data are richly described with a plurality of accurate and relevant attributes
    1. (Meta)data are released with a clear and accessible data usage license
    2. (Meta)data are associated with detailed provenance
    3. (Meta)data meet domain-relevant community standards

Make It FAIR in Ten Easy Steps

[Library Carpentry][lc] has a summary of 10 "easy" steps to make your software FAIR (PDF). An annotated list follows. Note that while the list is software-centric, it applies equally to data.

  1. Create a description of your software.
    Write this in README.md with supporting tables, charts, images, etc. Include its dependencies, installation instructions, and citations of any work it builds upon.
  2. Register your software in a software registry.
    MIDAS is the go-to where Data Sponsorship is concerned, but is not the only option.
  3. Use a unique and persistent identifier for your software.
    Any registry compliant with NIST O 5702 will provide you with a persistent handle.
  4. Make sure that people can download your software.
    If the data is fire- or pay-walled, provide an alternative site. Wherever your data lives, check back from time to time to make sure the links are still valid.
  5. Explain the functionality of your software.
    Write this into a "Usage" section of README.md, or similar, with example of how to configure, launch, and interact with the software, with examples of output to be expected.
  6. Use standard (community-agreed) formats for inputs and outputs.
    While open standards are preferred, if a proprietary format is the lingua franca of the field, focus on that. Create open versions if possible.
  7. Document your software.
    This goes beyond README.md and in-line comments. Place documentation, or its build scripts, in a folder named doc with its own README.md describing how to build the docs and what to expect.
  8. Give your software a license.
    If all members of the development team are Federal employees, use the standard NIST Disclaimer of Copyright and Warranty for your LICENSE.md. Otherwise, decide on an appropriate license.
  9. State how to cite your software.
    This can be done in README.md, or as a separate CITATION.md using a BiBTeX-styled code block.
  10. Follow best practices for software development.
    Broadly speaking, this starts with version control using git or similar, linting your code, and following some type of branching workflow when multiple developers are involved. The regularly-scheduled Software Carpentry workshops at NIST teach the basics of some of these concepts.

What's good enough?

Good enough practices in scientific computing is an excellent paper outlining what you need to do to produce good science in a FAIR frame of mind.

tl;dr follows.

Data management

  1. Save the raw data.
  2. Ensure that raw data are backed up in more than one location.
  3. Create the data you wish to see in the world.
  4. Create analysis-friendly data.
  5. Record all the steps used to process data.
  6. Anticipate the need to use multiple tables, and use a unique identifier for every record.
  7. Submit data to a reputable DOI-issuing repository so that others can access and cite it.

Software

  1. Place a brief explanatory comment at the start of every program.
  2. Decompose programs into functions.
  3. Be ruthless about eliminating duplication.
  4. Always search for well-maintained software libraries that do what you need.
  5. Test libraries before relying on them.
  6. Give functions and variables meaningful names.
  7. Make dependencies and requirements explicit.
  8. Do not comment and uncomment sections of code to control a program's behavior.
  9. Provide a simple example or test data set.
  10. Submit code to a reputable DOI-issuing repository.

Collaboration

  1. Create an overview of your project.
  2. Create a shared "to-do" list for the project.
  3. Decide on communication strategies.
  4. Make the license explicit.
  5. Make the project citable.

Project organization

  1. Put each project in its own directory, which is named after the project.
  2. Put text documents associated with the project in the doc directory.
  3. Put raw data and metadata in a data directory and files generated during cleanup and analysis in a results directory.
  4. Put project source code in the src directory.
  5. Put external scripts or compiled programs in the bin directory.
  6. Name all files to reflect their content or function.

Keeping track of changes

  1. Back up (almost) everything created by a human being as soon as it is created.
  2. Keep changes small.
  3. Share changes frequently.
  4. Create, maintain, and use a checklist for saving and sharing changes to the project.
  5. Store each project in a folder that is mirrored off the researcher's working machine.
  6. Add a file called CHANGELOG.md to the project's docs subfolder.
  7. Copy the entire project whenever a significant change has been made.
  8. Use a version control system.

Manuscripts

  1. Write manuscripts using online tools with rich formatting, change tracking, and reference management.
  2. Write the manuscript in a plain text format that permits version control.

Links

Some more general FAIR resources:

Institutional guidance: