COG-UK Docs

View the Project on GitHub COG-UK/docs

Updated 2020-09-09 by @samstudio8

Accessing metadata through a data view using Ocarina

0. Register for an account via Majora

Read the instructions for how to register

1. Acquire permission to access a data view

A data view is basically a list of metadata fields. If you are granted access to a data view, you can see all of the fields covered by that data view. Every data view is associated with a short name, which we sometimes call a code or Majora data view code (mdv code).

Guidance on how to obtain access to a view is in progress, check back after the consortium agreement has been distributed. This document has been written ahead of time and we are not currently granting permissions to any restricted views. Do not attempt to contact anyone to arrange access at this time.

2. Install the Ocarina client

Ocarina is a command line tool that is used to connect to Majora and perform actions with elevated privileges that are not possible on the website. It is not terribly difficult to use, but ideally you will have used a command line tool before.

You can install the latest version with the Python package manager. You’ll probably want to install it into a conda environment on the shared node.

conda create -n mdv-ocarina python=3.7
conda activate mdv-ocarina
pip install git+https://github.com/samstudio8/ocarina.git

3. Register your Ocarina instance as an OAuth application

You must register an instance of Ocarina with Majora so that it can authenticate as you through OAuth. Read the instructions for registering an application.

4. Set your Ocarina credentials

Create a JSON file in your home directory named .ocarina. Note the starting dot.

{"MAJORA_DOMAIN": "https://majora.covid19.climb.ac.uk/", "MAJORA_USER": "your-username", "MAJORA_TOKEN": "OAUTH", "CLIENT_ID": "your-client-id", "CLIENT_SECRET": "your-client-secret"}

Where:

5. Use Ocarina to request the data from the view

Once this has been set up, you are ready to retrieve data.

ocarina --oauth get dataview --mdv CODE --task-wait --output-table -o my_data.tsv

Replace CODE with the appropriate data view name. Ocarina will reject your request if you attempt to access a data view you do not have permission to view. Use the command exactly as stated (do not skip providing --task-wait) for ease of use.

When you submit this command, you will need to authenticate yourself through the following process:

This is an experimental feature and can change at any time. Please visit #metadata-apis if you have questions or trouble.


Published 2020-09-07. Updated 2020-09-09. Page maintainer @samstudio8.