ASReml for Python Quick Guide

This guide describes how to get started with ASReml for Python.

Requirements

ASReml for Python requires:

Python 3.8 or later
pip (included with most Python installations; run python -m pip --version in a terminal to check)
A valid ASReml license (contact VSN International for details)

Installation

Note

All commands below are run in a terminal.

Step 1: Create Virtual Environment (optional)

Create a virtual environment in a directory of choice:

python -m venv my_env
source ./my_env/bin/activate

Step 2: Install ASReml for Python

The package can be installed directly from the repository using pip. Choose the variant that best suits your needs:

Basic installation (no plotting support):

python -m pip install --extra-index-url https://products.vsni.co.uk/asreml/python-package asreml

With basic plotting support (excludes exporting plots to file):

python -m pip install --extra-index-url https://products.vsni.co.uk/asreml/python-package "asreml[plots]"

Everything, including exporting plots to file (recommended):

python -m pip install --extra-index-url https://products.vsni.co.uk/asreml/python-package "asreml[full]"

Verify the installation:

python -m pip show asreml

Step 3: Activate License

If license activation is required, run the following command:

python <LOCATION>/asreml/get_license.py YYYY-YYYY-YYYY-YYYY

Where:

<LOCATION> is the location into which the asreml package was installed, as shown when running pip show asreml.
YYYY-YYYY-YYYY-YYYY is your license key.

This should create a .lic file under VSNi/enterprise_licenses in the current user’s home directory.

Try loading ASReml:

python -c "import asreml"

If the license is not found, set the VSN_USER_LICPATH environment variable to the directory containing the license file:

export VSN_USER_LICPATH="PATH_TO_LICENSE"

To make it permanent, append it to your shell’s startup file, ~/.bashrc on most Linux systems:

echo 'export VSN_USER_LICPATH="PATH_TO_LICENSE"' >> ~/.bashrc

or ~/.zshrc on macOS:

echo 'export VSN_USER_LICPATH="PATH_TO_LICENSE"' >> ~/.zshrc

Try loading ASReml again after setting the environment variable.

Note

All commands below are run in a PowerShell terminal.

Step 1: Create Virtual Environment (optional)

Create a virtual environment in a directory of choice:

python -m venv my_env
.\my_env\Scripts\Activate.ps1

Step 2: Install ASReml for Python

The package can be installed directly from the repository using pip. Choose the variant that best suits your needs:

Basic installation (no plotting support):

python -m pip install --extra-index-url https://products.vsni.co.uk/asreml/python-package asreml

With basic plotting support (excludes exporting plots to file):

python -m pip install --extra-index-url https://products.vsni.co.uk/asreml/python-package "asreml[plots]"

Everything, including exporting plots to file (recommended):

python -m pip install --extra-index-url https://products.vsni.co.uk/asreml/python-package "asreml[full]"

Verify the installation:

python -m pip show asreml

Step 3: Activate License

If license activation is required, run the following command:

python <LOCATION>\asreml\get_license.py YYYY-YYYY-YYYY-YYYY

Where:

<LOCATION> is the location into which the asreml package was installed, as shown when running pip show asreml.
YYYY-YYYY-YYYY-YYYY is your license key.

This should create a .lic file under VSNi/enterprise_licenses in the current user’s home directory.

Try loading ASReml:

python -c "import asreml"

If the license is not found, set the VSN_USER_LICPATH environment variable to the directory containing the license file:

$env:VSN_USER_LICPATH = "PATH_TO_LICENSE"

To make it permanent:

[Environment]::SetEnvironmentVariable("VSN_USER_LICPATH", "PATH_TO_LICENSE", "User")

Try loading ASReml again after setting the environment variable.

Syntax

The main function signature is as follows:

asreml(
    data: Union[pandas.DataFrame, dict],
    response: Union[str, list[str]],
    fixed: Optional[str] = None,
    random: Optional[str] = None,
    sparse: Optional[str] = None,
    residual: Optional[str] = None,
    family: Optional[str] = None,
    weights: Optional[str] = None,
    predict: Optional[Union[list, dict]] = None,
    vpredict: Optional[Union[str, Dict[str, str]]] = None,
    options: Optional[dict] = None,
    fit_options: Optional[dict] = None,
) -> ASReml

The main methods of the ASReml class:

ASReml.summary()
ASReml.trace()
ASReml.coefficients()
ASReml.fitted()
ASReml.residuals()
ASReml.wald()
ASReml.predict()
ASReml.vpredict()
ASReml.plot()

For additional documentation:

import asreml
help(asreml)

Example Usage

This example demonstrates how to fit a mixed model using ASReml.

The data (oats.csv) has 6 variables and 72 rows:

blocks: Complete field replicates with 6 levels
nitrogen: Nitrogen application with 4 levels
subplots: Sub-plot within whole-plots with 4 levels
variety: Variety names with 3 levels
wplots: Whole-plots with 3 levels
yield: Grain yield

First, load required libraries and data:

import pandas as pd
from asreml import asreml, define_categorical_variables

oats = pd.read_csv("oats.csv")
print(oats)

Define categorical variables from the data; this is equivalent to defining factors in R:

oats = define_categorical_variables(
    oats, variables=["blocks", "nitrogen", "subplots", "variety", "wplots"]
)

Fit a model for yield, requesting predictions for nitrogen:variety interactions:

oats_asr = asreml(
    response="yield",
    fixed="nitrogen*variety",
    random="blocks/wplots",
    predict={"classify": "nitrogen:variety"},
    data=oats,
)

Print the summary, Wald test and predictions:

oats_asr.summary()
oats_asr.wald()
oats_asr.predict()