Welcome to snowexsql

About

NASA SnowEx was a multi-year airborne and field campaign aimed at understanding the seasonal snowpack across the western United States and Alaska. Each campaign combined airborne remote sensing (lidar, radar, hyperspectral imagery) with intensive ground truth measurements across a variety of different snow climates. The goal was to improve snow water equivalent (SWE) retrieval algorithms for future spaceborne missions.

The SnowEx database consolidates measurements from all campaigns into a single queryable PostgreSQL/PostGIS database. It holds point measurements (snow depths, Federal Sampler SWE) and snow pit information (density, temperature, stratigraphy from snow pits). This software is a client for accessing the database using Python.

Installing

Install using pip:

pip install snowexsql

Full Tutorial

For a complete walkthrough of accessing and querying the SnowEx database, including spatial queries, filtering by campaign or instrument, and working with the returned data, see the Project Pythia Snow Observations Cookbook:

• SnowEx Database Tutorial — step-by-step guide to using the Lambda client and the API classes

Accessing the Database

There are two ways to access the SnowEx database. The preferred way is to use the Lambda Client, which does not require setting up credentials locally with a user installation. The local Python API (this library) connects to the database from the local host, which requires authentication setup and has less limits on returned records. However, it is more technical to query the database directly, and is not recommended for standard users. Rather than retrieving a large number of records the user is encouraged to use the filters to reduce the amount of data to the needed rows.

Due to the heavy dependencies of GeoPandas on other libraries, the Lambda Client was stripped down to features that are only available via Pandas. The returned dataframe still has the ability to be converted to a GeoPandas dataframe locally.

Lambda client (no credentials required)

The recommended approach for most users. The SnowExLambdaClient connects to a public Amazon AWS Lambda Function URL that proxies queries to the database. No AWS account or database credentials are needed.

from snowexsql.lambda_client import SnowExLambdaClient

client = SnowExLambdaClient()
classes = client.get_measurement_classes()
PointMeasurements = classes['PointMeasurements']

df = PointMeasurements.from_filter(type='depth', limit=100)

Direct database access via local API (credentials required)

For advanced users with database credentials, the snowexsql.api classes can be used directly. This path also supports raster queries (in beta).

from snowexsql.api import PointMeasurements, LayerMeasurements

df = LayerMeasurements.from_filter(type='density', limit=100)

Configuring the database connection

For users wishing to have direct access to the database, there are two options for setting up the credentials:

• Set database connection URL via SNOWEX_DB_CONNECTION environment variable Example:

export SNOWEX_DB_CONNECTION="user:password@127.0.0.1/db_name"

• Point to a credentials JSON file via SNOWEX_DB_CREDENTIALS environment variable Example

export SNOWEX_DB_CREDENTIALS="/path/to/credentials.json"

Sample JSON file:

{
  "address": "localhost",
  "db_name": "snowexdb",
  "username": "user",
  "password": "password"
}

Getting help

Jump over to our discussion forum and get help from our community.

Documentation

Our read the docs pages include documentation of the API structure and provides a detailed description of the database schema.

I want to contribute

Thank you for the interest!

Our community follows the

Have a look at our contribution guide and see the many ways to get involved!

Testing

To run the test suite locally requires having a running instance of PostgreSQL. The test suite is configured to run against these credentials:

builder:db_builder@localhost/test

This requires a running database on localhost where the user builder has access to the test database with the password db_builder.

It is possible to set a custom host and database via the SNOWEX_TEST_DB environment variable. Example that would connect to a server on my.host and the database snowex_test:

export SNOWEX_TEST_DB="my_host/snowex_test"

More on connection strings to PostgreSQL can be found with the official documentation.

DOI

• SnowEx Hackweek 2022 -
• SnowEx Hackweek 2024 -