# Intended Use
The Salient SDK is a python convenience wrapper around Salient Predictions' customer-facing
[web API](https://api.salientpredictions.com/v2/documentation/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:
```bash
python3 --version
```
To get version 3.11:
```bash
# 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
```
```bash
# 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:
```bash
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:
```bash
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:
```bash
python3 -m salientsdk version
```
To verify that you can access Salient's API, use the limited universal credentials `testusr` and `testpwd` to log in:
```bash
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.
```bash
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.
```bash
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.
```python
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](api.md).
# Examples
The [examples](https://github.com/Salient-Predictions/salientsdk/tree/main/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](https://salient-predictions.github.io/salientsdk/LICENSE/).
Copyright 2024 [Salient Predictions](https://www.salientpredictions.com/)
Raw data
{
"_id": null,
"home_page": "https://salientpredictions.com",
"name": "salientsdk",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.11",
"maintainer_email": null,
"keywords": "weather, climate, forecasting, sdk, salient, s2s",
"author": "Salient Predictions",
"author_email": "help@salientpredictions.com",
"download_url": "https://files.pythonhosted.org/packages/a5/61/45166c26ce85f3e39777c48503bd6d84012bcb6818ed64f1e46515e84221/salientsdk-0.1.6.tar.gz",
"platform": null,
"description": "\n# Intended Use\n\nThe Salient SDK is a python convenience wrapper around Salient Predictions' customer-facing \n[web API](https://api.salientpredictions.com/v2/documentation/api/). It also contains utility functions for manipulating and analyzing the data delivered from the API.\n\n# Setting up the SDK\n\n## Prerequisites \n\nThe Salient SDK requires Python 3.11 to use. If you have Python installed, you can check your version with:\n\n```bash\npython3 --version\n```\n\nTo get version 3.11:\n\n```bash\n# Ubuntu:\nsudo apt update\nsudo apt install software-properties-common\nsudo add-apt-repository ppa:deadsnakes/ppa\nsudo apt update\nsudo apt install python3.11\n```\n\n```bash\n# macOS:\n/bin/bash -c \"$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)\"\nbrew update\nbrew install python@3.11\n```\n\n## Installing the SDK\n\nThe easiest way to get the Salient SDK is to install it like any other package:\n\n```bash\npip install salientsdk --upgrade\n# to verify version with\npip show salientsdk\n```\n\n# Usage\n\n## Command Line\n\nThe Salient SDK contains a full command line interface that can access each of the primary\nAPI functions without even opening python. You can get help for all options or specific commands:\n\n```bash\npython3 -m salientsdk --help\npython3 -m salientsdk forecast_timeseries --help\n```\n\nTo verify that you are set up to execute the sdk, ask for its version number:\n\n```bash\npython3 -m salientsdk version\n```\n\nTo verify that you can access Salient's API, use the limited universal credentials `testusr` and `testpwd` to log in:\n\n```bash\npython3 -m salientsdk login -u testusr -p testpwd\n```\n\nTo 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.\n\n```bash\npython3 -m salientsdk data_timeseries -lat 42 -lon -73 -fld all --start 2020-01-01 --end 2020-12-31 -u testusr -p testpwd\n```\n\nTo 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.\n\n```bash\npython3 -m salientsdk forecast_timeseries -lat 42 -lon -73 --variable precip --timescale seasonal --date 2020-01-01 -u username -p password\n```\n\n\n\n## Via Python\n\nIn a python 3.11 script, this example code will login and request a historical ERA5 data timeseries.\n\n```python\nimport salientsdk as sk\nimport xarray as xr\nimport netcdf4\n\nsession = sk.login(\"testusr\",\"testpwd\")\nhistory = sk.data_timeseries(loc = Location(lat=42, lon=-73), field=\"all\", variable=\"temp\", session=session)\nprint(xr.open_file(history))\n```\n\nNote that this example uses the limited credentials `testusr` and `testpwd`. To access the full capabilities of your license, use your Salient-provided credentials.\n\nSee all available functions in the [API Reference](api.md).\n\n# Examples\n\n\nThe [examples](https://github.com/Salient-Predictions/salientsdk/tree/main/examples) directory contains `ipynb` notebooks to help you get started with common operations. \n\nThese examples are also included within the package. You can list their file locations with:\n\n```\npython3 -m salientsdk examples\n```\n\n\n# License\n\nThis SDK is licensed for use by Salient customers [details](https://salient-predictions.github.io/salientsdk/LICENSE/).\n\n\nCopyright 2024 [Salient Predictions](https://www.salientpredictions.com/)\n",
"bugtrack_url": null,
"license": "LicenseRef-Custom",
"summary": "Salient Predictions Software Development Kit",
"version": "0.1.6",
"project_urls": {
"Documentation": "https://sdk.salientpredictions.com",
"Homepage": "https://salientpredictions.com",
"License": "https://sdk.salientpredictions.com/LICENSE/",
"Repository": "https://github.com/Salient-Predictions/salientsdk"
},
"split_keywords": [
"weather",
" climate",
" forecasting",
" sdk",
" salient",
" s2s"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "2426a60a9533d098a9377c204527c15ad1cb2577442a054a26ed51d3a48d4119",
"md5": "c61800ba567b413a5645fc44f0e5c0f6",
"sha256": "6e2ead1a20fda73247c8ece9d0ff14b9b6bc97240518f68be44ae702b10eb75b"
},
"downloads": -1,
"filename": "salientsdk-0.1.6-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c61800ba567b413a5645fc44f0e5c0f6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.11",
"size": 47510,
"upload_time": "2024-05-03T12:49:25",
"upload_time_iso_8601": "2024-05-03T12:49:25.137640Z",
"url": "https://files.pythonhosted.org/packages/24/26/a60a9533d098a9377c204527c15ad1cb2577442a054a26ed51d3a48d4119/salientsdk-0.1.6-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a56145166c26ce85f3e39777c48503bd6d84012bcb6818ed64f1e46515e84221",
"md5": "8390d8c7ed4a2e4f127c2d2af30ab6e5",
"sha256": "3e053d2ea25aab915357e66184628d1185c1988dfe3aaedf06d2ec1b75c599f5"
},
"downloads": -1,
"filename": "salientsdk-0.1.6.tar.gz",
"has_sig": false,
"md5_digest": "8390d8c7ed4a2e4f127c2d2af30ab6e5",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.11",
"size": 38813,
"upload_time": "2024-05-03T12:49:26",
"upload_time_iso_8601": "2024-05-03T12:49:26.769820Z",
"url": "https://files.pythonhosted.org/packages/a5/61/45166c26ce85f3e39777c48503bd6d84012bcb6818ed64f1e46515e84221/salientsdk-0.1.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-03 12:49:26",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Salient-Predictions",
"github_project": "salientsdk",
"github_not_found": true,
"lcname": "salientsdk"
}
JSON
