Skip to content

Documentation - Add more information to README and api.py #220

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jomey merged 1 commit into from
Aug 24, 2026
Merged

Documentation - Add more information to README and api.py #220

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 16 additions & 8 deletions README.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,9 @@ database using Python.

.. _SnowEx database: https://www.github.com/SnowEx/snowex_db

All data in the SnowEx database is publicly available and can be accessed via the
[public records at the National Snow and Ice Data Center](https://nsidc.org/data/snowex/data).
The data are a raw import of all the CSV files and not curated or cleaned

Installing
----------
Expand Down Expand Up @@ -66,18 +69,23 @@ 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.
after a user installation and all queries are fully supported. There is a limit
of 1000 records returned per query, which is sufficient for most use cases and
good filtering.

Another option is to connect directely from your local machine to the database,
which requires [authentication setup](#configuring-the-database-connection)
and has less limits on returned records. However, it is more technical to query
the database directly, and is recommended for advanced use cases. 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. See the `SnowEx Database Tutorial`_
for examples of filtering and querying the database.

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)**
**Lambda Client (no credentials required) - Preferred **
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.
Expand All @@ -92,7 +100,7 @@ dataframe still has the ability to be converted to a GeoPandas dataframe locally

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

**Direct database access via local API (credentials required)**
**Direct database access via local client (credentials required) - Technical users**
For advanced users with database credentials, the ``snowexsql.api`` classes
can be used directly. This path also supports raster queries (in beta).

Expand Down
13 changes: 10 additions & 3 deletions snowexsql/api.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -92,7 +92,8 @@ def get_points():
# * implement 'like' or 'contains' method
class BaseDataset:
"""
Base class for all SnowEx measurement dataset accessors.
Base API access class for all SnowEx measurement dataset providing common
query methods and shared attributes.

Provides filtering, querying, and property-based access to measurements
stored in the SnowEx database. Subclasses must set ``MODEL`` to the
Expand Down Expand Up @@ -577,7 +578,8 @@ def all_instruments(self):

class PointMeasurements(BaseDataset):
"""
API class for access to PointData
API class for access to PointData from a single location.
Examples: Snow Depth, SWE
"""

MODEL = PointData
Expand Down Expand Up @@ -706,7 +708,8 @@ class TooManyRastersException(Exception):

class LayerMeasurements(BaseDataset):
"""
API class for access to LayerData
API class for access to LayerData.
Examples: Snow pit observations (depth, density, temperature), SMP
"""

MODEL = LayerData
Expand Down Expand Up @@ -878,6 +881,10 @@ def get_sites(cls, site_names=None, **kwargs):


class RasterMeasurements(BaseDataset):
"""
Early beta class for handling data stored in raster datasets.
"""

MODEL = ImageData
ALLOWED_QRY_KWARGS = BaseDataset.ALLOWED_QRY_KWARGS + ["description"]

Expand Down
Loading