Documentation for function in the DAISIEprep package

Usage

default_params_doc(
  island_colonist,
  island_tbl,
  phylod,
  extraction_method,
  species_label,
  species_endemicity,
  x,
  value,
  clade_name,
  status,
  missing_species,
  col_time,
  col_max_age,
  branching_times,
  min_age,
  species,
  clade_type,
  endemic_clade,
  phylo,
  island_species,
  descendants,
  clade,
  asr_method,
  tie_preference,
  earliest_col,
  include_not_present,
  nested_asr_species,
  num_missing_species,
  species_to_add_to,
  node_pies,
  test_scenario,
  data,
  island_age,
  num_mainland_species,
  num_clade_types,
  list_type2_clades,
  prop_type2_pool,
  epss,
  verbose,
  precise_col_time,
  n,
  digits,
  include_crown_age,
  only_tips,
  node_label,
  multi_phylod,
  island_tbl_1,
  island_tbl_2,
  unique_clade_name,
  genus_name,
  stem,
  genus_in_tree,
  missing_genus,
  checklist,
  phylo_name_col,
  genus_name_col,
  in_phylo_col,
  endemicity_status_col,
  rm_species_col,
  tree_size_range,
  num_points,
  prob_on_island,
  prob_endemic,
  replicates,
  log_scale,
  parameter_index,
  sse_model,
  force_nonendemic_singleton,
  ...
)

Arguments

island_colonist

An instance of the Island_colonist class.

island_tbl

An instance of the Island_tbl class.

phylod

A phylo4d object from the package phylobase containing phylogenetic and endemicity data for each species.

extraction_method

A character string specifying whether the colonisation time extracted is the minimum time (min) (before the present), or the most probable time under ancestral state reconstruction (asr).

species_label

The tip label of the species of interest.

species_endemicity

A character string with the endemicity, either "endemic" or "nonendemic" of an island species, or "not_present" if not on the island.

x

An object whose class is determined by the signature.

value

A value which can take several forms to be assigned to an object of a class.

clade_name

Character name of the colonising clade.

status

Character endemicity status of the colonising clade. Either "endemic" or "nonendemic".

missing_species

Numeric number of missing species from the phylogeny that belong to the colonising clade. For a clade with missing species this is \(n - 1\), where \(n\) is the number of missing species in the clade. If the clade is an island singleton, the number of missing species is 0 because by adding the colonist it already counts as one automatically. If the clade has more than one species, the missing_species is \(n - 1\) because adding the lineage already counts as one.

col_time

Numeric with the colonisation time of the island colonist

col_max_age

Boolean determining whether colonisation time should be considered a precise time of colonisation or a maximum time of colonisation

branching_times

Numeric vector of one or more elements which are the branching times on the island.

min_age

Numeric minimum age (time before the present) that the species must have colonised the island by. This is known when there is a branching on the island, either in species or subspecies.

species

Character vector of one or more elements containing the name of the species included in the colonising clade.

clade_type

Numeric determining which type of clade the island colonist is, this determines which macroevolutionary regime (parameter set) the island colonist is in. After formatting the island_tbl to a DAISIE data list, the clade type can be used to conduct a 2-type analysis (see https://CRAN.R-project.org/package=DAISIE/vignettes/demo_optimize.html for more information)

endemic_clade

Named vector with all the species from a clade.

phylo

A phylogeny either as a phylo (from the ape package) or phylo4 (from the phylobase package) object.

island_species

Data frame with two columns. The first is a character string of the tip_labels with the tip names of the species on the island. The second column a character string of the endemicity status of the species, either endemic or nonendemic.

descendants

A vector character strings with the names of species to determine whether they are the same species.

clade

A numeric vector which the indices of the species which are in the island clade.

asr_method

A character string, either "parsimony" or "mk" determines whether a maximum parsimony or continuous-time markov model reconstructs the ancestral states at each node. See documentation in castor::asr_max_parsimony() or castor::asr_mk_model() in castor R package for details on the methods used.

tie_preference

Character string, either "island" or "mainland" to choose the most probable state at each node using the max.col() function. When a node has island presence and absence equally probable we need to decide whether that species should be considered on the island. To consider it on the island use ties.method = "last" in the max.col() function, if you consider it not on the island use ties.method = "first". Default is "island".

earliest_col

A boolean to determine whether to take the colonisation time as the most probable time (FALSE) or the earliest possible colonisation time (TRUE), where the probability of a species being on the island is non-zero. Default is FALSE.

include_not_present

A boolean determining whether species not present on the island should be included in island colonist when embedded within an island clade. Default is FALSE.

nested_asr_species

A character string which determines whether nested island colonists are split into separate colonists ("split"), or grouped into a single clade ("group"). Nested species are those whose tip state is on the island, and they have ancestral nodes on the island, but there are nodes in between these island state nodes that have the state not_present (i.e. not on the island). Therefore, the colonisation time can be extracted as the most recent node state on the island (this can be the branching time before the tip if the ancestor node of the tip is not on the island), or the older node state of the larger clade, for "split" or "group" respectively. Note This argument only applies when extraction_method = "asr".

num_missing_species

Numeric for the number of missing species in the clade.

species_to_add_to

Character string with the name of the species to identify which clade to assign missing species to.

node_pies

Boolean determining if pie charts of the probabilities of a species being present on the island. If TRUE the correct data is required in the phylod object.

test_scenario

Integer specifying which test phylod object to create.

data

Either an object of class Island_tbl or a DAISIE data table object (output from as_daisie_datatable()).

island_age

Age of the island in appropriate units.

num_mainland_species

The size of the mainland pool, i.e. the number of species that can potentially colonise the island.

num_clade_types

Number of clade types. Default num_clade_types = 1 all species are considered to belong to the same macroevolutionary process. If num_clade_types = 2, there are two types of clades with distinct macroevolutionary processes.

list_type2_clades

If num_clade_types = 2, list_type2_clades specifies the names of the clades that have a distinct macroevolutionary process. The names must match those in the "Clade_name" column of the source data table. If num_clade_types = 1, then list_type2_clades = NA should be specified (default).

prop_type2_pool

Specifies the fraction of potential mainland colonists that have a distinct macroevolutionary process. Applies only if number_clade_types = 2. Default "proportional" sets the fraction to be proportional to the number of clades of distinct macroevolutionary process that have colonised the island. Alternatively, the user can specify a value between 0 and 1 (e.g. if the mainland pool size is 1000 and prop_type2_pool = 0.02 then the number of type 2 species is 20).

epss

Default = 1e-5 should be appropriate in most cases. This value is used to set the maximum age of colonisation of "Non_endemic_MaxAge" and "Endemic_MaxAge" species to an age that is slightly younger than the island for cases when the age provided for that species is older than the island. The new maximum age is then used as an upper bound to integrate over all possible colonisation times.

verbose

Boolean. States if intermediate results should be printed to console. Defaults to FALSE

precise_col_time

Boolean, TRUE uses the precise times of colonisation, FALSE makes every colonist a max age colonistion and uses minimum age of colonisation if available.

n

A numeric to be rounded.

digits

A numeric specifying which decimal places to round to

include_crown_age

A boolean determining whether the crown age gets plotted with the stem age.

only_tips

A boolean determing whether only the tips (i.e. terminal branches) are searched for back colonisation events.

node_label

A numeric label for a node within a phylogeny.

multi_phylod

A list of phylod objects.

island_tbl_1

An object of Island_tbl class to be comparedl

island_tbl_2

An object of Island_tbl class to be compared

unique_clade_name

Boolean determining whether a unique species identifier is used as the clade name in the Island_tbl object or a genus name which may not be unique if that genus has several independent island colonisations

genus_name

Character string of genus name to be matched with a genus name from the tip labels in the phylogeny

stem

Character string, either "genus" or "island_presence". The former will extract the stem age of the genussbased on the genus name provided, the latter will extract the stem age based on the ancestral presence on the island either based on the "min" or "asr" extraction algorithms.

genus_in_tree

A numeric vector that indicates which species in the genus are in the tree

missing_genus

A list of character vectors containing the genera in each island clade

checklist

data frame with information on species on the island

phylo_name_col

A character string specifying the column name where the names in the phylogeny are in the checklist

genus_name_col

A character string specifying the column name where the genus names are in the checklist

in_phylo_col

A character string specifying the column name where the status of whether a species is in the phylogeny is in the checklist

endemicity_status_col

A character string specifying the column name where the endemicity status of the species are in the checklist

rm_species_col

A character string specifying the column name where the information on whether to remove species from the checklist before counting the number of missing species is in the checklist. This can be NULL if no species are to be removed from the checklist. This is useful when species are in the checklist because they are on the island but need to be removed as they are not in the group of interest, e.g. a migratory bird amongst terrestrial birds

tree_size_range

Numeric vector of two elements, the first is the smallest tree size (number of tips) and the second is the largest tree size

num_points

Numeric determining how many points in the sequence of smallest tree size to largest tree size

prob_on_island

Numeric vector of each probability on island to use in the parameter space

prob_endemic

Numeric vector of each probability of an island species being endemic to use in the parameter space

replicates

Numeric determining the number of replicates to use to account for the stochasticity in sampling the species on the island and endemic species

log_scale

A boolean determining whether the sequence of tree sizes are on a linear (FALSE) or log (TRUE) scale

parameter_index

Numeric determining which parameter set to use (i.e which row in the parameter space data frame), if this is NULL all parameter sets will be looped over

sse_model

either "musse" (default) or "geosse". MuSSE expects state values 1, 2, 3, which here we encode as "not_present", "endemic", "nonendemic", respectively. GeoSSE expects trait values 0, 1, 2, with 0 the widespread state (here, "nonendemic"), and 1 and 2 are "not_present" and "endemic", respectively.

force_nonendemic_singleton

A boolean that determines whether all species that are classified as "nonendemic" are forced to be extracted as singletons (i.e single species lineages). By default it is FALSE so non-endemics can be extracted either as singletons or part of an endemic clade. When set to TRUE all non-endemic species in the tree will be single species colonists, with the colonisation time extracted as the stem age for the tip in the phylogeny. There are some exceptions to this, please see vignette("Forcing_nonendemic_singleton", package = "DAISIEprep") for more details.

This argument is only active when extraction_method = "asr", when extraction_method = "min" this argument will be ignored with a warning, as the min method always extracts non-endemic species as singletons.

...

dots Allows arguments to be passed to castor::asr_mk_model() and castor::asr_max_parsimony(). These arguments must match by name exactly, see ?castor::asr_mk_model() and ?castor::asr_max_parsimony() for information on arguments.

Value

Nothing

Author

Joshua W. Lambert