# Salient Predictions SDK
## 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.
## Installing the SDK
The Salient SDK is a Python package that depends on Python v3.11 and installs from [PyPI](https://pypi.org/project/salientsdk):
```bash
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](#getting-python-311).
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.
```bash
# 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.
```bash
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.
```bash
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.
```bash
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:
```bash
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:
```bash
# 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:<br>
Kernel > Change Kernel > salient_env > Select
- Add your username/password credentials to the "login" step in the first cell:<br>
`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:<br>
`loc=sk.Location(region=["<region1>", "<region2>"]),`<br>
`variable=["<var1>", <var2>"],`
- Run > Run All Cells
- This will generate files in the `hindcast_summary_example` directory:<br>
`hindcast_summary_<hash>.csv` the source validation files from the API.<br>
`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.
```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).
## 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:
```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
```
## 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/60/07/d0dcadfb86909c7027dcb7369a2420154450edf767e5014eebcc8f955207/salientsdk-0.3.12.tar.gz",
"platform": null,
"description": "# Salient Predictions SDK\n\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## Installing the SDK\n\nThe Salient SDK is a Python package that depends on Python v3.11 and installs from [PyPI](https://pypi.org/project/salientsdk):\n\n```bash\npython3 --version | grep -q '3.11' && echo \"Py OK\" || echo \"Need Py 3.11\"\npip install salientsdk poetry --upgrade\npip show salientsdk\n```\n\nIf you \"need Py 3.11\", follow the instructions in [Getting Python 3.11](#getting-python-311).\n\nThe `install` will also get `poetry`, which `salientsdk` uses to manage dependencies.\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.\n\n```bash\n# Get the version number:\nsalientsdk version\n# Show help for all available commands:\nsalientsdk --help\n```\n\nTo 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.\n\n```bash\nsalientsdk login -u testusr -p testpwd\n# If successful, the command should return a Session object:\n# <requests.sessions.Session object at 0x12cf45590>\n```\n\nTo 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.\n\n```bash\nsalientsdk data_timeseries -fld all \\\n-lat 42 -lon -73 \\\n--start 2020-01-01 --end 2020-12-31 \\\n-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\nsalientsdk forecast_timeseries --variable precip \\\n-lat 42 -lon -73 \\\n--timescale seasonal --date 2020-01-01 \\\n-u username -p \"password\"\n```\n\n### Example Notebooks\n\nThe 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:\n\n```bash\nmkdir salient_env && cd salient_env\n# show all of the available examples:\nsalientsdk examples\n# Copy the \"hindcast_summary\" example to the current directory:\nsalientsdk examples | grep \"hindcast_summary\" | xargs -I {} cp {} .\n```\n\n`salientsdk` uses the `poetry` dependency manager to set up a virtual environment with all the dependencies needed to run the examples:\n\n```bash\n# Clear out any poetry projects that may already exist\nrm -f pyproject.toml\n# Create a new poetry project\npoetry init --no-interaction\n# Get the latest version of the salient sdk\npoetry add jupyter salientsdk@latest\n# Create a virtual environment with the right dependencies\npoetry run ipython kernel install --user --name=\"salient_env\"\n# Open the notebook and get it ready to run\npoetry run jupyter notebook hindcast_summary.ipynb\n```\n\nOnce the hindcast_summary notebook launches in your browser:\n\n- If \"salient env\" is not already selected as a kernel:<br>\n Kernel > Change Kernel > salient_env > Select\n- Add your username/password credentials to the \"login\" step in the first cell:<br>\n `sk.login(<username>, <password>, verbose=False)`\n- 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:<br>\n `loc=sk.Location(region=[\"<region1>\", \"<region2>\"]),`<br>\n `variable=[\"<var1>\", <var2>\"],`\n- Run > Run All Cells\n- This will generate files in the `hindcast_summary_example` directory:<br>\n `hindcast_summary_<hash>.csv` the source validation files from the API.<br>\n `hindcast_summary_transposed.csv` a combined version of the results\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## Installation Help\n\n### Getting Python 3.11\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## License\n\nThis SDK is licensed for use by Salient customers [details](https://salient-predictions.github.io/salientsdk/LICENSE/).\n\nCopyright 2024 [Salient Predictions](https://www.salientpredictions.com/)\n",
"bugtrack_url": null,
"license": "LicenseRef-Custom",
"summary": "Salient Predictions Software Development Kit",
"version": "0.3.12",
"project_urls": {
"Documentation": "https://salient-predictions.github.io/salientsdk",
"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": "f75fe5dc43d602b8063c388646700f474f0cdd24a8928909313571e1d7ccb01f",
"md5": "0e5bba248635c17d39cce9dce49a61eb",
"sha256": "10d3d9e306174f3d5ba8e51f696982bf01df8f5c1397d2cbb8f7141f269006c4"
},
"downloads": -1,
"filename": "salientsdk-0.3.12-py3-none-any.whl",
"has_sig": false,
"md5_digest": "0e5bba248635c17d39cce9dce49a61eb",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.11",
"size": 151238,
"upload_time": "2024-11-22T18:11:52",
"upload_time_iso_8601": "2024-11-22T18:11:52.509644Z",
"url": "https://files.pythonhosted.org/packages/f7/5f/e5dc43d602b8063c388646700f474f0cdd24a8928909313571e1d7ccb01f/salientsdk-0.3.12-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "6007d0dcadfb86909c7027dcb7369a2420154450edf767e5014eebcc8f955207",
"md5": "b94dc03b5ea1cd23b9575007e081b538",
"sha256": "14884903850940dd861ffe9fd5ec5457ca955b0ef18b33c9a716682c98c5aad5"
},
"downloads": -1,
"filename": "salientsdk-0.3.12.tar.gz",
"has_sig": false,
"md5_digest": "b94dc03b5ea1cd23b9575007e081b538",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.11",
"size": 131117,
"upload_time": "2024-11-22T18:11:54",
"upload_time_iso_8601": "2024-11-22T18:11:54.236051Z",
"url": "https://files.pythonhosted.org/packages/60/07/d0dcadfb86909c7027dcb7369a2420154450edf767e5014eebcc8f955207/salientsdk-0.3.12.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-22 18:11:54",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Salient-Predictions",
"github_project": "salientsdk",
"github_not_found": true,
"lcname": "salientsdk"
}
JSON
