Investigate unit of measurement handling

[jarq6c]

HT currently has no formal unit of measurement handling. We may be able to incorporate a library like Pint to deal with this.

https://pint.readthedocs.io/en/stable/

[jarq6c]

This issue is related to #113

[jarq6c]

Parking this example here:

from hydrotools.nwis_client.iv import IVDataService
import numpy as np
import pint

def convert(values, from_units, to_units):
    """Convert scientific units of values.
    
    Parameters
    ==========
    values: npt.ArrayLike
        Values to convert
    from_units: pint.UnitRegistry.Quantity compatible object
        Original units of values.
    to_units: pint.UnitRegistry.Quantity compatible object
        Desired conversion units.
        
    Returns
    =======
    result: npt.ArrayLike
        Same shape as values containing converted values.
    """
    # Setup registry
    u = pint.UnitRegistry()

    # Pint Array
    quantities = u.Quantity(np.asarray(values), from_units)

    # Convert units
    return quantities.to(to_units).magnitude

def main():
    # Setup client
    client = IVDataService(value_time_label="value_time")

    # Retrieve some data
    df = client.get(
        sites="01013500",
        startDT="20211001T00:00",
        endDT="20211002T00:00"
    )

    # Convert to cubic meters per second
    df["value"] = convert(df["value"], "ft^3/s", "m^3/s")
    df["measurement_unit"] = "m^3/s"

    # Look at the data
    print(df.head())

if __name__ == "__main__":
    main()

Output

           value_time variable_name usgs_site_code measurement_unit      value qualifiers series
0 2021-10-01 00:00:00    streamflow       01013500            m^3/s  16.112286      ['P']      0
1 2021-10-01 00:15:00    streamflow       01013500            m^3/s  16.112286      ['P']      0
2 2021-10-01 00:30:00    streamflow       01013500            m^3/s  16.112286      ['P']      0
3 2021-10-01 00:45:00    streamflow       01013500            m^3/s  16.112286      ['P']      0
4 2021-10-01 01:00:00    streamflow       01013500            m^3/s  16.112286      ['P']      0

[jarq6c]

Minimal example to compute discharge per unit area (AKA total runoff)

# Set up registry
u = pint.UnitRegistry()

# Parameters
catchment_area = u.Quantity(25.0, "miles^2").to("ft^2")
period = u.Quantity(15.0, "minutes").to("s")
discharge = u.Quantity(500.0, "ft^3/s")

# Compute discharge per unit area
discharge_per_unit_area = discharge * period / catchment_area

# Display in inches
print(discharge_per_unit_area.to("inches"))

Output

0.007747933884297518 inch