This repository contains Python utility scripts written by ROR staff and third parties that work with the ROR API or ROR data to perform various useful functions such as matching other organization identifiers to ROR IDs. Please note that these scripts are not officially supported by ROR and may be out of date with current versions of the ROR API or schema. They are provided here primarily to serve as models for those who wish to write their own ROR-related Python scripts.
List of scripts
- Contributor: Ramon Granell of FAIRsharing
matching_name_shortname.py- Accepts a CSV list of organization names, matches them to ROR records, and produces a TSV file that includes Levenshtein distances between the text strings.
matching_urls.py- Accepts a CSV list of organization home pages, matches them to ROR records, and produces a TSV file that includes Levenshtein distances between the text strings.
map-ringgold-via-wikidata.py- Accepts a single ROR ID as input and suggests the corresponding Ringgold ID when the ROR ID's corresponding Wikidata page includes a Ringgold ID.
match-other-ids-to-ror.py- Accepts a CSV list of other organization IDs (e.g., GRID, ISNI) as input and returns a CSV with corresponding ROR IDs.
search-by-name-affiliation.py- Searches the ROR API for organization names from a CSV file using the ROR API ?affiliation endpoint. Does not return corresponding ROR IDs.
search-by-name-query- Searches the ROR API for organization names from a CSV file using the ROR API ?query endpoint. Does not return corresponding ROR IDs.
To contribute one or more scripts to this repository, please open a pull request structured as follows:
- Place all your contributions in a directory with a name that indicates the source and/or function of the scripts: e.g.,
- Include a README file, your scripts, and any subdirectories in your directory. Optionally, you may also include a LICENSE file; otherwise, your contributions will be covered by the top-level LICENSE in ror-utilities. We also encourage you to include sample files that can be used to test your scripts.
- In the README file in your directory, provide clear and detailed usage instructions and list any required Python packages. You may also include your name, GitHub handle, and contact information if you wish.
- If your scripts require Python packages that are not part of the Python Standard Library, include a
requirements.txtfile to your directory in the format
requests==2.27.1). You can use pipreqs to generate requirements.txt automatically.
- Install and configure Python on your machine
- Clone/download this repository to your computer, ex
git clone email@example.com:ror-community/ror-utilities.git
- Move to the directory you just cloned, ex
Create a virtual environment & install packages
Create a Python virtual environment using venv
python3 -m venv ~/venv
The venv path and directory name can be anything you like, ex
~/ror-utilities, but it's best to put it outside your ror-utilities repository so that you don't accidentally commit it.
Activate the virtual environment
The virtual environment name should now appear in your command prompt, ex
(venv). If you used a different path or directory name in step 1, replace
~/venv with that path/directory name.
Move to the directory that the script you'd like to run is located in and add required packages into the virtual environment
cd general-scripts python -m pip install -r requirements.txt
Note that each directory inside ror-utilities has its own requirements.txt file, so you will need to perform the steps above inside each directory you would like to run scripts from.
When you are finished, deactivate the virtual environment (you can reactivate it by running the command in step 2 above)