Quickstart#

Get started with the twinLab Python Interface.

Requirements#

A Python version between 3.8 and 3.12 is required to run twinLab.

To check your Python version, you can either use your shell directly or use a Python script.

Type the following into your shell:

python --version

Execute the following in a Python script or notebook:

import sys
sys.version_info

Note

We recommend managing your Python packages with Python virtual environments. See more here.

Installation#

  1. Open a terminal

  2. Create a directory

Create a folder/directory where you want to install twinLab. Then, set that folder/directory as your current one.

mkdir my_project
cd my_project

  1. Install twinLab

In your newly created directory, install twinLab from PyPI.

pip install twinlab

After installation, you’ll need to add your user details, including your API key, in order to access twinLab capabilities.

Need an API key?

To access an API key, and for more information on licensing, get in touch and let our solution engineers set you up with a free trial.

Configure your API key#

There are two options for configuring your user details: creating a .env file, which contains your details, or providing them manually within Python scripts or notebooks.

If ever you forget or misplace your API key, you can find your user details through the Portal.

Once this .env file has been set, this will enable your username and API key to be read from any script run in the subsequent directory tree. Note that your username is usually an email address.

echo "TWINLAB_USER=<your_username>" >> .env
echo "TWINLAB_API_KEY=<your_api_key>" >> .env

echo TWINLAB_USER=<your_username> >> .env
echo TWINLAB_API_KEY=<your_api_key> >> .env

echo "TWINLAB_USER=<your_username>" >> .env
echo "TWINLAB_API_KEY=<your_api_key>" >> .env

echo "TWINLAB_USER=<your_username>" >> .env
echo "TWINLAB_API_KEY=<your_api_key>" >> .env

You can check that the .env file has been created successfully using the following:

ls -a .env

You should see the .env file listed.

If twinLab is unable to locate your .env file, you may receive the following error:

{message: 'Unable to find user with API key: `None`'}

Or

Error: permission denied

This could be for a few reasons:

  • The .env file does not exist (see the steps above).

  • The .env file does not have the correct information (see the steps above).

  • The .env file does not exist in the current working directory or above.

  • Your Windows user account doesn’t have read permissions on the .env file and the directory where the Python code is being executed.

  • Your Windows user account doesn’t have execute permissions on the directory where the Python code is being executed.

  • The .env file doesn’t exist on the same drive as the directory where the Python code is being executed.

Setting your user details within a script will mean that you don’t have to store them on your computer’s operating system.

import twinlab as tl

tl.set_user("<your_username>")
tl.set_api_key("<your_api_key>")

Executing this code should return something like this:

====== TwinLab Client Initialisation ======
Version     : 2.10.0
User        : user@digilab.co.uk
Server      : https://twinlab.digilab.co.uk/v3
Environment : <my_project_directory>/.env

Warning

While we offer the flexibility to utilize the set_user() and set_api_key() functionality, this should be used with care, so as to not to publicly expose your API key when sharing files. Ensure you replace <your_username> and <your_api_key> with the API key you received in the Portal. Be aware of any blank spaces in the words between the quotation marks, as this can cause errors when using twinLab.

Run an example#

Use the following example script to get you started:

# Import pandas as well
import pandas as pd

# Create a dataset and upload to twinLab cloud
df = pd.DataFrame({"X": [1, 2, 3, 4], "y": [1, 4, 9, 16]})
dataset = tl.Dataset("test-data")
dataset.upload(df)

# Train a machine-learning emulator for the data
emulator = tl.Emulator("test-emulator")
emulator.train(dataset=dataset, inputs=["X"], outputs=["y"])

# Evaluate the emulator on some unseen data
sample_points = pd.DataFrame({"X": [1.5, 2.5, 3.5]})
df_mean, df_std = emulator.predict(df=sample_points)

# Explore the results
print(df_mean)
print(df_std)

Use longer-form examples to test out twinLab with our Examples.

On this page
Show Source