phenology (version 10.1)

add_phenology: Create a new dataset or add a timeserie to a previous dataset.

Description

To create a new dataset, the syntaxe is :
data <- add_phenology(add=newdata, name="Site", reference=as.Date('2001-12-31'), format='\ To add a dataset to a previous one, the syntax is :
data <- add_phenology(previous=previousdata, add=newdata, name='Site',
reference=as.Date('2001-01-01'), format="\ The dataset to be added must include 2 or 3 columns.
The colname.Date included the dates in the format specified by the parameter format. If the number of nests is known for an exact date, then only one date must be indicated.
If the number of nests is known for a range of date, the first and last dates must be separated by a sep.dates character.
For example: 1/2/2000-10/2/2000
Note that date in the colname.Date column can be already formated and in this case the parameter format is ignored.

The colname.Number includes the number of nests observed for this date or this range of dates.
The colname.Rookery is optional and includes the name of the rookeries.

If only two columns are indicated, the name can be indicated as a parameter of the function with the parameter name. If no name is indicated, the default name Site will be used, but take care, only one rookery of this name can be used.

Several rookeries can be included in the same file but in this case the rookery name is obligatory at the colname.Rookery column.

The model cannot be fitted if a timeseries has no observation because the trivial solution is of course with max=0. The solution is to include a fake false observation at the closest position of the peak, and then the estimated number of nests/tracks will be the estimated number - 1.
If include0 is TRUE, then the series with no observation are included and one observation is added at the monitored date the closest of datepeakfor0.
The normal way to manage such a situation is as followed:
1- Format data with include0 being FALSE
2- Fit parameters using fdf <- fit_phenology()
3- Format data with include0 being TRUE and datepeakfor0=fdf$par["Peak"]
4- Fix previsouly fitted parameters using pfixed <- fdf$par
5- Generate new set of parameters with par_init(data, fixed.parameters=pfixed)
6- Run again fit_phenology()

Some problems that can occur:
If a name is defined as a third column of a data.frame and a name is defined also with name parameter, the third column has priority.
Two different timeseries MUST have different name and characters _ and space are forbiden in timeseries names. They are automatically changed if they are present.

Usage

add_phenology(
  add = stop("New data must be given."),
  name = "Site",
  reference = NULL,
  month_ref = NULL,
  sep.dates = "-",
  end.season.date = NULL,
  colname.Date = 1,
  colname.Number = 2,
  colname.Rookery = "Site",
  colname.CountTypes = NULL,
  CountTypes.default = "exact",
  colname.A = NULL,
  A.default = NA,
  colname.S = NULL,
  S.default = NA,
  colname.ZeroCounts = NULL,
  ZeroCounts.default = TRUE,
  format = "%d/%m/%Y",
  previous = NULL,
  include0 = FALSE,
  datepeakfor0 = NULL,
  expandRange0Observation = TRUE,
  check.overlapping.dates = TRUE,
  silent = FALSE
)

Value

Return a list of formated data that can be used ith fit_phenology()

Arguments

add

The data to be added. It can be a set of several entities that uses the same reference and date format.

name

The name of the monitored site.

reference

as.Date('2001-12-31') The date used as day 0 in the ordinal date model.

month_ref

If no reference date is given, use this month as a reference.

sep.dates

Separator used to separate dates when incertitude is included.

end.season.date

The date corresponding to the end of nesting season.

colname.Date

Name or number of column with dates.

colname.Number

Name or number of column with numbers.

colname.Rookery

Name or number of column with rookery names.

colname.CountTypes

Model of count type. It can be "exact" (default), "minimum" or a number to indicate the maximum possible.

CountTypes.default

The default of CountTypes if colname.CountTypes is not provided.

colname.A

The A parameter of the detection model

A.default

Default A value.

colname.S

The S parameter of the detection model

S.default

Default S value.

colname.ZeroCounts

The name of the column to indicate whether zero counts are included (TRUE is default).

ZeroCounts.default

The default for ZeroCounts.

format

The format of the dates.

previous

Previous data formated with add_phenology or NULL [default] if no previous data exist.

include0

Does timeseries with only 0 should be included?

datepeakfor0

If series with no observation are included, where add a 1 value in ordinal date (see description)

expandRange0Observation

If TRUE, the range of date with 0 observations are expanded into individual dates

check.overlapping.dates

If TRUE, will check for date overlapping

silent

Does information about added timeseries is shown

Author

Marc Girondot

Details

add_phenology creates a new dataset.

See Also

Other Phenology model: AutoFitPhenology(), BE_to_LBLE(), Gratiot, LBLE_to_BE(), LBLE_to_L(), L_to_LBLE(), MarineTurtles_2002, MinBMinE_to_Min(), adapt_parameters(), add_SE(), extract_result(), fit_phenology(), likelihood_phenology(), logLik.phenology(), map_Gratiot, map_phenology(), par_init(), phenology(), phenology2fitRMU(), phenology_MHmcmc(), phenology_MHmcmc_p(), plot.phenology(), plot.phenologymap(), plot_delta(), plot_phi(), print.phenology(), print.phenologymap(), print.phenologyout(), remove_site(), result_Gratiot, result_Gratiot1, result_Gratiot2, result_Gratiot_Flat, result_Gratiot_mcmc, summary.phenology(), summary.phenologymap(), summary.phenologyout()

Examples

if (FALSE) {
library(phenology)
# Read a file with data
data(Gratiot)
# Generate a formatted list nammed data_Gratiot 
refdate <- as.Date("2001-01-01")
data_Gratiot <- add_phenology(Gratiot, name="Complete", 
	reference=refdate, format="%d/%m/%Y")
	
# Generate initial points for the optimisation
parg <- par_init(data_Gratiot, fixed.parameters=NULL)
# Run the optimisation
result_Gratiot <- fit_phenology(data=data_Gratiot, fitted.parameters=parg, 
	fixed.parameters=NULL)
data(result_Gratiot)
# Plot the phenology and get some stats
output <- plot(result_Gratiot)

#############################################
# Example of use of include0 and datepeakfor0
#############################################
# Let create a times series with only 0
data0 <- data.frame(Date=c("11/3/2015", "12/3/2015", "13/3/2015-18/3/2015", "25/3/2015"), 
                    Number=c(0, 0, 0, 0), 
                    Beach=rep("Site", 4), stringsAsFactors=FALSE)
# Here I don't include beach with no observation: error message
try1 <- add_phenology(data0, format="%d/%m/%Y", month_ref=1, include0=FALSE)
# Here I include timeseries with no observation
try1 <- add_phenology(data0, format="%d/%m/%Y", month_ref=1, include0=TRUE, datepeakfor0=100)
try1 <- add_phenology(data0, format="%d/%m/%Y", month_ref=1, include0=TRUE, datepeakfor0=73)
try1 <- add_phenology(data0, format="%d/%m/%Y", month_ref=1, include0=TRUE, datepeakfor0=70)
# It can be done in two steps
try1 <- add_phenology(data0, format="%d/%m/%Y", month_ref=1, include0=TRUE)
try2 <- add_phenology(previous=try1, include0=TRUE, datepeakfor0=100)
# Here I include the series without observation
try1 <- add_phenology(add=data0, format="%d/%m/%Y", month_ref=1, 
                      include0=TRUE, expandRange0Observation=TRUE)
                      
##############################################################################
# Example of A and S parameters to say that only half of a beach was monitored
##############################################################################

refdate <- as.Date("2001-01-01")
data_Gratiot <- add_phenology(Gratiot, name="Complete1", 
                             	reference=refdate, format="%d/%m/%Y")
	      S.default = 10
	      # Let Complete1 be of length 2 and Complete0.5 be of length 1
	      length.Complete1 <- 2
	      length.Complete0.5 <- 1
	      A.default = log(1/(length.Complete0.5/length.Complete1)-1)/(-S.default*4)
	      # For day 0, the detection probability is
	      1/(1+exp(-(4*S.default)*(A.default-0)))
	data_Gratiot <- add_phenology(previous=data_Gratiot, 
	      add=Gratiot, 
	      name="Complete0.5", 
	      A.default = A.default,
	      S.default = S.default, 
	      reference=refdate, 
	      format="%d/%m/%Y")
	parg <- c(par_init(data_Gratiot, fixed.parameters=c(Min=0, Flat=0)), PMin=0.1)
	result_Gratiot <- fit_phenology(data=data_Gratiot, fitted.parameters=parg, 
	                                fixed.parameters=c(Flat=0))
	result_Gratiot$par
	# it shows that Max_Complete1 is half of Max_Complete0.5; all is ok
	summary(result_Gratiot)$synthesis
	
}