You should first install rse.
This will place the executable
rse in your bin folder, which is the client
for searching software, starting the interface, or otherwise interacting with
your software repository.
- How does it work?: How does rse work?
- Concepts: What are common rse concepts?
- Quick Start: to install, create, and add software to an RSEPedia database.
- Configuration your rse install, for example, choosing a database backend.
- Environment variables can be set to control functionality.
- Commands including run, re-run, list (ls), get, and others.
- Parsers know how to parse some remote software repository
- Scrapers discover new software repositories via resource APIs.
- Dashboard: an annotation interface for criteria and taxonomy
- Containers for pre-built environments to use rse.
- API application programming interface to expose software, criteria, and taxonomy
- Annotation of criteria and taxonomy items for research software
How does it work?
As we’ve mentioned, the research software encyclopedia is intended to provide a database for you to manage and assess research software. The interaction looks like the following:
+--------+ | | +-->+ zenodo | | | | | +--------+ +--> rse update... | | +--------------+ +--------+ | +--------+ +------------+ +--> rse get... | | | | | | | | | | | rse get... +--->+ parser +------->+ github |--->| database +--+--> rse ls... | | | | | | | | | | +--------------+ +--------+ | +--------+ +------------+ +--> rse search... | . | | . +--> rse exists... | +-------+ | | | | +--> rse start... +-->+ other | | | | +--> rse annotate... +-------+
In the above diagram, we start with a rse get command, where we provide a namespaced
github.com/user/repository) and it get’s parsed by a particular
parser (e.g., github, or zenodo). The parser interacts with our database of choice
(filesystem, sqlite, mysql, or postgres) to save custom metadata for the repository,
which minimally includes a timestamp it was obtained and a url for it. The
user can then query rse to get, list, update, or export a set of software or a particular
repository. There is also an interactive web interface to do the same.
The following concepts might not be specific to rse, but are defined as the following in the context of rse:
A parser is a controller to handle taking a uri (unique resource identifier) and returning metadata about the software. Minimally, a url is required to direct a user where to inspect it. The Research Software Encyclopedia uses a set of base parsers (version control systems) as sources of truth, and also provides additional parsers for the user to interact with if desired (e.g., Zenodo).
A scraper is intended to run at some regular interface to update the research software encyclopedia with entries from some external resource.
Is a Flask application that comes with rse, exposed via
rse start, that provides
an table to manage and otherwise interact with tasks.
Is the process of answering questions about one or more repositories in a software encyclopedia, and also indicating category membership. This can be done interactively in a web interface (under development) or via the command line.
A database is the backend database used by the research software encyclopedia to keep track of your software. The default (and dummy) database is the filesystem. If you want to use a different database backend then you need to install the sqlachemy database dependency and then specify using sqlite for your configuration by doing the following:
$ pip install -e .[all] # local install from repository $ pip install -e rse[all] # install from pypi $ rse config --database sqlite
A quick example of installing the software and creating a database of research software with two entries from GitHub might look like the following:
$ pip install rse[all] $ rse init $ rse add https://github.com/citation-file-format/cff-converter-python $ rse ls 1 github/citation-file-format/cff-converter-python $ rse add https://gitlab.com/jspaaks/howfairis-livetest $ rse ls 1 github/citation-file-format/cff-converter-python 2 gitlab/jspaaks/howfairis-livetest $ tree database database ├── github │ └── citation-file-format │ └── cff-converter-python │ └── metadata.json └── gitlab └── jspaaks └── howfairis-livetest └── metadata.json $ cat database/github/citation-file-format/cff-converter-python/metadata.json
And then you might want to look at Annotation or criteria or taxonomy items, Scrapers to automate adding software to your database, or generating a Dashboard for others to explore.
This code is licensed under the Mozilla, version 2.0 or later LICENSE.
You might next want to browse tutorials available.