salientsdk 0.1.6

Salient Predictions Software Development Kit

Intended Use

The Salient SDK is a python convenience wrapper around Salient Predictions' customer-facing
web API. It also contains utility functions for manipulating and analyzing the data delivered from the API.

Setting up the SDK

Prerequisites

The Salient SDK requires Python 3.11 to use. If you have Python installed, you can check your version with:

python3 --version

To get version 3.11:

# Ubuntu:
sudo apt update
sudo apt install software-properties-common
sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt update
sudo apt install python3.11

# macOS:
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
brew update
brew install python@3.11

Installing the SDK

The easiest way to get the Salient SDK is to install it like any other package:

pip install salientsdk --upgrade
# to verify version with
pip show salientsdk

Usage

Command Line

The Salient SDK contains a full command line interface that can access each of the primary API functions without even opening python. You can get help for all options or specific commands:

python3 -m salientsdk --help
python3 -m salientsdk forecast_timeseries --help

To verify that you are set up to execute the sdk, ask for its version number:

python3 -m salientsdk version

To verify that you can access Salient's API, use the limited universal credentials testusr and testpwd to log in:

python3 -m salientsdk login -u testusr -p testpwd

To verify that you can download data from Salient, try the testusr/testpwd credentials to download historical data with the data_timeseries function. This will download a NetCDF file to your current directory and display its contents.

python3 -m salientsdk data_timeseries -lat 42 -lon -73 -fld all --start 2020-01-01 --end 2020-12-31 -u testusr -p testpwd

To test that your specific Salient-issued credentials are functioning properly, try them with the forecast_timeseries function. Replace username and password in the example below with your credentials. Note that you may need to change the location (North America) and timescale (seasonal) if your license does not include them.

python3 -m salientsdk forecast_timeseries -lat 42 -lon -73 --variable precip --timescale seasonal --date 2020-01-01 -u username -p password

Via Python

In a python 3.11 script, this example code will login and request a historical ERA5 data timeseries.

import salientsdk as sk
import xarray as xr
import netcdf4

session = sk.login("testusr","testpwd")
history = sk.data_timeseries(loc = Location(lat=42, lon=-73), field="all", variable="temp", session=session)
print(xr.open_file(history))

Note that this example uses the limited credentials testusr and testpwd. To access the full capabilities of your license, use your Salient-provided credentials.

See all available functions in the API Reference.

Examples

The examples directory contains ipynb notebooks to help you get started with common operations.

These examples are also included within the package. You can list their file locations with:

python3 -m salientsdk examples

License

This SDK is licensed for use by Salient customers details.

Copyright 2024 Salient Predictions