Summary and Setup

This Library Carpentry lesson introduces people working in library- and information-related roles to working with data in OpenRefine. At the conclusion of the lesson you will understand what the OpenRefine software does and how to use the OpenRefine software to work with data files.

Prerequisites

To complete this lesson you will need to:

Install OpenRefine or use it through a cloud service
Download a data file
Use a supported browser

See below for more information.

Getting ready

You need to install OpenRefine and download a data file to follow this lesson.

Installing and running OpenRefine

OpenRefine is a free, open-source Java application. You can download OpenRefine from http://openrefine.org/download.html. This lesson has been tested with the 3.7.7 version of OpenRefine.

Packages are available on https://openrefine.org/download.html for Windows, macOS, and Linux. Please download the latest stable version, choosing the option for your operating system. Current versions for Windows (with embedded Java) and Mac include everything you need to run OpenRefine. For Windows you can choose between an installer (.exe) file or a zip-archive. The Linux version requires a “Java Runtime Environment” (JRE) installed on your system (see notes below).

If you are using an older version of OpenRefine, it is recommended you upgrade to the latest tested version.

Please follow OpenRefine’s manual to install and run it.

When running OpenRefine, initially a command line window will open. This is a window with a black background. As OpenRefine runs, lines of text will appear in the command line window. Then the Open Refine interface will open in your default web browser. You do not need to interact with the command line window. Leave it open in the background, and work on datasets in your web browser.

Notes:

When you download OpenRefine for Windows or Linux from the address above, you are downloading an archive file (zip or tar), unless you are chosing the installer for windows. To install OpenRefine unzip the downloaded file to a permanent location on your computer. This can be to a personal directory or to an applications or software directory - OpenRefine should run wherever you put the unzipped folder. The location has to be a “local” drive as problems have been reported trying to run OpenRefine from a Network drive.
The versions for Windows and Mac include Java as part of the package. You do not need to install Java if you use one of these archives. This is the preferred method on Windows and Mac systems.
On Linux a “Java Runtime Environment” (JRE) will be required to run OpenRefine. If you do not already have JRE or JDK installed on your system, most distribution repositories will contain OpenJRE / OpenJDK packages. Install the default version available from your distribution. For example, on Ubuntu/Debian: sudo apt install default-jre.
OpenRefine does not support Internet Explorer. Please use Firefox, Microsoft Edge, Chrome or Safari instead.

OpenRefine cloud services

If you are unable to install OpenRefine (due to IT restrictions, for example), please try openrefineder using MyBinder. It’s free to use without registration, but it’s the older OpenRefine 3.5.0, restricted to 1-2 GB RAM, and the server will be deleted after 10 minutes of inactivity.

Downloading the data

You can download doaj-article-sample.csv, which is a csv file that will open in a new browser tab. Be sure to right click or control click in order to save the file (NOTE: In Safari, right click and select download linked file; in Chrome and Firefox, right click and select save link as…). Make a note of the location (i.e. the folder, your desktop) to which you save the file.

Exiting OpenRefine

To exit OpenRefine, close all the browser tabs or windows, then navigate to the command line window. To close this window and ensure OpenRefine exits properly, hold down [control] and press [c] on your keyboard. This will save all changes to your projects.

Getting help

If you encounter problems installing or running OpenRefine, a good source of support is the OpenRefine mailing list and user forum. Include your operating system when searching to find the most relevant answers for your issue, such as threads related to Windows, macOS, or Linux.

You may also want to check the Stack Overflow OpenRefine tag.

There are also general and specialist tutorials about using OpenRefine available on the web, including: