fitacis: Fit multiple A-Ci curves at once
In plantecophys: Modelling and Analysis of Leaf Gas Exchange Data

Description Usage Arguments Details References Examples

A convenient function to fit many curves at once, by calling fitaci for every group in the dataset. The data provided must include a variable that uniquely identifies each A-Ci curve.

fitacis(
  data,
  group,
  fitmethod = c("default", "bilinear"),
  progressbar = TRUE,
  quiet = FALSE,
  id = NULL,
  ...
)

## S3 method for class 'acifits'
plot(
  x,
  how = c("manyplots", "oneplot"),
  highlight = NULL,
  ylim = NULL,
  xlim = NULL,
  add = FALSE,
  what = c("model", "data", "none"),
  colour_by_id = FALSE,
  id_legend = TRUE,
  linecol = "grey",
  linecol_highlight = "black",
  lty = 1,
  ...
)

`data`	Dataframe with Ci, Photo, Tleaf, PPFD (the last two are optional). For `fitacis`, also requires a grouping variable.
`group`	The name of the grouping variable in the dataframe (an A-Ci curve will be fit for each group separately).
`fitmethod`	Method to fit the A-Ci curve. Either 'default' (Duursma 2015), or 'bilinear'. See Details.
`progressbar`	Display a progress bar (default is TRUE).
`quiet`	If TRUE, no messages are written to the screen.
`id`	Names of variables (quoted, can be a vector) in the original dataset to return as part of the coef() statement. Useful for keeping track of species names, treatment levels, etc. See Details and Examples.
`...`	Further arguments passed to `fitaci` (in the case of `fitacis`), or `plot.acifit` (in the case of `plot.acifits`).
`x`	For `plot.acifits`, an object returned from `fitacis`
`how`	If 'manyplots', produces a single plot for each A-Ci curve. If 'oneplot' overlays all of them.
`highlight`	If a name of a curve is given (check names(object), where object is returned by acifits), all curves are plotted in grey, with the highlighted one on top.
`xlim, ylim`	The X and Y axis limits.
`add`	If TRUE, adds the plots to a current plot.
`what`	What to plot, either 'model' (the fitted curve), 'data' or 'none'. See examples.
`colour_by_id`	If TRUE, uses the 'id' argument to colour the curves in the standard plot (only works when `how = 'oneplot'`, see Examples)
`id_legend`	If `colour_by_id` is set, place a legend (topleft) or not.
`linecol`	Colour(s) to use for the non-highlighted curves (can be a vector).
`linecol_highlight`	Colour to use for the 'highlighted' curve.
`lty`	Line type(s), can be a vector (one for each level of the factor, will be recycled).

Troubleshooting - When using the default fitting method (see fitaci), it is common that some curves cannot be fit. Usually this indicates that the curve is poor quality and should not be used to estimate photosynthetic capacity, but there are exceptions. The fitacis function now refits the non-fitting curves with the 'bilinear' method (see fitaci), which will always return parameter estimates (for better or worse).

Summarizing and plotting - Like fitaci, the batch utility fitacis also has a standard plotting method. By default, it will make a single plot for every curve that you fit (thus generating many plots). Alternatively, use the setting how="oneplot" (see Examples below) for a single plot. The fitted coefficients are extracted with coef, which gives a dataframe where each row represents a fitted curve (the grouping label is also included).

Adding identifying variables - after fitting multiple curves, the most logical next step is to analyze the coefficient by some categorical variable (species, treatment, location). You can use the id argument to store variables from the original dataset in the output. It is important that the 'id' variables take only one value per fitted curve, if this is not the case only the first value of the curve will be stored (this will be rarely useful). See examples.

Duursma, R.A., 2015. Plantecophys - An R Package for Analysing and Modelling Leaf Gas Exchange Data. PLoS ONE 10, e0143346. doi:10.1371/journal.pone.0143346

## Not run: 
# Fit many curves (using an example dataset)
# The bilinear method is much faster, but compare using 'default'!
fits <- fitacis(manyacidat, "Curve", fitmethod="bilinear")
with(coef(fits), plot(Vcmax, Jmax))

# The resulting object is a list, with each component an object as returned by fitaci
# So, we can extract one curve:
fits[[1]]
plot(fits[[1]])

# Plot all curves in separate figures with plot(fits)
# Or, in one plot:
plot(fits, how="oneplot")

# Note that parameters can be passed to plot.acifit. For example,
plot(fits, how="oneplot", what="data", col="blue")
plot(fits, how="oneplot", add=TRUE, what="model", lwd=c(1,1))

# Other elements can be summarized with sapply. For example, look at the RMSE:
rmses <- sapply(fits, "[[", "RMSE")
plot(rmses, type='h', ylab="RMSE", xlab="Curve nr")

# And plot the worst-fitting curve:
plot(fits[[which.max(rmses)]])

# It is very straightforward to summarize the coefficients by a factor variable
# that was contained in the original data. In manyacidat, there is a factor variable
# 'treatment'.
# We first have to refit the curves, using the 'id' argument:
fits <- fitacis(manyacidat, "Curve", fitmethod="bilinear", id="treatment")

# And now use this to plot Vcmax by treatment.
boxplot(Vcmax ~ treatment, data=coef(fits), ylim=c(0,130))

# As of package version 1.4-2, you can also use the id variable for colouring curves,
# when plotting all fitted curves in one plot.
# Set colours to be used. Also note that the 'id' variable has to be a factor,
# colours will be set in order of the levels of the factor.
# Set palette of colours:
palette(rainbow(8))

# Use colours, add legend.
plot(fits, how="oneplot", colour_by_id = TRUE, id_legend=TRUE)


## End(Not run)