nls_table {forestmangr}

Fit non-linear regressions by group, using LM algorithm and get different output options.

Description

With this function it's possible to fit non-linear regressions using Levenberg-Marquardt or Gauss-Newton algorithms by a grouping variable, and get a data frame with each column as a coefficient and quality of fit variables, and other output options. Works with dplyr grouping functions.

Usage

nls_table(
  df,
  model,
  mod_start,
  .groups = NA,
  output = "table",
  est.name = "est",
  replace = FALSE,
  keep_model = FALSE,
  global_start,
  algorithm = "LM"
)

Arguments

df

A data frame.

model

A linear regression model, with or without quotes. The variables mentioned in the model must exist in the provided data frame. X and Y sides of the model must be separated by "~".

mod_start

A vector or data frame, with start values for coefficients used in the model. This can be a data frame containing the same group variables used in the .groups argument, and the start values.

.groups

Optional argument. Quoted name(s) of grouping variables used to fit multiple regressions, one for each level of the provided variable(s). Default NA.

output

Selects different output options. Can be either "table", "merge", "merge_est" and "nest". See details for explanations for each option. Default: "table".

est.name

Name of the estimated y value. Used only if est.name = TRUE. Default: "est".

replace

If TRUE, models that don't converge on a grouped regression fit will be replaced by coefficients fitted using all data. Default: FALSE.

keep_model

If TRUE, a column containing lm object(s) is kept in the output. Useful if the user desires to get more information on the regression.Default: FALSE.

global_start

Optional argument. A vector or data frame, with start values for the global fit regression used when "replace" is TRUE.

algorithm

Algorithm to be used in the non-linear regression. It can be "LM" (Levenberg-Marquardt, more robust) or "GN" (Gauss-Newton, less robust, uses nls default algorithm). Default: "LM".

Details

This function Levenberg-Marquardt algorithm as default for fitting non-linear regression models. Also, with this function there no more need to use the do function when fitting a linear regression in a pipe line. It's also possible to easily make fit multiple regressions, specifying a grouping variable. In addition to that, the default output sets each coefficient as a column, making it easy to call coefficients by name or position when estimating values. The Levenberg-Marquardt fit uses nlsLM.

Value

A data frame. Different data frame options are available using the output argument.

Author(s)

Sollano Rabelo Braga [e-mail]

Examples

library(forestmangr)
library(dplyr)
data("exfm14")
head(exfm14)

# Fit Chapman & Richards non-linear model for dominant Height:
nls_table(exfm14, dh ~ b0 * (1 - exp( -b1 * age )  )^b2, 
          mod_start = c( b0=23, b1=0.03, b2 = 1.3  ) )

# Fit CR model by strata:
nls_table(exfm14,dh ~ b0 * (1 - exp( -b1 * age )  )^b2,
          mod_start = c( b0=23, b1=0.03, b2 = 1.3  ),
          .groups = "strata") %>% 
          as.data.frame
          
# or, using group_by

exfm14 %>% 
group_by(strata) %>% 
nls_table(dh ~ b0 * (1 - exp( -b1 * age )  )^b2,
          mod_start = c( b0=23, b1=0.03, b2 = 1.3  ) )

# If there are multiple start values, for each strata, they can be supplied like so:
tab_coef <- data.frame(strata = c(1:20, 24,25,27,28,30,31,33,35,36,37), 
              rbind(
              data.frame(b0 = rep(23, 20), b1 = rep(0.03, 20), b2 = rep(1.3, 20) ), 
              data.frame(b0 = rep(23, 10), b1 = rep(0.03, 10), b2 = rep(.5, 10) )))

tab_coef

nls_table(exfm14, dh ~ b0 * (1 - exp( -b1 * age )  )^b2, 
          mod_start = tab_coef,
          .groups = "strata" )
# mod_start needs to be a data frame in this case.

# It's possible to bind the coefficients to the original data,
# to estimate y. We'll also estimate bias and rmse for this estimation.

# This can also be done directly using "merge_est" as output:
nls_table(exfm14,dh ~ b0 * (1 - exp( -b1 * age )  )^b2, 
          mod_start = tab_coef ,
          .groups = "strata", 
          output = "merge_est", 
          est.name = "dh_est" ) %>% 
  mutate(
  bias = bias_per(y = dh, yhat = dh_est),
  rmse = rmse_per(y = dh, yhat = dh_est) ) %>% 
  head(15)

# It's possible to further customize the output, using nested columns:
nls_table(exfm14,dh ~ b0 * (1 - exp( -b1 * age )  )^b2, 
          mod_start = tab_coef ,
          .groups = "strata",
          output = "nest" ) 
             
# It's possible to use Gauss-Newton's algorithm. In this case,
# some regressions will not converge.            
 exfm14 %>% 
group_by(strata) %>% 
nls_table(dh ~ b0 * (1 - exp( -b1 * age )  )^b2,
          mod_start = c( b0=23, b1=0.03, b2 = 1.3  ),algorithm="GN" )
         
# If some regressions don't converge, it's possible to fill those NAs with
# regression coefficients from a general fit, using the entire data: 
nls_table(exfm14,dh ~ b0 * (1 - exp( -b1 * age )  )^b2, 
          mod_start = c( b0=23, b1=0.03, b2 = 1.3  ),
          .groups = "strata",
          replace = TRUE,
          algorithm="GN" )