5. API

5.1. EONR Class

Calculates the economic optimum nitrogen rate and plots the results

EONR is a Python package for computing the economic optimum nitrogen fertilizer rate using data from agronomic field trials under economic conditions defined by the user (i.e., grain price and fertilizer cost). It can be used for any crop (e.g., corn, wheat, potatoes, etc.), but the current version only supports use of the quadratic-plateau piecewise model.

Therefore, use caution in making sure that a quadratic-plateau model is appropriate for your application. Future versions should add support for other models (quadratic, spherical, etc.) that may improve the fit of experimental yield response to nitrogen for other crops.

Optional arguments when creating an instance of EONR:

param cost_n_fert:
 Cost of N fertilizer (default: 0.50)
type cost_n_fert:
 float, optional
param cost_n_social:
 Social cost of N fertilier (default: 0.00)
type cost_n_social:
 float, optional
param costs_fixed:
 Fixed costs on a per area basis (default: 0.00)
type costs_fixed:
 float, optional
param price_grain:
 Price of grain (default: 3.00)
type price_grain:
 float, optional
param col_n_app:
 Column name pointing to the rate of applied N fertilizer data (default: ‘rate_n_applied_lbac’)
type col_n_app:str, optional
param col_yld:Column name pointing to the grain yield data. This column is multiplied by price_grain to create the ‘grtn’ column in EONR.df_data (default: ‘yld_grain_dry_buac’)
type col_yld:str, optional
param col_crop_nup:
 Column name pointing to crop N uptake data (default: ‘nup_total_lbac’)
type col_crop_nup:
 str, optional
param col_n_avail:
 Column name pointing to available soil N plus fertilizer (default: ‘soil_plus_fert_n_lbac’)
type col_n_avail:
 str, optional
param col_year:Column name pointing to year (default: ‘year’)
type col_year:str, optional
param col_location:
 Column name pointing to location (default: ‘location’)
type col_location:
 str, optional
param col_time_n:
 Column name pointing to nitrogen application timing (default: ‘time_n’)
type col_time_n:
 str, optional
param unit_currency:
 String describing the curency unit (default: ‘$’)
type unit_currency:
 str, optional
param unit_fert:
 String describing the “fertilizer” unit (default: ‘lbs’)
type unit_fert:str, optional
param unit_grain:
 String describing the “grain” unit (default: ‘bu’)
type unit_grain:
 str, optional
param unit_area:
 String descibing the “area” unit (default: ‘ac’)
type unit_area:str, optional
param model:Statistical model used to fit N rate response. ‘quad_plateau’ = quadratic plateau; ‘lin_plateau’ = linear plateau (default: ‘quad_plateau’)
type model:str, optional
param ci_level:Confidence interval level to save in EONR.df_results and to display in the EONR plot; note that confidence intervals are calculated at many alpha levels, and we should choose from that list - should be one of [0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.667, 0.7, 0.8, 0.9, 0.95, or 0.99] (default: 0.90)
type ci_level:float, optional
param base_dir:Base file directory when saving results (default: None)
type base_dir:str, optional
param base_zero:
 Determines if gross return to N is expressed as an absolute value or relative to the yield/return at the zero rate. If base_zero is True, observed data for the zero nitrogen rate will be standardized by subtracting the y-intercept (\(\beta_0\)) from the ‘grtn’ column of EONR.df_data. (default: True)
type base_zero:bool, optional
param print_out:
 Determines if “non-essential” results are printed in the Python console (default: False)
type print_out:bool, optional
Requirements:
The minimum data requirement to utilize this package is observed (or simulated) experimental data of agronomic yield response to nitrogen fertilizer. In other words, your experiment should have multiple nitrogen rate treatments, and you should have measured the yield for each experimental plot at the end of the season. Suitable experimental design for your particular experiment is always suggested (e.g., it should probably be replicated).

5.2. EONR Instance Methods

Class methods available for any instance of EONR. Run my_eonr = EONR([options]) to create a new EONR instance, then you’ll have access to any of the following methods.

class eonr.EONR(cost_n_fert=0.5, cost_n_social=0.0, costs_fixed=0.0, price_grain=3.0, col_n_app='rate_n_applied_lbac', col_yld='yld_grain_dry_buac', col_crop_nup='nup_total_lbac', col_n_avail='soil_plus_fert_n_lbac', col_year='year', col_location='location', col_time_n='time_n', unit_currency='$', unit_fert='lbs', unit_grain='bu', unit_area='ac', model='quad_plateau', ci_level=0.9, base_dir=None, base_zero=True, print_out=False)[source]
calc_delta(df_results=None)[source]

Calculates the change in EONR among economic scenarios

Parameters:df_results (Pandas dataframe, optional) – The dataframe containing the results from EONR.calculate_eonr() (default: None).
Returns:df_out “The dataframe with the newly inserted EONR delta.”

Note

EONR.calc_delta() filters all data by location, year, and nitrogen timing, then the “delta” is calculated as the difference relative to the economic scenario resulting in the highest EONR.

calculate_eonr(df, col_n_app=None, col_yld=None, col_crop_nup=None, col_n_avail=None, col_year=None, col_location=None, col_time_n=None, bootstrap_ci=False, samples_boot=9999, delta_tstat=False)[source]

Calculates the EONR and its confidence intervals

Parameters:
  • df (Pandas dataframe) – The dataframe containing the experimental data.
  • col_n_app (str, optional) – Column name pointing to the rate of applied N fertilizer data (default: None).
  • col_yld (str, optional) – Column name pointing to the grain yield data. This column is multiplied by price_grain to create the ‘grtn’ column in EONR.df_data (default: None).
  • col_crop_nup (str, optional) – Column name pointing to crop N uptake data (default: None).
  • col_n_avail (str, optional) – Column name pointing to available soil N at planting plus fertilizer throughout the season (default: None).
  • col_year (str, optional) – Column name pointing to year (default: None).
  • col_location (str, optional) – Column name pointing to location (default: None).
  • col_time_n (str, optional) – Column name pointing to nitrogen application timing (default: None).
  • bootstrap_ci (bool, optional) – Indicates whether bootstrap confidence intervals are to be computed. If calculating the EONR for many sites and/or economic scenarios, it may be desirable to set to False because the bootstrap confidence intervals take the most time to compute (default: False).
  • samples_boot (int, optional) – Number of samples in the bootstrap computation (default: 9999).
  • delta_tstat (bool, optional) – Indicates whether the difference from the t-statistic will be computed (as a function of theta2/N rate). May be useful to observe what optimization method is best suited to reach convergence when computing the profile-likelihood CIs (default: False).

Note

col_n_app and col_yld are required by EONR, but not necessarily by EONR.calculate_eonr(). They must either be set during the initialization of EONR(), or be passed in this method.

Note

col_crop_nup and col_n_avail are required to calculate the socially optimum nitrogen rate, SONR. The SONR is the optimum nitrogen rate considering the social cost of nitrogen, so therefore, EONR.cost_n_social must also be set.

Note

col_year, col_location, and col_time_n are purely optional. They only affect the titles and axes labels of the plots.

plot_delta_tstat(level_list=None, style='ggplot')[source]

Plots the test statistic as a function nitrogen rate

Parameters:
  • level_list (list) – The confidence levels to plot; should be a subset of items in EONR.ci_list (default: None).
  • style (str, optional) – The style of the plolt; can be any of the options supported by matplotlib
plot_derivative(ci_type='profile-likelihood', ci_level=None, style='ggplot')[source]

Plots a zoomed up view of the ONR and the derivative

Parameters:
  • ci_type (str) – Indicates which confidence interval type should be plotted. Options are ‘wald’, to plot the Wald CIs; ‘profile-likelihood’, to plot the profile-likelihood CIs; or ‘bootstrap’, to plot the bootstrap CIs (default: ‘profile-likelihood’).
  • ci_level (float) – The confidence interval level to be plotted, and must be one of the values in EONR.ci_list. If None, uses the EONR.ci_level (default: None).
  • level (float) – The confidence levels to plot; should be a value from EONR.ci_list (default: 0.90).
  • style (str, optional) – The style of the plolt; can be any of the options supported by matplotlib
plot_eonr(ci_type='profile-likelihood', ci_level=None, run_n=None, x_min=None, x_max=None, y_min=None, y_max=None, style='ggplot')[source]

Plots EONR, MRTN, GRTN, net return, and nitrogen cost

Parameters:
  • ci_type (str, optional) – Indicates which confidence interval type should be plotted. Options are ‘wald’, to plot the Wald CIs; ‘profile-likelihood’, to plot the profile-likelihood CIs; or ‘bootstrap’, to plot the bootstrap CIs (default: ‘profile-likelihood’).
  • ci_level (float, optional) – The confidence interval level to be plotted, and must be one of the values in EONR.ci_list. If None, uses the EONR.ci_level (default: None).
  • run_n (int, optional) – NOT IMPLEMENTED. The run number to plot, as indicated in EONR.df_results; if None, uses the most recent, or maximum, run_n in EONR.df_results (default: None).
  • x_min (int, optional) – The minimum x-bounds of the plot (default: None)
  • x_max (int, optional) – The maximum x-bounds of the plot (default: None)
  • y_min (int, optional) – The minimum y-bounds of the plot (default: None)
  • y_max (int, optional) – The maximum y-bounds of the plot (default: None)
  • style (str, optional) – The style of the plolt; can be any of the options supported by matplotlib

Note

x_min, x_max, y_min, and y_max are set by Matplotlib if left as None.

plot_modify_size(fig=None, plotsize_x=7, plotsize_y=4, labelsize=11)[source]

Modifies the size of the last plot generated

Parameters:
  • fig (Matplotlib Figure, optional) – Matplotlib figure to modify (default: None)
  • plotsize_x (float, optional) – Sets x size of plot in inches (default: 7)
  • plotsize_y (float, optional) – Sets y size of plot in inches (default: 4)
  • labelsize (float, optional) – Sets tick and label (defaulat: 11)
plot_modify_title(title_text, g=None, size_font=12)[source]

Allows user to replace the title text

Parameters:
  • title_text (str) – New title text
  • g (matplotlib.figure) – Matplotlib figure object to modify (default: None)
  • size_font (float) – Font size to use (default: 12)
plot_save(fname=None, base_dir=None, fig=None, dpi=300)[source]

Saves a generated matplotlib figure to file

Parameters:
  • fname (str, optional) – Filename to save plot to (default: None)
  • base_dir (str, optional) – Base file directory when saving results (default: None)
  • fig (eonr.fig, optional) – EONR figure object to save (default: None)
  • dpi (int, optional) – Resolution to save the figure to in dots per inch (default: 300)
plot_tau(y_axis='t_stat', emphasis='profile-likelihood', run_n=None, style='ggplot')[source]

Plots the test statistic as a function nitrogen rate

Parameters:
  • y_axis (str, optional) – Value to plot on the y-axis. Options are ‘t_stat’, to plot the T statistic; ‘f_stat’, to plot the F-statistic; or ‘level’, to plot the confidence level; (default: ‘t_stat’).
  • emphasis (str, optional) – Indicates which confidence interval type, if any, should be emphasized. Options are ‘wald’, to empahsize the Wald CIs; ‘profile-likelihood’, to empahsize the profile-likelihood CIs; ‘bootstrap’, to empahsize the bootstrap CIs; or None, to empahsize no CI (default: ‘profile-likelihood’).
  • run_n (int, optional) – The run number to plot, as indicated in EONR.df_ci; if None, uses the most recent, or maximum, run_n in EONR.df_ci (default: None).
  • style (str, optional) – The style of the plolt; can be any of the options supported by matplotlib
print_results()[source]

Prints the results of the optimum nitrogen rate computation

set_column_names(col_n_app=None, col_yld=None, col_crop_nup=None, col_n_avail=None, col_year=None, col_location=None, col_time_n=None)[source]

Sets the column name(s) for EONR.df_data

Parameters:
  • col_n_app (str, optional) – Column name pointing to the rate of applied N fertilizer data (default: None).
  • col_yld (str, optional) – Column name pointing to the grain yield data. This column is multiplied by price_grain to create the ‘grtn’ column in EONR.df_data (default: None).
  • col_crop_nup (str, optional) – Column name pointing to crop N uptake data (default: None).
  • col_n_avail (str, optional) – Column name pointing to available soil N at planting plus fertilizer throughout the season (default: None).
  • col_year (str, optional) – Column name pointing to year (default: None).
  • col_location (str, optional) – Column name pointing to location (default: None).
  • col_time_n (str, optional) – Column name pointing to nitrogen application timing (default: None).

Note

Year, location, or nitrogen timing (used for titles and axes labels for plotting).

set_trial_details(year=None, location=None, n_timing=None)[source]

Sets the year, location, or nitrogen timing

Parameters:
  • year (str or int, optional) – Year of experimental trial (default: None)
  • location (str or int, optional) – Location of experimental trial (default: None)
  • n_timing (str or int, optional) – Nitrogen timing of experimental trial (default: None)

Note

Year, location, or nitrogen timing (used for titles and axes labels for plotting).

update_econ(cost_n_fert=None, cost_n_social=None, costs_fixed=None, price_grain=None)[source]

Sets or resets the nitrogen costs or grain price

Parameters:
  • cost_n_fert (float, optional) – Cost of nitrogen fertilizer (default: None).
  • cost_n_social (float, optional) – Cost of pollution caused by excess nitrogen (default: None).
  • costs_fixed (float, optional) – Fixed costs on a per area basis
  • (default – None)
  • price_grain (float, optional) – Price of grain (default: None).

Note

update_econ() recomputes the price ratio based on the passed information, then adjusts/renames the lowest level folder in the base directory, EONR.base_dir, based on to the ratio. The folder name is set according to the economic scenario (useful when running EONR for many different economic scenarios then plotting and saving results for each scenario). See examples below.

Example 1 (how folder name is set when social cost of nitrogen is zero): folder name will be set to “trad_0010” if cost_n_social == 0 and price_ratio == 0.10, coresponding to “trad” and “0010” in the folder name, respectively.

Example 2 (how folder name is set when social cost of nitrogen is greater than zero): folder name will be set to “social_154_1100” if cost_n_social > 0, price_ratio = 15.4, and cost_n_social = 1.10, corresponding to “social”, “154”, and “1100” in the folder name, respectively.