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.7.tar.gz (83.4 kB view details)

Uploaded Source

Built Distribution

salientsdk-0.3.7-py3-none-any.whl (98.8 kB view details)

Uploaded Python 3

File details

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

File metadata

  • Download URL: salientsdk-0.3.7.tar.gz
  • Upload date:
  • Size: 83.4 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.7.tar.gz
Algorithm Hash digest
SHA256 0306e316d7dce2fe1feacc84a3b1baf3ff499f003968e6bfa0ae4f60075bafb0
MD5 b1ed1121f01877d5315d31b86cb49f29
BLAKE2b-256 d166eac602741216d0d87250fc0b83689ed9a9529311ea4703f419736c82224d

See more details on using hashes here.

File details

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

File metadata

  • Download URL: salientsdk-0.3.7-py3-none-any.whl
  • Upload date:
  • Size: 98.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.7-py3-none-any.whl
Algorithm Hash digest
SHA256 8b44aa3d5ac714d0a30e868d4216f8f55de9d22b942e906652c72e0cb642a102
MD5 109d1742dfe7143e0e5f438be8ce9914
BLAKE2b-256 24fafe28fc07a63181426cdc29cf0a02110de522cc5fd976d4821178c8433e24

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