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

Uploaded Source

Built Distribution

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

Uploaded Python 3

File details

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

File metadata

  • Download URL: salientsdk-0.3.6.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.6.tar.gz
Algorithm Hash digest
SHA256 8e5548d6174048795cf1867ea82ac0fbe9f22f720b33ac50acc1bc33a296b937
MD5 028da3d5037e5c33cc65a24b7f45af19
BLAKE2b-256 10c34787a17342bcb5faaf3d1acfaff881316593b78e082cfd6752cfacc0d18b

See more details on using hashes here.

File details

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

File metadata

  • Download URL: salientsdk-0.3.6-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.6-py3-none-any.whl
Algorithm Hash digest
SHA256 3dbdc91c03093cdca84756ee32957d63592c4e9b9c9e70fd85b204a480300bcf
MD5 42eccaddf3376d3576efd77d1ec74171
BLAKE2b-256 a856c82dae7a4b5ce0f25dec2137800df40d49ce81d13b9d5ec9ff0c1ad77daf

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