Quick start#

Turn measured columns into derived quantities, with Polars, Pandas or NumPy.

Every calculation in hydrometlib is a plain function: you give it the measured quantities it needs, and it gives you the derived quantity back, in the same form you passed in.

Here is net radiation from its four measured components, in each of the three libraries:

Refer to columns by name (a plain string) or with pl.col. You get a Polars expression back - which you can give to with_columns or select for Polars to run:


from hydrometlib import meteorology

df = pl.DataFrame(
    {
        "swin": [22.9, 19.3, 14.0, 25.1],
        "swout": [4.9, 4.2, 3.0, 5.5],
        "lwin": [24.1, 26.0, 26.2, 23.1],
        "lwout": [31.2, 31.9, 30.9, 30.8],
    }
)

# string inputs should match your dataframe column names:
df = df.with_columns(
    rn=meteorology.net_radiation(
        "swin", "swout", "lwin", "lwout"
    )
)

# equivalent with pl.col():
df = df.with_columns(
    rn=meteorology.net_radiation(
        pl.col("swin"), pl.col("swout"), pl.col("lwin"), pl.col("lwout")
    )
)

Output:

shape: (4, 5)
┌──────┬───────┬──────┬───────┬──────┐
│ swin ┆ swout ┆ lwin ┆ lwout ┆ rn   │
│ ---  ┆ ---   ┆ ---  ┆ ---   ┆ ---  │
│ f64  ┆ f64   ┆ f64  ┆ f64   ┆ f64  │
╞══════╪═══════╪══════╪═══════╪══════╡
│ 22.9 ┆ 4.9   ┆ 24.1 ┆ 31.2  ┆ 10.9 │
│ 19.3 ┆ 4.2   ┆ 26.0 ┆ 31.9  ┆ 9.2  │
│ 14.0 ┆ 3.0   ┆ 26.2 ┆ 30.9  ┆ 6.3  │
│ 25.1 ┆ 5.5   ┆ 23.1 ┆ 30.8  ┆ 11.9 │
└──────┴───────┴──────┴───────┴──────┘

You can also pass polars.Series directly, and get a Series back, ready to assign:

swin = pl.Series("swin", [22.9, 19.3, 14.0, 25.1])
swout = pl.Series("swout", [4.9, 4.2, 3.0, 5.5])
lwin = pl.Series("lwin", [24.1, 26.0, 26.2, 23.1])
lwout = pl.Series("lwout", [31.2, 31.9, 30.9, 30.8])

rn = meteorology.net_radiation(swin, swout, lwin, lwout)

Output:

shape: (4,)
Series: 'net_radiation' [f64]
[
	10.9
	9.2
	6.3
	11.9
]

Pass pandas.Series - the columns of a DataFrame - and a Series comes back, ready to assign:


from hydrometlib import meteorology

df = pd.DataFrame(
    {
        "swin": [22.9, 19.3, 14.0, 25.1],
        "swout": [4.9, 4.2, 3.0, 5.5],
        "lwin": [24.1, 26.0, 26.2, 23.1],
        "lwout": [31.2, 31.9, 30.9, 30.8],
    }
)

pd_series = meteorology.net_radiation(df["swin"], df["swout"], df["lwin"], df["lwout"])

Output:

<class 'pandas.Series'>
0    10.9
1     9.2
2     6.3
3    11.9
Name: net_radiation, dtype: float64

Pandas support needs the pandas extra (see Installation).

Pass numpy.ndarray and an array comes back:

import numpy as np

swin = np.array([22.9, 19.3, 14.0, 25.1])
swout = np.array([4.9, 4.2, 3.0, 5.5])
lwin = np.array([24.1, 26.0, 26.2, 23.1])
lwout = np.array([31.2, 31.9, 30.9, 30.8])

np_array = meteorology.net_radiation(swin, swout, lwin, lwout)

Output:

<class 'numpy.ndarray'>
[10.9  9.2  6.3 11.9]

NumPy support needs the numpy extra (see Installation).

Every calculation in the library works this way. Which one to use, and what each argument means, is in All calculations.

Where to look next#

  • Flexible inputs: everything you can pass in and what comes back - including Polars Series, site attributes such as a sensor height or a wilting point, and evaluating a calculation for a single set of values.

  • Chaining calculations: feeding one derived quantity into the next.

  • All calculations: the full list of hydrometeorological calculations in the library, grouped by module, each with its inputs, units and source.