sidfex.read.fcst: Read SIDFEx Forecasts

In helgegoessling/SIDFEx: Tools for the Sea Ice Drift Forecast Experiment (SIDFEx)

Read SIDFEx Forecasts

Description

Read SIDFEx forecast data and (optionally) merge ensembles.

Usage

sidfex.read.fcst(files=NULL,data.path=NULL,GroupID=NULL,MethodID=NULL,TargetID=NULL,InitYear=NULL,InitDayOfYear=NULL,EnsMemNum=NULL,ens.merge=TRUE,checkfileformat=TRUE,verbose=TRUE,speed.fix=TRUE,speed.fix.max=80,timedupli.fix=TRUE,nrl001_xxx.ini.fix=TRUE)

Arguments

files	a character, character vector, or index data frame specifying the SIDFEx forecast file(s) to be read. If a directory is provided, all files in that directory are read. Note that ens.merge works only if files is an index data frame.
data.path	NULL or a character specifying the directory of the forecast data. If NULL, it is attempted to source a file named .SIDFEx in the home directory where a character variable data.path.fcst needs to be defined.
ens.merge	a logical value specifying whether or not to merge ensemble members from individual lists (corresponding to individual files) into merged lists with shared meta data. If TRUE, also ensemble means are computed and, if required, ensembles members are temporally regridded to the time axis of the parent ensemble member (required e.g. to handle lagged-initial-date ensembles).
checkfileformat	a logical value specifying whether or not to check if the file format complies with the SIDFEx conventions, using sidfex.checkfileformat.
verbose	a logical value specifying whether to produce warnings in sl.trajectory.remaptime (only used when lagged-initial-time ensembles are merged), in particular when new time axes reach outside original time axes. Default is TRUE.
speed.fix	a logical value specifying whether to limit the drift speed to certain bounds. Trajectory segments with unrealistically high speeds (as set by speed.fix.max) are replaced by linearly interpolated values between adjacent data points based on sl.trajectory.remaptime(). Default is TRUE.
speed.fix.max	a numerical value specifying the speed threshold used to 'fix' trajectory segments with unrealistically high speeds when speed.fix=TRUE. Default is 80.
timedupli.fix	a logical value specifying whether to remove trajectory data entries with identical times. The respective first values are kept. Note that the consistency or inconsistency of the associated coordinates are not considered. Default is TRUE.
nrl001_xxx.ini.fix	a logical value specifying whether to fix the InitYear and InitDayOfYear of some of the nrl001 MethodIDs where the true initial times correspond to the first time entry in the data table rather than the values in the file name and header. Default is TRUE. As sidfex.fcst.search.createIndex() uses sidfex.fcst.read(), this fix is also reflected in the SIDFEx index.

Value

ens.merge	a logical value indicating whether ensembles have been merged or not (see corresponding argument).
res.list	a list with one element for each individual forecast or forecast ensemble that has been read. The following subelements are included:
...$fl	a character with the corresponding file path and name. A vector if ens.merge=TRUE and the ensemble size is larger than 1.
...$checkfileformat.result	a character, provided only if checkfileformat=TRUE), with the output of sidfex.checkfileformat. A vector if ens.merge=TRUE and the ensemble size is larger than 1.
...$SubmitYear	Year of submission of the forecast to the DKRZ cloud. Inherited from the ensemble parent if ens.merge=TRUE and the ensemble size is larger than 1.
...$SubmitDayOfYear	DayOfYear of submission of the forecast to the DKRZ cloud. Inherited from the ensemble parent if ens.merge=TRUE and the ensemble size is larger than 1.
...$ProcessedYear	Year of processing of the forecast on the DKRZ cloud. Inherited from the ensemble parent if ens.merge=TRUE and the ensemble size is larger than 1.
...$ProcessedDayOfYear	DayOfYear of processing of the forecast on the DKRZ cloud. Inherited from the ensemble parent if ens.merge=TRUE and the ensemble size is larger than 1.
...$GroupID	the Group ID.
...$MethodID	the Method ID.
...$TargetID	the Target ID.
...$InitYear	Year of the initialisation time. Inherited from the ensemble parent if ens.merge=TRUE and the ensemble size is larger than 1.
...$InitDayOfYear	DayOfYear of the initialisation time. Inherited from the ensemble parent if ens.merge=TRUE and the ensemble size is larger than 1.
...$InitLat	initial latitude. Inherited from the ensemble parent if ens.merge=TRUE and the ensemble size is larger than 1. See also MergedInitLat.
...$InitLon	initial longitude. Inherited from the ensemble parent if ens.merge=TRUE and the ensemble size is larger than 1. See also MergedInitLon.
...$EnsMemNum	the ensemble member number. A vector if ens.merge=TRUE and the ensemble size is larger than 1.
...$Ntimesteps	number of timesteps. Inherited from the ensemble parent if ens.merge=TRUE and the ensemble size is larger than 1.
...$FirstYear	Year of the first data point in data. May or may not differ from InitYear.
...$FirstDayOfYear	DayOfYear of the first data point in data. May or may not differ from InitDayOfYear.
...$FirstLat	latitude of the first data point in data. May or may not differ from InitLat. If ens.merge=TRUE and the ensemble size is larger than 1 and initial locations differ, this is the ensemble mean whereas InitLat is inherited from the parent.
...$FirstLon	lonitude of the first data point in data. May or may not differ from InitLon. If ens.merge=TRUE and the ensemble size is larger than 1 and initial locations differ, this is the ensemble mean whereas InitLon is inherited from the parent.
...$LastYear	Year of the last data point in data.
...$LastDayOfYear	DayOfYear of the last data point in data.
...$LastLat	latitude of the last data point in data. If ens.merge=TRUE and the ensemble size is larger than 1, this is the ensemble mean.
...$LastLon	longitude of the last data point in data. If ens.merge=TRUE and the ensemble size is larger than 1, this is the ensemble mean.
...$DaysForecastLength	the time difference between the last and initial time of the forecast in days.
...$data	a data frame holding the actual trajectory data with one point in each row and the following columns: Year, DayOfYear, Lat, Lon, and DaysLeadTime. The latter is the time in days relative to the initial time. If ens.merge=TRUE and the ensemble size is larger than 1, columns 3 and 4 correspond to the ensemble-mean (barycenter) locations and additional pairs of columns with names LatX and LonX are added for each ensemble member, where X is the ensemble member number.
...$MergedInitLat	a vector, provided only if ens.merge=TRUE and the ensemble size is larger than 1, with the first value providing the initial ensemble-mean (barycenter) latitude and the subsequent values providing the initial latitudes of the individual forecasts.
...$MergedInitLon	a vector, provided only if ens.merge=TRUE and the ensemble size is larger than 1, with the first value providing the initial ensemble-mean (barycenter) longitude and the subsequent values providing the initial longitudes of the individual forecasts.
index	the index data frame corresponding to the data read.

Author(s)

Helge Goessling

See Also

sidfex.download.fcst, sidfex.write.fcst, sidfex.checkfileformat

Examples

# Load the forecast data index
index = sidfex.load.index()
# Show the first rows of the index to see which variables can be used to subselect the index
head(index)

# Make an index subset for one specific forecast ensemble
subind = sidfex.fcst.search.extractFromTable(gid = "awi001" , tid = "300234063991680", iy = 2018, idoy = 30, return.dataframe = TRUE)
# Read the forecasts
fcst = sidfex.read.fcst(files=subind, ens.merge=FALSE)
# Now plot latitude against forecast lead time for the whole ensemble
plot(fcst$res.list[[1]]$data$DaysLeadTime,fcst$res.list[[1]]$data$Lat,type="l",ylim=c(74,80),xlim=c(0,600))
for (i in 2:length(fcst$res.list)) {lines(fcst$res.list[[i]]$data$DaysLeadTime,fcst$res.list[[i]]$data$Lat)}
# If you are surprised that the ensemble members have different length, that's because the climatological method applied to generate these forecasts discards trajectories when the sea-ice concentration in the corresponding years dropped below some threshold.

helgegoessling/SIDFEx documentation built on March 15, 2024, 2:26 p.m.