Fit and predict fish traits

Fit_model estimates parameters and predicts values from a multivariate random-walk model for fish traits

Usage

Fit_model(
  text = NULL,
  Database = FishLife::FishBase_and_RAM,
  tree = Database$tree,
  Y_ij = Database$Y_ij,
  Z_ik = Database$Z_ik,
  Use_REML = TRUE,
  N_factors = 0,
  N_obsfactors = 0,
  min_replicate_measurements = 0,
  SR_obs = Database$SR_obs,
  StockData = Database$StockData,
  group_j = 1:ncol(Y_ij) - 1,
  Version = "Taxon_v3_0_0",
  TmbDir = system.file("executables", package = "FishLife"),
  RunDir = tempfile(pattern = "run_", tmpdir = tempdir(), fileext = "/"),
  verbose = FALSE,
  debug_mode = FALSE,
  j_SR = ncol(Y_ij) - 3:1,
  additional_variance = c(0, 0),
  SD_b_stock = 10,
  b_type = 0,
  Turn_off_taxonomy = FALSE,
  Pen_lowvar_lnRhat = 1,
  lowerbound_MLSPS = 1,
  Use_RAM_Mvalue_TF = TRUE,
  rho_space = "natural",
  n_sims = 1000,
  n_batches = NULL,
  include_r = TRUE,
  PredTF_stock = NULL,
  extract_covariance = FALSE,
  run_model = TRUE,
  multinomial_for_factors = FALSE,
  Params = "Generate",
  Random = "Generate",
  Map = "Generate",
  add_predictive = FALSE,
  ...
)

Arguments

text

structural equation model structure, passed to either specifyModel and then parsed to control the set of path coefficients and variance-covariance parameters

Database

Whether to use results for both adult and stock-recruit parameters, Database="FishBase_and_RAM", or just adult parameters, Database="FishBase"

tree

phylogenetic structure, using class as.phylo. If tree=NULL then argument Z_ik is instead converted to a tree using ape::as.phylo( ~Class/Order/Family/Genus/GenusSpecies, ... ) to convert it to a tree

Y_ij

a data frame of trait values (perhaps log-scaled) with rows for records, and tagged-columns for traits

Z_ik

a data frame of taxonomic classification for each row of Y_ij

Use_REML

OPTIONAL boolean whether to use maximum marginal likelihood or restricted maximum likelihood (termed "REML")

N_factors

Number of factors in decomposition of covariance for random-walk along evolutionary tree (0 means a diagonal but unequal covariance; negative is the sum of a factor decomposition and a diagonal-but-unequal covariance)

N_obsfactors

Number of factors in decomposotion of observation covariance (same format as N_obsfactors)

min_replicate_measurements

specified threshold for the number of measurements for a given continuous traits, where any continuous trait having fewer replicated measurements for at least one taxon will have the measurement variance fixed at an arbitrarily low value, such that estimated traits are forced to approach the unreplicated measurements

SR_obs

Stock-recruit records from RAM Legacy stock-recruit database

StockData

Auxiliary information for every stock with stock-recruit information

Version

TMB version number

TmbDir

Directory containing pre-compiled TMB script

RunDir

Directory to use when compiling and running TMB script (different to avoid problems with read-write restrictions)

verbose

Boolean whether to print diagnostics to terminal

run_model

Boolean indicating whether to run the model or just return the built TMB object

Params

optional list of parameter estimates to use as starting values (Default Params="Generate" starts from random values)

...

other paramers passed to fit_tmb

Process_cov

Whether process-error covariance is equal or differs multiplicatively for different taxonomic levels (Options: "Equal" or "Unequal")

Value

Tagged list containing objects from FishLife run (first 9 slots constitute list 'Estimate_database' for archiving results)

tree

The phylogenetic tree used for analysis, whether inputted or generated from taxonomy based on Z_ik

SEM_model

The phylogenetic tree used for analysis, whether inputted or generated from taxonomy based on Z_ik

N_factors

Number of factors used for evolution in life-history model

N_obsfactors

Number of factors used for measurent-error in life-history model

Use_REML

Boolean, whether REML was used for model

Cov_gjj

Covariance among traits for every taxon in tree

ParentChild_gz

Record of taxonomic tree

ParHat

Parameter estimates and predictions

g_i

Associates every observation with a level of the taxonomic tree

Y_ij

Raw data

Z_ik

Taxonomy for each datum

Obj

The built TMB object

Opt

Output from optimization

Report

tagged list of report-file from TMB

ParHat_SE

Estimated/predicted standard errors for fixed/random effects

Examples

if (FALSE) {
# Load data set
library(FishLife)

# Simulate data
tree = ape::rtree(n=100)
xfit = x = 1 + 0.3 * phylolm::rTrait(n = 1, phy=tree)
yfit = y = 2 + 1*x + 0.3 * phylolm::rTrait(n = 1, phy=tree)
drop_x = sample( 1:ape::Ntip(tree), replace=FALSE, size=round(ape::Ntip(tree)*0.3) )
xfit[drop_x] = NA
drop_y = sample( 1:ape::Ntip(tree), replace=FALSE, size=round(ape::Ntip(tree)*0.3) )
yfit[drop_y] = NA

# Fit model
Fit = Fit_model(
  text = "x -> y, p",
  Database = NULL,
  Use_REML = FALSE,
  Y_ij = data.frame( x=xfit, y=yfit ),
  tree = tree,
  min_replicate_measurements = Inf )

# S3-defaults
print(Fit)
coef(Fit)

# Convet and plot using sem
mysem = as(Fit,"sem")
sem::pathDiagram( model = mysem,
                  style = "traditional",
                  edge.labels = "values" )
myplot = semPlot::semPlotModel( as(Fit,"sem") )
semPlot::semPaths( myplot,
                   nodeLabels = myplot@Vars$name )

# Convert and plot using phylobase / phylosignal
library(phylobase)
plot( as(Fit,"phylo4d") )
}