1\name{na.locf}
2\alias{na.locf}
3\alias{na.locf0}
4\alias{na.locf.data.frame}
5\alias{na.locf.list}
6\alias{na.locf.default}
7\title{Last Observation Carried Forward}
8\description{
9Generic function for replacing each \code{NA} with the most recent
10non-\code{NA} prior to it.
11}
12\usage{
13na.locf(object, na.rm = TRUE, \dots)
14\method{na.locf}{default}(object, na.rm = TRUE, fromLast, rev,
15        maxgap = Inf, rule = 2, \dots)
16
17na.locf0(object, fromLast = FALSE, maxgap = Inf, coredata = NULL)
18}
19\arguments{
20  \item{object}{an object.}
21  \item{na.rm}{logical. Should leading \code{NA}s be removed?}
22  \item{fromLast}{logical. Causes observations to be carried backward rather
23    than forward.  Default is \code{FALSE}. With a value of \code{TRUE}
24    this corresponds to NOCB (next observation carried backward).
25    It is not supported if \code{x} or \code{xout} is specified.}
26  \item{rev}{Use \code{fromLast} instead.  This argument will
27    be eliminated in the future in favor of \code{fromLast}.}
28  \item{maxgap}{Runs of more than \code{maxgap} \code{NA}s are retained,
29    other \code{NA}s are removed and the last occurrence in the resulting series
30    prior to each time point in \code{xout} is used as that time point's output value.
31    (If \code{xout} is not specified this reduces to retaining runs of more than
32    \code{maxgap} \code{NA}s while filling other \code{NA}s with the last
33    occurrence of a non-\code{NA}.)}
34  \item{rule}{See \code{\link{approx}}.}
35  \item{\dots}{further arguments passed to methods.}
36  \item{coredata}{logical. Should LOCF be applied to the core data
37    of a (time series) object and then assigned to the original object
38    again? By default, this strategy is applied to time series classes
39    (e.g., \code{ts}, \code{zoo}, \code{xts}, etc.) where it preserves
40    the time index.}
41}
42
43\value{
44An object in which each \code{NA} in the input object is replaced
45by the most recent non-\code{NA} prior to it.  If there are no earlier non-\code{NA}s then
46the \code{NA} is omitted (if \code{na.rm = TRUE}) or it is not replaced (if \code{na.rm = FALSE}).
47
48The arguments \code{x} and \code{xout} can be used in which case they have
49the same meaning as in \code{\link{approx}}.
50
51Note that if a multi-column zoo object has a column entirely composed of
52\code{NA} then with \code{na.rm = TRUE}, the default,
53the above implies that the resulting object will have
54zero rows. Use \code{na.rm = FALSE} to preserve the \code{NA} values instead.
55
56The function \code{na.locf0} is the workhorse function underlying the default
57\code{na.locf} method. It has more limited capabilities but is faster for the
58special cases it covers. Implicitly, it uses \code{na.rm=FALSE}.
59}
60
61\seealso{\code{\link{zoo}}}
62
63\examples{
64az <- zoo(1:6)
65
66bz <- zoo(c(2,NA,1,4,5,2))
67na.locf(bz)
68na.locf(bz, fromLast = TRUE)
69
70cz <- zoo(c(NA,9,3,2,3,2))
71na.locf(cz)
72
73# generate and fill in missing dates
74z <- zoo(c(0.007306621, 0.007659046, 0.007681013,
75	0.007817548, 0.007847579, 0.007867313),
76	as.Date(c("1993-01-01", "1993-01-09", "1993-01-16",
77	"1993-01-23", "1993-01-30", "1993-02-06")))
78g <- seq(start(z), end(z), "day")
79na.locf(z, xout = g)
80
81# similar but use a 2 second grid
82
83z <- zoo(1:9, as.POSIXct(c("2010-01-04 09:30:02", "2010-01-04 09:30:06",
84 "2010-01-04 09:30:07", "2010-01-04 09:30:08", "2010-01-04 09:30:09",
85 "2010-01-04 09:30:10", "2010-01-04 09:30:11", "2010-01-04 09:30:13",
86 "2010-01-04 09:30:14")))
87
88g <- seq(start(z), end(z), by = "2 sec")
89na.locf(z, xout = g)
90
91## get 5th of every month or most recent date prior to 5th if 5th missing.
92## Result has index of the date actually used.
93
94z <- zoo(c(1311.56, 1309.04, 1295.5, 1296.6, 1286.57, 1288.12,
951289.12, 1289.12, 1285.33, 1307.65, 1309.93, 1311.46, 1311.28,
961308.11, 1301.74, 1305.41, 1309.72, 1310.61, 1305.19, 1313.21,
971307.85, 1312.25, 1325.76), as.Date(c(13242, 13244,
9813245, 13248, 13249, 13250, 13251, 13252, 13255, 13256, 13257,
9913258, 13259, 13262, 13263, 13264, 13265, 13266, 13269, 13270,
10013271, 13272, 13274)))
101
102# z.na is same as z but with missing days added (with NAs)
103# It is formed by merging z with a zero with series having all the dates.
104
105rng <- range(time(z))
106z.na <- merge(z, zoo(, seq(rng[1], rng[2], by = "day")))
107
108# use na.locf to bring values forward picking off 5th of month
109na.locf(z.na)[as.POSIXlt(time(z.na))$mday == 5]
110
111## this is the same as the last one except instead of always using the
112## 5th of month in the result we show the date actually used
113
114# idx has NAs wherever z.na does but has 1, 2, 3, ... instead of
115# z.na's data values (so idx can be used for indexing)
116
117idx <- coredata(na.locf(seq_along(z.na) + (0 * z.na)))
118
119# pick off those elements of z.na that correspond to 5th
120
121z.na[idx[as.POSIXlt(time(z.na))$mday == 5]]
122
123## only fill single-day gaps
124
125merge(z.na, filled1 = na.locf(z.na, maxgap = 1))
126
127## fill NAs in first column by inflating the most recent non-NA
128## by the growth in second column.  Note that elements of x-x
129## are NA if the corresponding element of x is NA and zero else
130
131m <- zoo(cbind(c(1, 2, NA, NA, 5, NA, NA), seq(7)^2), as.Date(1:7))
132
133r <- na.locf(m[,1]) * m[,2] / na.locf(m[,2] + (m[,1]-m[,1]))
134cbind(V1 = r, V2 = m[,2])
135
136## repeat a quarterly value every month
137## preserving NAs
138zq <- zoo(c(1, NA, 3, 4), as.yearqtr(2000) + 0:3/4)
139tt <- as.yearmon(start(zq)) + seq(0, len = 3 * length(zq))/12
140na.locf(zq, xout = tt, maxgap = 0)
141
142## na.locf() can also be mimicked with ave()
143x <- c(NA, 10, NA, NA, 20, NA)
144f <- function(x) x[1]
145ave(x, cumsum(!is.na(x)), FUN = f)
146
147## by replacing f() with other functions various generalizations can be
148## obtained, e.g.,
149f <- function(x) if (length(x) > 3) x else x[1]  # like maxgap
150f <- function(x) replace(x, 1:min(length(x)), 3) # replace up to 2 NAs
151f <- function(x) if (!is.na(x[1]) && x[1] > 0) x[1] else x  # only positve numbers
152}
153\keyword{ts}
154