salientsdk 0.1.3__tar.gz

salientsdk-0.1.3/PKG-INFO

@@ -0,0 +1,105 @@
+Metadata-Version: 2.1
+Name: salientsdk
+Version: 0.1.3
+Summary: Salient Predictions Software Development Kit
+Home-page: https://salientpredictions.com
+License: docs/LICENSE.md
+Keywords: weather,climate,forecasting,sdk,salient,s2s
+Author: Salient Predictions
+Author-email: help@salientpredictions.com
+Requires-Python: >=3.11,<4.0
+Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Dist: h5netcdf (>=1.3.0,<2.0.0)
+Requires-Dist: netCDF4 (>=1.6.5,<2.0.0)
+Requires-Dist: pandas (>=2.2.1,<3.0.0)
+Requires-Dist: requests (>=2.31.0,<3.0.0)
+Requires-Dist: toml (>=0.10.2,<0.11.0)
+Requires-Dist: xarray[h5netcdf] (>=2024.2.0,<2025.0.0)
+Project-URL: Documentation, https://sdk.salientpredictions.com
+Project-URL: Repository, https://github.com/Salient-Predictions/salientsdk
+Description-Content-Type: text/markdown
+
+
+# Intended Use
+
+The Salient SDK is a 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
+python --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
+```
+
+
+
+
+
+
+
+# Usage
+
+To access the Salient API you will need a `username` and `password` provided by
+your Salient representative.  The universal credentials `testusr` and `testpwd` 
+have limited permissions for testing and validation purposes:
+
+```bash
+python -m salientsdk.data_timeseries -lat 42 -lon -73 -fld all --start 2020-01-01 --end 2020-12-31 -u testusr -p testpwd
+```
+
+In a python script:
+
+```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")
+print(xr.open_file(history))
+```
+
+See all available functions in the [API Reference](api.md).
+
+The [examples](https://github.com/Salient-Predictions/salientsdk/tree/main/examples) directory contains `ipynb` notebooks to help you get started with common operations. 
+
+# License
+
+This SDK is licensed for use by Salient customers [details](LICENSE.md).
+
+
+Copyright 2024 [Salient Predictions](https://www.salientpredictions.com/)
+

salientsdk-0.1.3/docs/index.md

@@ -0,0 +1,80 @@
+
+# Intended Use
+
+The Salient SDK is a 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
+python --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
+```
+
+
+
+
+
+
+
+# Usage
+
+To access the Salient API you will need a `username` and `password` provided by
+your Salient representative.  The universal credentials `testusr` and `testpwd` 
+have limited permissions for testing and validation purposes:
+
+```bash
+python -m salientsdk.data_timeseries -lat 42 -lon -73 -fld all --start 2020-01-01 --end 2020-12-31 -u testusr -p testpwd
+```
+
+In a python script:
+
+```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")
+print(xr.open_file(history))
+```
+
+See all available functions in the [API Reference](api.md).
+
+The [examples](https://github.com/Salient-Predictions/salientsdk/tree/main/examples) directory contains `ipynb` notebooks to help you get started with common operations. 
+
+# License
+
+This SDK is licensed for use by Salient customers [details](LICENSE.md).
+
+
+Copyright 2024 [Salient Predictions](https://www.salientpredictions.com/)

salientsdk-0.1.3/pyproject.toml

@@ -0,0 +1,114 @@
+[tool.poetry]
+name = "salientsdk"
+version = "0.1.3"
+description = "Salient Predictions Software Development Kit"
+authors = ["Salient Predictions <help@salientpredictions.com>"]
+license = "docs/LICENSE.md"
+readme = "docs/index.md"
+keywords = ["weather","climate","forecasting","sdk","salient","s2s"]
+homepage = "https://salientpredictions.com"
+documentation = "https://sdk.salientpredictions.com"
+repository = "https://github.com/Salient-Predictions/salientsdk"
+
+[tool.poetry.dependencies]
+# use "poetry add <packagename>" to edit this list
+h5netcdf = "^1.3.0"
+netCDF4 = "^1.6.5"
+pandas = "^2.2.1"
+python = "^3.11"
+requests = "^2.31.0"
+toml = "^0.10.2"
+xarray = {extras = ["h5netcdf"], version = "^2024.2.0"}
+
+[tool.poetry.group.dev.dependencies]
+# use "poetry add --dev <packagename>" to edit this list
+google = "^3.0.0"
+google-cloud-secret-manager = "^2.19.0"
+markdown-include = "^0.8.1"
+mkdocs = "^1.5.3"
+mkdocs-material = "^9.5.15"
+mkdocs-jupyter = "^0.24.6"
+mkdocs-glightbox = "^0.3.7"
+mkdocstrings = "^0.24.1"
+mkdocstrings-python = "^1.9.0"
+nbmake = "^1.5.3"
+pydoc-markdown = "^4.8.2"
+pytest = "^8.1.1"
+pytest-cov = "^5.0.0"
+ruff = "^0.3.4"
+
+[build-system]
+# poetry build
+# -- to publish to test pypi --
+# poetry config repositories.testpypi https://test.pypi.org/legacy/
+# poetry config pypi-token.testpypi <your-test-pypi-token>
+# poetry publish -r testpypi
+# pip install --index-url https://test.pypi.org/simple/ salientsdk
+# -- to publish to the canonical pypi --
+# poetry config pypi-token.pypi <your-pypi-token>
+# poetry publish
+# pip install salientsdk
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.black]
+line-length = 99
+exclude = ""
+
+# Make sure that isort and black play nicely together
+# (both are part of our precommit)
+[tool.isort]
+profile = "black"
+
+# These are the ruff settings that are explicitly supplied to pre-commit for enforcement
+[tool.ruff]
+# Should match black
+line-length = 99
+# Assume Python 3.9
+target-version = "py39"
+
+# Currently enforce:
+# C90=mccabe-complexity
+# E722=do not use base except
+# Eventually add: F=pyflakes, E=pycodestyle, I=isort, W=pycodestyle warnings, N=pep8-naming, D=pydocstyle
+select = ["C90", "E722","D"]
+ignore = []
+
+[tool.ruff.mccabe]
+max-complexity = 25
+
+[tool.ruff.pydocstyle]
+convention = "google"
+
+[tool.pytest.ini_options]
+filterwarnings = [
+   "ignore::DeprecationWarning"
+]
+
+
+
+
+#[project]
+#name = "salientsdk"
+#version = "0.1.2"
+#dynamic = ["dependencies"]
+#license = {file = "docs/LICENSE.md"}
+#readme = "docs/index.md"
+#description="Salient Predictions Software Development Kit"
+#requires-python=">=3.11"
+#keywords = ["weather","climate","forecasting","sdk","salient","s2s"]
+#authors = [
+#  {name = "Salient Predictions", email = "help@salientpredictions.com"}
+#]
+#classifiers=[
+#   "Development Status :: 1 - Planning",
+#   "Programming Language :: Python",
+#]
+
+# to deploy & install with twine, replace build-system-twine with build-system
+# python3 -m build
+# python3 -m twine upload --repository testpypi dist/* --skip-existing
+# pip install --upgrade -i https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ salientsdk
+#[build-system]
+#requires = ["setuptools>=61.0","wheel","toml"]
+#build-backend = "setuptools.build_meta"

salientsdk-0.1.3/salientsdk/.gitignore

@@ -0,0 +1,3 @@
+*.nc
+*.csv
+*.geojson

salientsdk-0.1.3/salientsdk/__init__.py

@@ -0,0 +1,42 @@
+#!/usr/bin/env python
+# Copyright Salient Predictions 2024
+
+"""Salient Predictions Software Development Kit."""
+
+import os
+
+import toml
+
+from .constants import get_model_version, set_model_version
+from .data_timeseries_api import data_timeseries, load_multihistory
+from .downscale_api import downscale
+from .forecast_timeseries_api import forecast_timeseries
+from .location import Location
+from .login_api import login
+from .upload_file_api import upload_bounding_box, upload_file, upload_location_file
+
+init_file_dir = os.path.dirname(__file__)
+pyproject_path = os.path.join(init_file_dir, "..", "pyproject.toml")
+
+with open(pyproject_path) as f:
+    pyprj = toml.load(f)
+    prj = pyprj["tool"]["poetry"]
+
+__version__ = prj["version"]
+__author__ = "Salient Predictions"
+__all__ = [
+    "login",
+    "data_timeseries",
+    "downscale",
+    "forecast_timeseries",
+    "get_model_version",
+    "load_multihistory",
+    "Location",
+    "set_model_version",
+    "upload_file",
+    "upload_bounding_box",
+    "upload_location_file",
+]
+
+if __name__ == "__main__":
+    print(f"ver: {__version__} by: {__author__}")

salientsdk-0.1.3/salientsdk/constants.py

@@ -0,0 +1,102 @@
+#!/usr/bin/env python
+# Copyright Salient Predictions 2024
+
+"""Constants for the Salient SDK.
+
+This module contains constants used throughout the Salient SDK.
+
+"""
+
+import datetime
+import hashlib
+import urllib
+
+import requests
+
+# This is the base URL for the Salient API:
+URL = "https://api.salientpredictions.com/"
+
+API_VERSION = "v2"
+
+MODEL_VERSION = "v8"
+MODEL_VERSIONS = ["v7", "v7_1", "v8"]
+
+VERFY_SSL = True
+
+TEST_USER = "help+test@salientpredictions.com"
+TEST_PWD = "salty!"
+
+CURRENT_SESSION = None
+
+
+def _build_url(endpoint: str, args: None | dict = None) -> tuple[str, str]:
+    url = URL + API_VERSION + "/" + endpoint
+    file_name = endpoint
+
+    if args:
+        url += "?"
+        url += urllib.parse.urlencode(args, safe=",")
+
+        file_name += "_"
+        file_name += hashlib.md5(str(args).encode()).hexdigest()
+
+        if "format" in args:
+            file_name += "." + args["format"]
+
+    return (url, file_name)
+
+
+def _validate_date(date: str | datetime.datetime) -> str:
+    if isinstance(date, str) and date == "-today":
+        date = datetime.datetime.today()
+
+    if isinstance(date, datetime.datetime):
+        date = date.strftime("%Y-%m-%d")
+
+    # ENHANCEMENT: accept other date formats like numpy datetime64, pandas Timestamp, etc
+    # ENHANCEMENT: make sure date is properly formatted
+
+    return date
+
+
+def get_model_version() -> str:
+    """Get the current default model version.
+
+    Returns:
+        str: The current model version
+
+    """
+    return MODEL_VERSION
+
+
+def set_model_version(version: str) -> None:
+    """Set the default model version.
+
+    Args:
+        version (str): The model version to set
+
+    """
+    assert version in MODEL_VERSIONS
+    global MODEL_VERSION
+    MODEL_VERSION = version
+
+
+def get_current_session() -> None | requests.Session:
+    """Get the current session.
+
+    Returns:
+        None | requests.Session: The current session
+
+    """
+    return CURRENT_SESSION
+
+
+def set_current_session(session: requests.Session) -> None:
+    """Set the current session.
+
+    Args:
+        session (requests.Session): The session to set
+
+    """
+    global CURRENT_SESSION
+    CURRENT_SESSION = session

salientsdk-0.1.3/salientsdk/data_timeseries_api.py

@@ -0,0 +1,224 @@
+#!/usr/bin/env python
+# Copyright Salient Predictions 2024
+
+"""Historical data timeseries.
+
+This module is an interface to the Salient `data_timeseries` API, which returns historical
+observed data.  It also includes utility functions for operating on the returned data.
+
+Command line usage example:
+
+```
+cd ~/salientsdk
+# this will get a single variable in a single file:
+python -m salientsdk.data_timeseries_api -lat 42 -lon -73 -fld all --start 2020-01-01 --end 2020-12-31
+# this will get multiple variables in separate files:
+python -m salientsdk.data_timeseries_api -lat 42 -lon -73 -fld all -var temp,precip
+```
+
+"""
+
+import os
+
+import requests
+import xarray as xr
+
+from . import constants, location, login_api
+
+
+def data_timeseries(
+    loc: location.Location,
+    variable: str = "temp",
+    field: str = "anom",
+    debias: bool = False,
+    start: str = "1950-01-01",
+    end: str = "-today",
+    format: str = "nc",
+    frequency: str = "daily",
+    force: bool = False,
+    session: requests.Session = constants.get_current_session(),
+    verify: bool = constants.VERFY_SSL,
+    verbose: bool = False,
+    **kwargs,
+) -> str | dict[str, str]:
+    """Get a historical time series of ERA5 data.
+
+    This function is a convenience wrapper to the Salient
+    [API](https://api.salientpredictions.com/v2/documentation/api/#/Historical/get_data_timeseries).
+
+    Args:
+        loc (Location): The location to query
+        variable (str): The variable to query, defaults to `temp`
+            To request multiple variables, separate them with a comma `temp,precip`
+            This will download one file per variable
+            See the
+            [Data Fields](https://salientpredictions.notion.site/Variables-d88463032846402e80c9c0972412fe60)
+            documentation for a full list of available historical variables.
+        field (str): The field to query, defaults to "anom"
+        debias (bool): If True, debias the data to local observations.  Disabled for `shapefile` locations.  [detail](https://salientpredictions.notion.site/Debiasing-2888d5759eef4fe89a5ba3e40cd72c8f)
+        start (str): The start date of the time series
+        end (str): The end date of the time series
+        format (str): The format of the response
+        frequency (str): The frequency of the time series
+        force (bool): If False (default), don't download the data if it already exists
+        session (requests.Session): The session object to use for the request
+        verify (bool): If True (default), verify the SSL certificate
+        verbose (bool): If True (default False) print status messages
+        **kwargs: Additional arguments to pass to the API
+
+    Keyword Arguments:
+        units (str): `SI` or `US`
+        apikey (str): use an API key instead of a username & password
+
+    Returns:
+        str | dict: the file name of the downloaded data.  File names are a hash of the query parameters.
+            When `force=False` and the file already exists, the function will return the file name
+            almost instantaneously without querying the API.
+            If multiple variables are requested, returns a `dict` of `{variable:file_name}`
+    """
+    assert field in [
+        "anom",
+        "anom_d",
+        "anom_ds",
+        "anom_qnt",
+        "anom_s",
+        "clim",
+        "stdv",
+        "trend",
+        "vals",
+        "all",
+    ], f"Invalid field {field}"
+    assert format in ["nc", "csv"], f"Invalid format {format}"
+    assert frequency in [
+        "daily",
+        "weekly",
+        "monthly",
+        "3-monthly",
+    ], f"Invalid frequency {frequency}"
+
+    # if there is a comma in variable, vectorize:
+    if isinstance(variable, str) and "," in variable:
+        variable = variable.split(",")
+
+    if isinstance(variable, list):
+        file_names = {
+            var: data_timeseries(
+                loc=loc,
+                variable=var,
+                field=field,
+                debias=debias,
+                start=start,
+                end=end,
+                format=format,
+                frequency=frequency,
+                force=force,
+                session=session,
+                verify=verify,
+                verbose=verbose,
+                **kwargs,
+            )
+            for var in variable
+        }
+        if verbose:
+            print(file_names)
+        return file_names
+
+    endpoint = "data_timeseries"
+    args = loc.asdict(
+        start=start,
+        end=end,
+        debias=debias,
+        field=field,
+        format=format,
+        frequency=frequency,
+        variable=variable,
+        **kwargs,
+    )
+
+    (query, file_name) = constants._build_url(endpoint, args)
+
+    if force or not os.path.exists(file_name):
+        if verbose:
+            print(f"Downloading {query} to {file_name}")
+        with open(file_name, "wb" if format == "nc" else "w") as f:
+            result = session.get(query, verify=verify)
+            result.raise_for_status()
+            if format == "nc":
+                f.write(result.content)
+            else:
+                f.write(result.text)
+    elif verbose:
+        print(f"File {file_name} already exists")
+
+    return file_name
+
+
+def load_multihistory(files: dict, fields: list[str] = ["vals"]) -> xr.Dataset:
+    """Load multiple history files and merge them into a single dataset.
+
+    Args:
+        files (dict): Dictionary of `{variable:file_name}` of the type returned by
+                      `data_timeseries` when multiple `variable`s are requested
+                      e.g. `data_timeseries(..., variable = "temp,precip")`
+        fields (list[str]): List of fields to extract from the history files
+
+    Returns:
+        xr.Dataset: The merged dataset, where each field and variable is renamed
+        to `<variable>_<field>` or simply `variable` if field = "vals".
+    """
+
+    def __extract_history_fields(file: str, variable: str, fields: str) -> xr.Dataset:
+        hst = xr.load_dataset(file)
+        hst = hst[fields]
+        fields_new = [variable if field == "vals" else variable + "_" + field for field in fields]
+        hst = hst.rename({field: field_new for field, field_new in zip(fields, fields_new)})
+        for fld in fields_new:
+            hst[fld].attrs = hst.attrs
+        hst.attrs = {}
+        hst.close()
+
+        return hst
+
+    # Would prefer to use xr.open_mfdataset, but we need to pass in the variable name
+    # Can convert when history files have a short_name attribute
+    # https://salientpredictions.atlassian.net/browse/RD-1184
+    hst = xr.merge(
+        [__extract_history_fields(files[variable], variable, fields) for variable in files.keys()]
+    )
+    return hst
+
+
+def _main() -> None:
+    argparser = location.Location.get_argparser(["debias", "force"])
+    argparser.add_argument("-var", "--variable", type=str, default="temp")
+    argparser.add_argument("-fld", "--field", type=str, default="anom")
+    argparser.add_argument("--start", type=str, default="1950-01-01")
+    argparser.add_argument("--end", type=str, default="-today")
+    argparser.add_argument("--format", type=str, default="nc")
+    argparser.add_argument("--frequency", type=str, default="daily")
+
+    args = argparser.parse_args()
+
+    session = login_api._login_from_args(args)
+
+    loc = location.Location._from_args_(args)
+    file_name = data_timeseries(
+        loc=loc,
+        variable=args.variable,
+        field=args.field,
+        debias=args.debias,
+        start=args.start,
+        end=args.end,
+        format=args.format,
+        frequency=args.frequency,
+        force=args.force,
+        verbose=args.verbose,
+        session=session,
+    )
+
+    if args.verbose and isinstance(file_name, str):
+        print(xr.open_dataset(file_name))
+
+
+if __name__ == "__main__":
+    _main()