PyRAT#

PyRAT is a popular animal facility management software.

To access data in a PyRAT instance via OSCaR, there are some initial setup steps:

Client tokens#

This step should be done by an administrator of your institution’s PyRAT instance, and only needs to be done once.

You will need to contact Scionics (the creators of PyRAT) to approve access for OSCaR:

  • Ask them to setup a new API client called ‘OSCaR’ on your PyRAT server; they should send you a ‘client token’.

  • The new API client will appear under ADMINISTRATION > API in PyRAT, and an administrator will need to enable it from there.

User tokens#

Once the client is enabled, any user can request a user token by logging into PyRAT, going to ADMINISTRATION > API and clicking the ‘Request access’ button on the OSCaR row.

Providing tokens to OSCaR#

Once all tokens have been created (as above), they can be provided to OSCaR by setting the following environment variables:

  • PYRAT_URL: the url of the PyRAT instance you want to access

  • PYRAT_CLIENT_TOKEN: the client token sent to you by Scionics

  • PYRAT_USER_TOKEN: the user token created via ‘Request access’ in PyRAT

Set these variables however you prefer - just make sure they are never checked in to version control (tokens should be kept secret). One convenient method is to create a .env file and use python-dotenv to read them. We’ll show an example of that below.

Pulling data from the PyRAT API#

See the docs for the api module, for full details of how OSCaR can pull data from the PyRAT API. Below, we’ll walk through an example of retrieving data for a named line.

First, let’s set our environment variables. We’ll use python-dotenv for this, but feel free to use whatever method you like.

We can create a .env file containing:

PYRAT_URL=https://my-pyrat-instance
PYRAT_CLIENT_TOKEN=my-client-token
PYRAT_USER_TOKEN=my-user-token

You would need to update the values to match your PyRAT instance.

Then load it with:

from dotenv import load_dotenv

load_dotenv()

Now we can fetch data via OSCaR. Let’s retrieve all available animals from a given line:

from oscar_colony.colony_management.pyrat.api import get_pyrat_data
animal_data = get_pyrat_data(
    species_name="Mouse",
    line_name="MY-LINE",
)

As this could be a very large amount of data, it is returned as a generator of pandas dataframes that we can loop through to process one-by-one.

Standardising data from the PyRAT API#

Now we have the data, it must be converted into OSCaR’s standard table format.

We can do this with:

import pandas as pd
from oscar_colony.colony_management.pyrat.standardise import standardise_pyrat_csv

standardised_dfs = []

# Loop through the returned animal data, and standardise each
for animal_df in animal_data:
    standard_df = standardise_pyrat_csv(animal_df)
    standardised_dfs.append(standard_df)

# Join all the standardised dataframes into one
standard_df = pd.concat(standardised_dfs)

See the docs for the standardise module, for full details of how data is standardised.