nh3pred 0.1.1__py3-none-any.whl

nh3pred/__init__.py

@@ -0,0 +1,8 @@
+from .api import predict
+
+__all__ = ['predict']
+
+from importlib.metadata import version
+
+__version__ = version("nh3pred")  
+

nh3pred/api.py

@@ -0,0 +1,172 @@
+import torch
+from importlib.resources import files, as_file
+
+from .model_def import AmmoniaRNN
+
+from .utils import generate_tensors_predictors
+
+from .utils import check_allowed_cols
+from .utils import check_needed_cols
+from .utils import check_nan 
+from .utils import check_unique_values_for_plot_level_variables
+from .utils import check_correct_values_for_categorical_variables
+from .utils import check_t_incorp_col
+from .utils import check_t_incorp_values
+
+from .utils import complete_incorp
+from .utils import complete_other
+from .utils import add_dt
+from .utils import convert_cat_variables
+from .utils import reorder_variables
+
+DEVICE = "cpu"
+num_layers = 1
+nonlinearity = "relu"
+bidirectional = True
+hidden_size = 512 
+
+cat_dims = [5, 3, 2]  
+embedding_dims = [10, 9, 8]  
+input_size = 13   
+output_size = 1
+
+model = AmmoniaRNN(input_size = input_size, 
+                   output_size = output_size, 
+                   hidden_size = hidden_size, 
+                   nonlinearity = nonlinearity,
+                   num_layers = num_layers,
+                   bidirectional = bidirectional,
+                   cat_dims = cat_dims, 
+                   embedding_dims = embedding_dims).to(DEVICE)
+
+
+resource = files(__package__).joinpath("data").joinpath("final_model.pth")
+with as_file(resource) as path:
+    model.load_state_dict(torch.load(path, weights_only = True, map_location=torch.device('cpu')))
+
+
+
+def predict (df):
+
+    """
+    Prediction of ammonia emissions following field fertilization.
+
+    Parameters
+    ----------
+    df: pandas.DataFrame
+        Input DataFrame containing the environmental conditions for which predictions are made. 
+        This DataFrame must include some mandatory columns and may include optional columns.
+
+        Mandatory columns:
+            - pmid: identifier for plots
+            - ct: time since fertilizer application (h)
+            - tan_app: total ammoniacal nitrogen applied (kgN/ha)
+
+        Optional columns: 
+            Dynamic variables:
+                - air_temp: air temperature (°C)
+                - wind_2m: wind speed (m/s)
+                - rain_rate: rainfall rate (mm/h)
+            Plot-level variables:
+                - app_rate: application rate (t/ha)
+                - man_dm: manure dry matter content (%)
+                - man_ph: manure pH
+                - app_mthd: application method (must belong to {bc, bsth, ts, os, cs} (1))
+                - man_source: manure source (must belong to {pig, cat})
+                - incorp: incorporation (must belong to {none, shallow, deep})
+                - t_incorp: time of incorporation (h) (2)
+
+        (1) bc = broadacst, bsth = band spreading trailing hose, ts = trailing shoe, os = open slot, cs = closed slot.
+
+        (2) When incorp = none, t_incorp must be set to NaN.
+
+        Default values for optional columns: air_temp = 13.89, wind_2m = 3.11, rain_rate = 0, app_rate = 29.38, man_dm = 6.25, man_ph = 7.38, app_mthd = bsth, man_source = cat, incorp = none. 
+
+    Returns
+    -------
+    pandas.DataFrame
+        The DataFrame completed with the column 'prediction_ecum' (cumulative prediction, kgN/ha) as well as the optional columns not initially provided, filled with their default values.
+
+    Example
+    --------
+    >>> # Prediction for two plots, identified with pmid = 1 and pmid = 2
+    >>> import pandas as pd
+    >>> from nh3pred import predict
+
+    >>> df = pd.DataFrame ({
+    ...     "pmid": [1, 1, 1, 1, 1, 1, 2, 2, 2, 2, 2, 2],
+    ...     "ct": [3, 6, 10, 24, 48, 72, 1, 3, 6, 10, 21, 46],
+    ...     "tan_app": [42, 42, 42, 42, 42, 42, 120, 120, 120, 120, 120, 120],
+    ...     "air_temp": [18, 23, 24, 15, 21, 20, 9, 10, 11, 6, 7, 10],
+    ...     "wind_2m": [2, 2, 1, 1, 2, 2, 4, 5, 5, 6, 3, 4],
+    ...     "rain_rate": 0,
+    ...     "app_rate": [20, 20, 20, 20, 20, 20, 28, 28, 28, 28, 28, 28],
+    ...     "man_dm": [8.3, 8.3, 8.3, 8.3, 8.3, 8.3, 13, 13, 13, 13, 13, 13],
+    ...     "man_ph": [7.1, 7.1, 7.1, 7.1, 7.1, 7.1, 7.7, 7.7, 7.7, 7.7, 7.7, 7.7],
+    ...     "app_mthd": ["ts", "ts", "ts", "ts", "ts", "ts", "bc", "bc", "bc", "bc", "bc", "bc"],
+    ...     "man_source": ["cat", "cat", "cat", "cat", "cat", "cat", "pig", "pig", "pig", "pig", "pig", "pig"]
+    ... })
+
+    >>> predict (df)
+        pmid  ct  air_temp  wind_2m  rain_rate app_mthd incorp man_source  tan_app  app_rate  man_dm  man_ph  t_incorp  prediction_ecum
+    0      1   3        18        2          0       ts   none        cat       42        20     8.3     7.1       NaN         3.090000
+    1      1   6        23        2          0       ts   none        cat       42        20     8.3     7.1       NaN         5.620000
+    2      1  10        24        1          0       ts   none        cat       42        20     8.3     7.1       NaN         7.460000
+    3      1  24        15        1          0       ts   none        cat       42        20     8.3     7.1       NaN         8.030000
+    4      1  48        21        2          0       ts   none        cat       42        20     8.3     7.1       NaN         9.760000
+    5      1  72        20        2          0       ts   none        cat       42        20     8.3     7.1       NaN        10.480000
+    6      2   1         9        4          0       bc   none        pig      120        28    13.0     7.7       NaN         8.550000
+    7      2   3        10        5          0       bc   none        pig      120        28    13.0     7.7       NaN        27.150000
+    8      2   6        11        5          0       bc   none        pig      120        28    13.0     7.7       NaN        41.639999
+    9      2  10         6        6          0       bc   none        pig      120        28    13.0     7.7       NaN        48.549999
+    10     2  21         7        3          0       bc   none        pig      120        28    13.0     7.7       NaN        52.610001
+    11     2  46        10        4          0       bc   none        pig      120        28    13.0     7.7       NaN        61.220001
+    """
+
+    check_allowed_cols (df)
+    check_needed_cols (df)
+    check_nan (df)
+    check_unique_values_for_plot_level_variables (df)
+    check_correct_values_for_categorical_variables (df)
+    check_t_incorp_col (df)
+    check_t_incorp_values (df)
+
+    data_predictions = df.copy()
+
+    data_predictions = complete_incorp (data_predictions)
+    data_predictions = complete_other (data_predictions)
+    data_predictions = add_dt (data_predictions)
+    data_predictions = convert_cat_variables (data_predictions)
+    data_predictions = reorder_variables (data_predictions)
+
+
+    pmids = data_predictions['pmid'].unique()
+    
+    data_predictions['prediction_ecum'] = None
+    data_predictions['prediction_delta_ecum'] = None
+        
+    with torch.no_grad():
+    
+        all_predictions = torch.empty(0).to(DEVICE)
+    
+            
+        for i in pmids:
+    
+            x = generate_tensors_predictors (data_predictions, i, device = DEVICE)
+            y = model(x)
+            all_predictions = torch.cat ((all_predictions, y.squeeze()), 0)
+    
+        data_predictions['prediction_delta_ecum'] = all_predictions.to("cpu").detach()
+    
+    data_predictions['prediction_ecum'] = data_predictions.groupby('pmid')['prediction_delta_ecum'].cumsum()
+    data_predictions["prediction_ecum"] = data_predictions["prediction_ecum"].round(2)
+
+    data_predictions = data_predictions.drop (['dt', 'prediction_delta_ecum'], axis = 1)
+
+
+    data_predictions["app_mthd"] = data_predictions["app_mthd"].map({0: "bc", 1: "bsth", 2: "os", 3: "ts", 4:"cs"})
+    data_predictions["man_source"] = data_predictions["man_source"].map({0: "pig", 1: "cat"})
+    data_predictions["incorp"] = data_predictions["incorp"].map({0: "none", 1: "shallow", 2: "deep"})
+    data_predictions["t_incorp"] = data_predictions["t_incorp"].replace(1000, float("nan"))
+
+    return data_predictions

nh3pred/model_def.py

@@ -0,0 +1,52 @@
+import torch
+import torch.nn as nn
+
+class AmmoniaRNN(nn.Module):
+    
+    def __init__(self, 
+                 input_size, 
+                 output_size, 
+                 hidden_size, 
+                 num_layers,
+                 nonlinearity, 
+                 bidirectional,
+                 cat_dims = None, embedding_dims = None):
+        
+        super(AmmoniaRNN, self).__init__()
+        
+        D = 1 + 1 * bidirectional
+               
+        self.embeddings = nn.ModuleList([
+            nn.Embedding(num_embeddings = cat_dim, embedding_dim = embed_dim)
+            for cat_dim, embed_dim in zip(cat_dims, embedding_dims)
+        ])
+        
+        input_size = input_size - len(cat_dims) + sum(embedding_dims)           
+        
+        self.rnn = nn.RNN(input_size, 
+                          hidden_size, 
+                          num_layers = num_layers,
+                          nonlinearity = nonlinearity, 
+                          bidirectional = bidirectional)    
+        
+        self.fc1 = nn.Linear(hidden_size * D, 6)
+        self.relu = nn.ReLU()
+        self.fc2 = nn.Linear(6, output_size)
+
+    def forward(self, x):
+
+        x_continuous = x[0]
+        x_categoricals = x[1]
+        
+        x_embeds = [embed(x_cat) for embed, x_cat in zip(self.embeddings, x_categoricals)]
+        
+        x = torch.cat([x_continuous] + x_embeds, dim = -1)
+        
+        h, _ = self.rnn(x)
+
+        out = self.fc1(h)
+        out = self.relu(out)
+        out = self.fc2(out)
+       
+        return out
+

nh3pred/utils.py

@@ -0,0 +1,154 @@
+import torch
+import pandas as pd
+
+def generate_tensors_predictors(df, pmid, device):
+    
+    data_filtered = df[df['pmid'] == pmid]
+
+    x_cont = data_filtered[['ct', 'dt', 'air_temp', 'wind_2m', 'rain_rate', 'tan_app', 'app_rate', 'man_dm', 'man_ph', 't_incorp']]
+
+    x_cont_tensor = torch.tensor(x_cont.values, dtype=torch.float32).view(len(x_cont), len(x_cont.columns))
+    x_cont_tensor = x_cont_tensor.to(device)
+    
+    x_cat = data_filtered[['app_mthd', 'incorp', 'man_source']]
+    
+    x_cat_tensor = torch.tensor(x_cat.values, dtype=torch.long).view(len(x_cat), len(x_cat.columns))
+    x_cat_tensor = x_cat_tensor.to(device)
+    x_cat_tensor = torch.unbind (x_cat_tensor, dim = 1)
+
+    output = [x_cont_tensor, x_cat_tensor]
+    
+    return output
+
+def check_allowed_cols (_df):
+
+    allowed_cols = ['pmid', 'ct', 'air_temp', 'wind_2m', 'rain_rate', 'tan_app', 'app_rate', 'man_dm', 'man_ph', 'app_mthd', 'man_source', 'incorp', 't_incorp']
+
+    invalid_cols = list(set(_df.columns) - set(allowed_cols))
+
+    if invalid_cols:
+        raise ValueError(f"The following columns are not allowed: {invalid_cols}")
+
+def check_needed_cols (_df):
+
+    needed_cols = ['pmid', 'ct', 'tan_app']
+    
+    missing_cols = list (set(needed_cols) - set(_df.columns))
+    
+    if missing_cols:
+        raise ValueError (f"The following column(s) is(are) missing: {missing_cols}")    
+
+def check_nan (_df):
+
+    for col in list (set (_df.columns) - set (['t_incorp'])):
+
+        if _df[col].isna().any():
+            raise ValueError(f"NaN values in {col}.")
+
+def check_unique_values_for_plot_level_variables (_df):
+
+    plot_level_variables = ["app_mthd", "man_source", "incorp", "man_ph", "man_dm"]
+
+    pmids = _df['pmid'].unique()
+    variables_to_check = list (set (plot_level_variables) & set (_df.columns))
+
+    for var in variables_to_check:
+        df_tmp = _df.groupby('pmid')[var].unique()
+        for i in pmids:
+            if len (df_tmp[i]) != 1:
+                raise ValueError (f"Not unique value for {var} in pmid {i}")
+
+def check_correct_values_for_categorical_variables (_df):
+
+    categorical_variables = ['app_mthd', 'incorp', 'man_source']
+    
+    expected_values = {'app_mthd': ['bc', 'bsth', 'ts', 'os', 'cs'],
+                       'incorp': ['none', 'deep', 'shallow'],
+                       'man_source': ['pig', 'cat']}
+    
+    variables_to_check = list (set (categorical_variables) & set (_df.columns))
+    
+    for var in variables_to_check:
+        unvalid_values = list (set (_df[var].unique()) - set (expected_values[var]))
+        if unvalid_values:
+            raise ValueError(f"The following values are not allowed in {var}: {unvalid_values}")
+
+def check_t_incorp_col (_df):
+    if 'incorp' in _df.columns:
+        if list (set (_df['incorp'].unique()) - set (["none"])):
+            if 't_incorp' not in _df.columns:
+                raise ValueError ("Column t_incorp is missing.")
+    else:
+        if 't_incorp' in _df.columns:
+            raise ValueError ("Column t_incorp is not allowed since there is no incorp column.")
+
+def check_t_incorp_values (_df):
+
+    if 't_incorp' in _df.columns:
+    
+        df_tmp = _df [(_df['incorp'] == "none") & (_df ['t_incorp'].notna())]
+        if df_tmp.shape[0] > 0:
+            raise ValueError ("t_incorp should be set to NaN when incorp = none.")
+        
+        df_tmp = _df [(_df['incorp'] != "none") & (_df ['t_incorp'].isna())]
+        if df_tmp.shape[0] > 0:
+            raise ValueError ("NaN values in t_incorp for incorp != none.")
+
+def complete_incorp (_df):
+
+    if 'incorp' in _df.columns:
+        if 't_incorp' in _df.columns:
+            _df['t_incorp'] = _df['t_incorp'].fillna (1000)
+
+        elif 't_incorp' not in _df.columns:
+            _df["t_incorp"] = [1000 if val == "none" else 0 for val in _df["incorp"]]
+            
+
+    elif 'incorp' not in _df.columns:
+        _df.insert (len (_df.columns), 'incorp', "none")
+        _df.insert (len (_df.columns), 't_incorp', 1000)
+
+    return _df
+
+def complete_other (_df):
+    all_columns = ['pmid', 'ct', 'air_temp', 'wind_2m', 'rain_rate', 'app_mthd', 'man_source', 'tan_app', 
+                   'app_rate', 'man_dm', 'man_ph']
+
+    default_values = pd.Series({
+        'air_temp': 13.89,
+        'wind_2m': 3.11,
+        'rain_rate': 0,
+        'app_mthd': "bsth",
+        'man_source' : 'cat',
+        'tan_app' : 62.07,
+        'app_rate': 29.38,
+        'man_dm': 6.25,
+        'man_ph': 7.38,
+        
+    })
+
+    missing_col = list (set (all_columns) - set (_df.columns))
+
+    for col in missing_col:
+        _df.insert (len (_df.columns), col, default_values[col])
+
+    return _df
+
+def add_dt (_df):
+    _df.insert (1, 'ct_shift', _df.groupby("pmid")["ct"].shift(1, fill_value=0))
+    _df['dt'] = _df['ct'] - _df['ct_shift']
+    _df = _df.drop (['ct_shift'], axis = 1)
+    return _df
+
+def convert_cat_variables (_df):
+    _df["app_mthd"] = _df["app_mthd"].map({"bc": 0, "bsth": 1, "os": 2, "ts": 3, "cs": 4})
+    _df["man_source"] = _df["man_source"].map({"pig": 0, "cat": 1})
+    _df["incorp"] = _df["incorp"].map({"none": 0, "shallow": 1, "deep": 2})
+
+    return _df
+
+def reorder_variables (_df):
+    return _df[['pmid', 'ct', 'dt', 'air_temp', 'wind_2m', 'rain_rate', 'app_mthd', 'incorp', 'man_source', 'tan_app', 
+                   'app_rate', 'man_dm', 'man_ph', 't_incorp']]
+
+    

nh3pred-0.1.1.dist-info/METADATA

@@ -0,0 +1,68 @@
+Metadata-Version: 2.4
+Name: nh3pred
+Version: 0.1.1
+Summary: Predict ammonia emissions with a recurrent neural network model
+Author-email: Armand Favrot <armand.favrot@inrae.fr>
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python
+Requires-Python: >=3.12.3
+Description-Content-Type: text/markdown
+Requires-Dist: pandas>=2.2.3
+Requires-Dist: torch>=2.5.0
+Provides-Extra: build
+Requires-Dist: build; extra == "build"
+Requires-Dist: twine; extra == "build"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+
+# nh3pred
+
+This package provides a single function, `predict`, which estimates ammonia emissions following field fertilization under given environmental conditions.  
+The underlying model is a recurrent neural network described in [ref] under the name *"rnn 9 – data a."*.  
+The `predict` function works similarly to the `alfam2` function from the R package [ALFAM2](https://cran.r-project.org/web/packages/ALFAM2/index.html).
+
+## Install
+
+```bash
+pip install nh3pred 
+```
+
+## Documentation
+
+A complete documentation for the `predict` function is available [here](https://nh3pred.readthedocs.io/en/latest/api.html#nh3pred.api.predict).
+
+## Usage
+
+You can use the package in Python as follows:
+
+```python
+import pandas as pd
+from ammonia_predict_3 import predict
+
+df = pd.DataFrame ({
+    "pmid": [1, 1, 1, 1, 1, 1],
+    "ct": [3, 6, 10, 24, 48, 72],
+    "tan_app": [42, 42, 42, 42, 42, 42],
+    "air_temp": [18, 23, 24, 15, 21, 20],
+    "wind_2m": [2, 2, 1, 1, 2, 2],
+    "rain_rate": 0,
+    "app_rate": [20, 20, 20, 20, 20, 20],
+    "man_dm": [8.3, 8.3, 8.3, 8.3, 8.3, 8.3],
+    "man_ph": [7.1, 7.1, 7.1, 7.1, 7.1, 7.1],
+    "app_mthd": ["ts", "ts", "ts", "ts", "ts", "ts"],
+    "man_source": ["cat", "cat", "cat", "cat", "cat", "cat"]
+})
+
+pred = predict(df)
+print(pred)
+``` 
+
+
+## Notes
+
+- The trained weights are included in the package under `ammonia_predict/data/final_model.pth`.
+- The package requires **Python ≥3.12**, **PyTorch ≥2.5.0**, and **pandas ≥2.2.3**.
+
+
+

nh3pred-0.1.1.dist-info/RECORD

@@ -0,0 +1,9 @@
+nh3pred/__init__.py,sha256=gR8afgOvwZBjb2w-AONXJZCHqINKQydV5wYNObFcXtM,125
+nh3pred/api.py,sha256=IqT9YZQNdz9Llz3HBw5TVQHn6UPrKOGCGBM5pTxd1w4,7902
+nh3pred/model_def.py,sha256=aue_GP7nnJGFwp5645ScluyDHdt0kBi9g8WxcFs17mI,1528
+nh3pred/utils.py,sha256=z2H6dxebdvVJrN96_Qx4XWYVt8czMj7fFo7xzQocxgE,5352
+nh3pred/data/final_model.pth,sha256=RSAaLGytjB9uQPlFW_EAKyrwGjaDmlQKhLgDozJfB18,2285808
+nh3pred-0.1.1.dist-info/METADATA,sha256=sgEKMbzf5Y1VGVrzYYN1zL328I2-dpJO6nXi4uU-6LY,2077
+nh3pred-0.1.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+nh3pred-0.1.1.dist-info/top_level.txt,sha256=pCAF7nBmtSkoPGy2HebVx00kF1r6gascwX4NOmfLFVw,8
+nh3pred-0.1.1.dist-info/RECORD,,

nh3pred-0.1.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

nh3pred-0.1.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+nh3pred