Skip to main content

Salient Predictions Software Development Kit

Project description

Salient Predictions SDK

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.

Installing the SDK

The Salient SDK is a Python package that depends on Python v3.11 and installs from PyPI:

python3 --version | grep -q '3.11' && echo "Py OK" || echo "Need Py 3.11"
pip install salientsdk poetry --upgrade
pip show salientsdk

If you "need Py 3.11", follow the instructions in Getting Python 3.11.

The install will also get poetry, which salientsdk uses to manage dependencies.

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.

# Get the version number:
salientsdk version
# Show help for all available commands:
salientsdk --help

To verify that you can access Salient's API, use the limited test* credentials to log in. If you see errors or warnings relating to VERIFY SSL you may need to adjust your firewall settings.

salientsdk login -u testusr -p testpwd
# If successful, the command should return a Session object:
# <requests.sessions.Session object at 0x12cf45590>

To verify that you can download data from Salient, try these 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.

salientsdk data_timeseries -fld all \
-lat 42 -lon -73 \
--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.

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

Example Notebooks

The package ships with examples that show salientsdk in action. You can list the file locations and copy them to a working directory for use. Let's work with the hindcast_summary notebook example:

mkdir salient_env && cd salient_env
# show all of the available examples:
salientsdk examples
# Copy the "hindcast_summary" example to the current directory:
salientsdk examples | grep "hindcast_summary" | xargs -I {} cp {} .

salientsdk uses the poetry dependency manager to set up a virtual environment with all the dependencies needed to run the examples:

# Clear out any poetry projects that may already exist
rm -f pyproject.toml
# Create a new poetry project
poetry init --no-interaction
# Get the latest version of the salient sdk
poetry add jupyter salientsdk@latest
# Create a virtual environment with the right dependencies
poetry run ipython kernel install --user --name="salient_env"
# Open the notebook and get it ready to run
poetry run jupyter notebook hindcast_summary.ipynb

Once the hindcast_summary notebook launches in your browser:

  • If "salient env" is not already selected as a kernel:
    Kernel > Change Kernel > salient_env > Select
  • Add your username/password credentials to the "login" step in the first cell:
    sk.login(<username>, <password>, verbose=False)
  • The notebook assumes you are licenced for regions north-america and europe, and variables temp and precip. If you are not, change cell 2 to generate a request consistent with your licensing:
    loc=sk.Location(region=["<region1>", "<region2>"]),
    variable=["<var1>", <var2>"],
  • Run > Run All Cells
  • This will generate files in the hindcast_summary_example directory:
    hindcast_summary_<hash>.csv the source validation files from the API.
    hindcast_summary_transposed.csv a combined version of the results

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.

Installation Help

Getting Python 3.11

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

License

This SDK is licensed for use by Salient customers details.

Copyright 2024 Salient Predictions

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

salientsdk-0.3.9.tar.gz (99.5 kB view details)

Uploaded Source

Built Distribution

salientsdk-0.3.9-py3-none-any.whl (115.8 kB view details)

Uploaded Python 3

File details

Details for the file salientsdk-0.3.9.tar.gz.

File metadata

  • Download URL: salientsdk-0.3.9.tar.gz
  • Upload date:
  • Size: 99.5 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.8.4 CPython/3.11.5 Linux/6.5.0-1025-azure

File hashes

Hashes for salientsdk-0.3.9.tar.gz
Algorithm Hash digest
SHA256 31895a5e7dadf755b2c3edd8b07873dc8c8e145d388696589a445c2097aced34
MD5 5e09228f7c24e2f0d2b8627923477f2f
BLAKE2b-256 ea6710709e23320a41b18bb72ea9240b9b9c707a348c86a54436d9ceefb67dfd

See more details on using hashes here.

File details

Details for the file salientsdk-0.3.9-py3-none-any.whl.

File metadata

  • Download URL: salientsdk-0.3.9-py3-none-any.whl
  • Upload date:
  • Size: 115.8 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.8.4 CPython/3.11.5 Linux/6.5.0-1025-azure

File hashes

Hashes for salientsdk-0.3.9-py3-none-any.whl
Algorithm Hash digest
SHA256 aa230d9ac6560bd564eab59c62bfaeb11a552b060d37a381aa663123c0118648
MD5 dcc1dd5b068f2f3adb49e0d4e76308c2
BLAKE2b-256 104ee62523a4de056d3fa8e2ea45a45b64bac1131289d1e5579b2adb9100b781

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page