Metadata-Version: 2.1
Name: snowexsql
Version: 0.4.1
Summary: SQL Database software for SnowEx data
Home-page: https://github.com/SnowEx/snowexsql
Author: Micah Johnson
Keywords: snowexsql
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Requires-Python: >=3.8
Description-Content-Type: text/x-rst
License-File: LICENSE
Requires-Dist: utm <1.0,>=0.5.0
Requires-Dist: geoalchemy2 <1.0,>=0.6
Requires-Dist: geopandas <1.0,>=0.7
Requires-Dist: psycopg2-binary <2.10.0,>=2.9.0
Requires-Dist: rasterio >=1.1.5
Requires-Dist: SQLAlchemy >=2.0.0

====================
Welcome to snowexsql
====================

.. image:: https://readthedocs.org/projects/snowexsql/badge/?version=latest
    :target: https://snowexsql.readthedocs.io/en/latest/?badge=latest
    :alt: Documentation Status

.. image:: https://img.shields.io/github/workflow/status/SnowEx/snowexsql/snowexsql
    :target: https://github.com/SnowEx/snowexsql/actions/workflows/main.yml
    :alt: Testing Status

.. image:: https://img.shields.io/pypi/v/snowexsql.svg
    :target: https://pypi.org/project/snowexsql/
    :alt: Code Coverage

.. image:: https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/micahjohnson150/2034019acc40a963bd02d2fcbb31c5a9/raw/snowexsql__heads_master.json
    :alt: Code Coverage

Database access and tools for using the `SnowEx database`_. This tool is
simply a client for accessing the database using python

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

WARNING - This is under active development in preparation for SnowEx Hackweek.  Use at your own risk.  Data will change as it is QA/QC'd and the end goal is for all data in this database to be pulled from NSIDC.  The goal is for this to become a community database open to all. 

DOI
---
* SnowEx Hackweek 2022

.. image:: https://zenodo.org/badge/DOI/10.5281/zenodo.7618102.svg
   :target: https://doi.org/10.5281/zenodo.7618102

Features
--------

* Database access for SnowEx Database
* Analysis tools
* Useful conversions to pandas and geopandas
* Lots of examples_

.. _examples: https://snowexsql.readthedocs.io/en/latest/examples.html


Installing
----------
If you are just planning on using the database, then only install the
python package instructions below.

I just want to use it
---------------------
Install using pip:

.. code-block::

    pip install snowexsql

I want to contribute!
---------------------
Install the python package by:

.. code-block:: bash

  python3 setup.py install

If you are planning on running the tests or building the docs below also run:

.. code-block:: bash

  pip install -r requirements_dev.txt

If you are using `conda` you may need to reinstall the following using conda:

  * Jupyter notebook
  * nbconvert


I want data fast!
-----------------
A programmatic API has been created for fast and standard
access to Point and Layer data. There are two examples_ covering the
features and usage of the api. See the specific api_ documentation for
detailed description.

.. _api: https://snowexsql.readthedocs.io/en/latest/api.html

.. code-block:: python

    from snowexsql.api import PointMeasurements, LayerMeasurements
    # The main functions we will use are `from_area` and `from_filter` like this
    df = PointMeasurements.from_filter(
        date=date(2020, 5, 28), instrument='camera'
    )
    print(df.head())

Tests
-----

Before testing, in a seperate terminal, we need to run a local instance
of the database. This can be done with

.. code-block:: bash

  docker-compose up -d

When you are finished testing, make sure to turn the docker off

.. code-block:: bash

  docker-compose down


Quickly test your installation by running:

.. code-block:: bash

  python3 -m pytest tests/

The goal of this project is to have high fidelity in data
interpretation/submission to the database. To see the current
test coverage run:

.. code-block:: bash

  make coverage


Documentation
-------------

There is a whole host of resources for users in the documentation. It has been
setup for you to preview in your browser.

In there you will find:

* Examples of database use
* Database structure
* API to the python package snowexsql
* Links to other resources
* Notes about the data uploaded
* And more!

To see the documentation in your browser:

**Warning**: To see the examples/gallery, the snowex db needs to be up. Otherwise they will be left with the
last image submitted to GitHub.

.. code-block:: bash

  make docs


=======
History
=======

0.1.0 (2020-06-12)
------------------

* Project Created.

Hack Week 2021 (2021-07-15)
---------------------------

* Fully deployed database with around 100 users
* Uploaded with fully reproducible DB using Snowex Data for Grand Mesa 2020
* Timezones all in Mountain Standard

0.2.0 Repo Split (2022-06-20)
-----------------------------

* Repo was split into an access client and a db builder to reduce overhead
* snowexsql is now an access client and python tools to make life easy
* snowex_db_ is now a repo containing all necessary assets to build db.

.. _snowex_db: https://github.com/SnowEx/snowex_db

0.3.0 (2022-07-6)
-----------------------------

* New columns were added to the LayerData table for flags
* Converted surveyors to observers
* Changed utm zone to be an integer
