Examples
========
The following are a collection of examples using the python data access API.

Example to get the paths and metadata about parflow water table depth baseline::

	import hydrodata.data_catalog.data_access

	options = {
		"variable": "water_table_depth",
		"dataset": "conus1_baseline_mod",
		"grid": "CONUS1",
		"period": "daily",
		"file_type": "pfb"
	}
	# Get path names to files
	entry = hydrodata.data_catalog.data_access.get_catalog_entry(options)
	paths = hydrodata.data_catalog.data_access.get_file_paths(entry, start_time="2005-09-29", end_time="2005-10-03")

	# 4 files between 9/29/2005-10/03/2005  (note - spans water year)
	assert len(paths) == 4
	assert paths[3] == "/hydrodata/PFCLM/CONUS1_baseline/simulations/daily/WY2006/wtd.daily.mean.002.pfb"

	assert entry["structure_type"] == "gridded"
	assert entry["dataset_var"] == "wtd"
	assert entry["units"] == "m"
	assert entry["file_type"] == "pfb"

Example to get an numpy ndarray of data of a data catalog entry::

    options = {
        "variable": "water_table_depth",
        "dataset": "conus1_baseline_mod",
        "period": "daily",
        "file_type": "pfb"
    }
    # Get an data catalog entry and the data for that entry as a numpy array
    entry = hydrodata.data_catalog.data_access.get_catalog_entry(options)
    data = hydrodata.data_catalog.data_access.get_ndarray(entry, start_time="2005-09-29", end_time="2005-10-03")

    assert list(data.shape) == [4, 1888, 3342]

Example subsetting of PFB forcing file using the data catalog::

import hydrodata.data_catalog.data_access
from parflow import read_pfb_sequence

"""Demonstrate reading and susetting 5 days of hourly pfb pressure files."""

	options = {
		"variable": "pressure_head",
		"dataset": "conus1_baseline_mod",
		"grid": "conus1",
		"period": "hourly",
		"file_type": "pfb"
	}
	entry = hydrodata.data_catalog.data_access.get_catalog_entry(options)
	paths = hydrodata.data_catalog.data_access.get_file_paths(entry, start_time="2005-09-29", end_time="2005-10-03")

	# Read the data from the list of pfb files (5 days crossing a water year)
	# Subset the pfb files by x,y space constraints to an area of interest
	boundary_constraints = {
		"x": {"start": int(1076), "stop": int(1124)},
		"y": {"start": int(720), "stop": int(739)},
		"z": {"start": 0, "stop": 0},
	}
	data = read_pfb_sequence(paths, boundary_constraints)

	assert data.shape[0] == 96       # 4 days x 24 hours
	assert data.shape[1] == 4        # 4 layers deep
	assert data.shape[2] == 19       # 19 y points
	assert data.shape[3] == 48       # 48 x points


Example To Get Information From Data Model Tables::

	import hydrodata.data_catalog.data_access

	# Demonstrate reading information from data catalog model

	rows = hydrodata.data_catalog.data_access.get_table_rows("grid")

	assert len(rows) == 3
	assert rows[0]["id"] == "conus1"
	assert rows[0]["shape"][0] == 3342
	assert rows[0]["shape"][1] == 1888

	rows = hydrodata.data_catalog.data_access.get_table_rows("dataset", id="conus1_baseline_mod")
	assert rows[0]["dataset_type"] == "parflow"