Package 'gfpop'

Data Generator

Description

Generating data with a given model = changepoint relative positions + parameters + type of cost + (standard deviation + gamma decay)

Usage

dataGenerator(
  n,
  changepoints,
  parameters,
  type = "mean",
  sigma = 1,
  gamma = 1,
  size = 10
)

Arguments

n	number of data points to generate
changepoints	vector of positions of the changepoints in (0,1] (last element is always 1).
parameters	vector of means for the consecutive segments (same length as changepoints)
type	a string defining the cost model to use: "mean", "variance", "poisson", "exp", "negbin"
sigma	a positive number = the standard deviation of the data
gamma	a number between 0 and 1 : the coefficient of the exponential decay (by default = 1 for piecewise constant signals)
size	parameter of the rnbinom function

Value

a vector of size n generated by the chosen model

Examples

dataGenerator(500, c(0.3, 0.6, 1), c(1, 2, 3), type = "mean", sigma = 0.5)

dataGenerator(1000, c(0.2, 0.33,0.5, 1), c(4, 0.2, 3,0.5), type = "variance")

dataGenerator(800, c(0.4, 0.8, 1), c(15, 5, 8), type = "mean", gamma  = 0.95, sigma = 0.4)

dataGenerator(400, c(0.4, 0.9, 1), c(2, 1.5, 3), type = "poisson")

dataGenerator(1000, c(0.44, 0.86, 1), c(0.5, 0.2, 0.4), type = "negbin", size = 3)

---

Electrocardiogram data

Description

The goal in these data is to detect the QRS complex, as does the Pan-Tompkins algorithm.

Usage

data("ECG")

Format

A named list of two data.tables: data has 1001 rows and 2 columns, PanTompkins has 24 rows and 3 columns.

References

https://www.robots.ox.ac.uk/~gari/teaching/cdt/A3/readings/ECG/Pan+Tompkins.pdf

---

Edge generation

Description

Edge creation for gfpop-R-Package graph

Usage

Edge(
  state1,
  state2,
  type = "null",
  decay = 1,
  gap = 0,
  penalty = 0,
  K = Inf,
  a = 0
)

Arguments

state1	a string defining the starting state of the edge
state2	a string defining the ending state of the edge
type	a string equal to "null", "std", "up", "down" or "abs". Default type is "null", the transition to stay on the same segment.
decay	a nonnegative number to give the strength of the exponential decay into the segment
gap	a nonnegative number to constrain the size of the gap in the change of state
penalty	a nonnegative number. The penality associated to this state transition
K	a positive number. Threshold for the Biweight robust loss
a	a positive number. Slope for the Huber robust loss

Value

a one-row dataframe with 9 variables

Examples

Edge("Dw", "Up", "up", gap = 1, penalty = 10, K = 3)

Edge(0, 1, "abs", penalty = 2, gap = 1)

Edge(0, 0, "null", penalty = 0, K = 2, a = 1)

Edge("Dw", "Dw", type = "null", decay = 0.997)

---

Graph-Constrained Functional Pruning Optimal Partitioning (gfpop)

Description

Functional pruning optimal partitioning with a graph structure to take into account constraints on consecutive segment parameters. The user has to specify the graph he wants to use (see the graph function) and a type of cost function. This is the main function of the gfpop package. Its result can be plotted using the S3 gfpop function gfpop::plot()

Usage

gfpop(data, mygraph, type = "mean", weights = NULL, testMode = FALSE)

Arguments

data	vector of data to segment. For simulation studies, Data can be generated using gfpop package function gfpop::dataGenerator()
mygraph	dataframe of class "graph" to constrain the changepoint inference, see gfpop::graph()
type	a string defining the cost model to use: "mean", "variance", "poisson", "exp", "negbin"
weights	vector of weights (positive numbers), same size as data
testMode	boolean. FALSE by default. Used to debug the code

Details

The constrained optimization problem for n data points takes the following general form:

$Q_n = min (with constraints) (\sum_{t=1}^n (\gamma(e[t])(y[t], \mu[t]) + \beta(e[t]))$

with data points $y[t]$, edges $e[t]$, edge-dependent penalties $\beta(e[t])$ and cost functions $\gamma$. The cost function can take three different forms for parameter x and constants (A, B, C):

• quadratic, with representation $Ax^2 + Bx +C$ with $x$ in R

• log-linear, with representation $Ax - B log(x) +C$ with $x \ge 0$

• log-log, with representation $- A log(x) - B log(1-x) +C$ with $0 \le x \le 1$

For each optimization problem, we consider a unique cost representation. However, the User can define robustness values (K and a) specific to each edge, making the cost function edge-dependent. We give the atomic form of each of the five available types (for one data point of value y with weight w)

• "mean" : $A = w$, $B = -2wy$, $C = wy^2$

• "variance" : $A = wy^2$, $B = w$, $C = 0$

• "poisson" : $A = w$, $B = wy$, $C = 0$

• "exp" : $A = wy$, $B = w$, $C = 0$

• "negbin" : $A = w$, $B = wy$, $C = 0$

Value

a gfpop object = (changepoints, states, forced, parameters, globalCost)

changepoints

is the vector of changepoints (we give the last element of each segment)

states

is the vector giving the state of each segment

forced

is the vector specifying whether the constraints of the graph are active (= TRUE) or not (= FALSE)

parameters

is the vector of successive parameters of each segment

globalCost

is a number equal to the total loss: the minimal cost for the optimization problem with all penalty values excluded

See Also

• gfpop::dataGenerator() to generate data for multiple change-point simulations

• gfpop::graph() to create graphs complying with the gfpop function

• gfpop::plot() to plot the gfpop object and visualize inferred changepoints and parameters

Examples

n <- 1000 #data length
### EXAMPLE 1 ### updown graph + poisson loss
 myData <- dataGenerator(n, c(0.1, 0.3, 0.5, 0.8, 1), c(1, 2, 1, 3, 1), type = "poisson")
 myGraph <- graph(penalty = 2 * sdDiff(myData)^2 * log(n), type = "updown")
 gfpop(data = myData, mygraph = myGraph, type = "poisson")

### EXAMPLE 2 ### relevant graph with min gap = 2 + poisson loss
 myData <- dataGenerator(n, c(0.1, 0.3, 0.5, 0.8, 1), c(1, 2, 3, 5, 3), type = "poisson")
 myGraph <- graph(type = "relevant", penalty = 2 * log(n), gap = 2)
 gfpop(data =  myData, mygraph = myGraph, type = "poisson")

### EXAMPLE 3 ### std graph with robust loss + variance loss
 myData <- dataGenerator(n, c(0.1, 0.3, 0.5, 0.8, 1), c(1, 5, 1, 5, 1), type = "variance")
 outliers <- 5 * rbinom(n, 1, 0.05) - 5 * rbinom(n, 1, 0.05)
### with robust parameter K
 myGraph <- graph(type = "std", penalty = 2 * log(n), K = 10)
 gfpop(data =  myData + outliers, mygraph = myGraph, type = "variance")
### no K
 myGraph <- graph(type = "std", penalty = 2 * log(n))
 gfpop(data =  myData, mygraph = myGraph, type = "variance")

### EXAMPLE 4 ###  3-segment graph with mean (Gaussian) loss
 myData <- dataGenerator(n, c(0.12, 0.31, 0.53, 0.88, 1), c(1, 2, 0, 1, 2), type = "mean")
 outliers <- 5 * rbinom(n, 1, 0.05) - 5 * rbinom(n, 1, 0.05)
 gfpop(data =  myData + outliers, mygraph = paperGraph(8, penalty = 2 * log(n)), type = "mean")

---

Graph generation

Description

Graph creation using component functions Edge, StartEnd and Node

Usage

graph(
  ...,
  type = "empty",
  decay = 1,
  gap = 0,
  penalty = 0,
  K = Inf,
  a = 0,
  all.null.edges = FALSE
)

Arguments

...	This is a list of edges definied by functions Edge, StartEnd and Node. See gfpop functions gfpop::Edge(), gfpop::StartEnd() and gfpop::Node()
type	a string equal to "std", "isotonic", "updown" or "relevant" to build a predefined classic graph
decay	a nonnegative number to give the strength of the exponential decay into the segment
gap	a nonnegative number to constrain the size of the gap in the change of state
penalty	a nonnegative number equals to the common penalty to use for all edges
K	a positive number. Threshold for the Biweight robust loss
a	a positive number. Slope for the Huber robust loss
all.null.edges	a boolean. Add null edges to all nodes automatically

Value

a dataframe with 9 variables : columns are named "state1", "state2", "type", "parameter", "penalty", "K", "a", "min", "max" with additional "graph" class.

Examples

graph(type = "updown", gap = 1.3, penalty = 5)

graph(Edge("Dw","Dw"),
      Edge("Up","Up"),
      Edge("Dw","Up","up", gap = 0.5, penalty = 10),
      Edge("Up","Dw","down"),
      StartEnd("Dw","Dw"),
      Node("Dw",0,1),
      Node("Up",0,1))

graph(Edge("1", "2", type = "std"),
      Edge("2", "3", type = "std"),
      Edge("3", "4", type = "std"),
      StartEnd(start = "1", end = "4"),
      all.null.edges = TRUE)

---

Graph-constrained functional pruning optimal partitioning iterated

Description

Functional pruning optimal partitioning with a graph structure to take into account constraints on consecutive segment parameters. This is an iterated version of the main gfpop function using a Birgé Massart like penalty

Usage

itergfpop(
  data,
  mygraph,
  type = "mean",
  weights = NULL,
  iter.max = 100,
  D.init = 1
)

Arguments

data	vector of data to segment. For simulation studies, Data can be generated using gfpop package function gfpop::dataGenerator()
mygraph	dataframe of class "graph" to constrain the changepoint inference, see gfpop::graph()
type	a string defining the cost model to use: "mean", "variance", "poisson", "exp", "negbin"
weights	vector of weights (positive numbers), same size as data
iter.max	maximal number of iteration of the gfpop function
D.init	initialisation of the number of segments

Value

a gfpop object = (changepoints, states, forced, parameters, globalCost)

changepoints

is the vector of changepoints (we give the last element of each segment)

states

is the vector giving the state of each segment

forced

is the vector specifying whether the constraints of the graph are active (= TRUE) or not (= FALSE)

parameters

is the vector of successive parameters of each segment

globalCost

is a number equal to the total loss: the minimal cost for the optimization problem with all penalty values excluded

Dvect

is a vector of integers. The successive tested D in the Birgé Massart penalty until convergence

---

A small ChIP-seq data set in which peaks can be found using PeakSegFPOP

Description

The data come from an H3K27ac ChIP-seq experiment which was aligned to the human reference genome (hg19), aligned read counts were used to produce the coverage data; looking at these data in a genome browser was used to produce the labels.

Usage

data("Mono27ac")

Format

A list of 2 data.tables: coverage has 4 columns (chrom, chromStart, chromEnd, count=number of aligned reads at each position on chrom:chromStart-chromEnd); labels has 4 columns (chrom, chromStart, chromEnd, annotation=label at chrom:chromStart-chromEnd).

Source

https://github.com/tdhock/feature-learning-benchmark

---

Neuro spike train data

Description

The goal in these data is to detect the spikes = abrupt up changes in calcium concentration, which correspond to neurons firing in laboratory animals.

Usage

data("neuroSpike")

Format

A data frame with 20000 observations on the following 4 variables.

seconds

time of measurement

calcium

noisy data measured

AR1

autoregressive model mean, for comparison

TrueSpike

logical

Source

Spikefinder challenge, dataset number 7, cell number 13, subset 1:20000, 100 fps, for AR1: 0.98 exp decay parameter, 3.6 penalty parameter.

---

Node Values

Description

Constrain the range of values to consider at a node

Usage

Node(state = NULL, min = -Inf, max = Inf)

Arguments

state	a string defining the state to constrain
min	minimal value for the inferred parameter
max	maximal value for the inferred parameter

Value

a dataframe with 9 variables with only state1, min and max defined (not NA).

Examples

Node(state = "s0", min = 0, max = 2)

Node(state = 0, min = -1, max = 1)

Node(state = "positive", min = 0)

Node(state = "mu0", min = 0.5, max = 0.5)

---

Graphs of our paper in JSS

Description

Graphs of our paper in JSS (Journal of Statistical Software)

Usage

paperGraph(nb, penalty = 0, decay = 1, gap = 0, oneValue = 0, K = Inf, a = 0)

Arguments

nb	the number of the Figure in paper
penalty	the penalty to use for change-point
decay	a nonnegative number to give the strength of the exponential decay into the segment
gap	a nonnegative number to constrain the size of the gap in the change of state
oneValue	the value for parameter when we consider the collective anomalies problem
K	a positive number. Threshold for the Biweight robust loss
a	a positive number. Slope for the Huber robust loss

Value

a dataframe with 9 variables : columns are named "state1", "state2", "type", "parameter", "penalty", "K", "a", "min", "max" with additional "graph" class.

---

plot.gfpop

Description

Plotting inferred segment parameters (the result of gfpop) and data.

Usage

## S3 method for class 'gfpop'
plot(x, ..., data, multiple = TRUE)

Arguments

x	a gfpop class object
...	Other parameters
data	the data from which we get the gfpop result
multiple	if TRUE we plot data and the model on different graphs. Only with "mean" and "poisson" cost functions (as in that case the parameter values represent the data mean value over each segment) we allow the User to plot signal and data on a single graph.

Value

plot data and the inferred gfpop segments

Examples

n <- 1000 #data length
data <- dataGenerator(n, c(0.3, 0.4, 0.7, 0.95, 1), c(1, 3, 1, -1, 4), "mean", sigma = 3)
myGraph <- graph(type = "relevant", gap = 0.5, penalty = 2 * sdDiff(data) ^ 2 * log(n))
g <- gfpop(data, myGraph, type = "mean")
plot(x = g, data = data, multiple = FALSE)

data <- dataGenerator(n, c(0.4, 0.8, 1), c(1, 1.7, 2.3), "exp")
g <- gfpop(data,graph(type = "isotonic", penalty = 2 * sdDiff(data) ^ 2 * log(n)), type = "exp")
plot(x = g, data = data, multiple = TRUE)

data <- dataGenerator(n, c(0.22, 0.75, 1), c(1.4,1,0.8), "poisson")
g <- gfpop(data, paperGraph(8), type = "poisson")
plot(x = g, data = data, multiple = TRUE)

---

print.gfpop

Description

Printing the resulting change-point model found by gfpop function

Usage

## S3 method for class 'gfpop'
print(x, ...)

Arguments

x	a gfpop class object
...	Other parameters

Value

print the gfpop object

Examples

n <- 1000 #data length
data <- dataGenerator(n, c(0.3, 0.4, 0.7, 0.95, 1), c(1, 3, 1, -1, 4), "mean", sigma = 3)
myGraph <- graph(type = "relevant", gap = 0.5, penalty = 2 * sdDiff(data) ^ 2 * log(n))
g <- gfpop(data, myGraph, type = "mean")
print(g)

---

Labeled DNA copy number profile

Description

This DNA copy number data set has changepoint labels that are impossible to all predict correctly using the maximum likelihood gaussian changepoint model.

Usage

data("profile614chr2")

Format

Named list of two elements: probes is a data.table with 153663 noisy logratio observations in which we would like to detect changepoints; labels is a data.table with 8 rows that define regions with 1 or 0 breakpoints.

Source

https://github.com/vrunge/gfpop.data

References

Labels created with SegAnnDB software, Hocking et al., Bioinformatics 2014, doi:10.1093/bioinformatics/btu072.

---

sdDiff

Description

sdDiff is a function based on the difference operator (or difference order for HALL method) estimating the time-series standard deviation. The estimation works for time-series generated by Gaussian random variables with constant standard deviation and multiple changes in mean. Three estimators are available:

• HALL : the so-called HALL-estimator of order 3. For more details see: (1990) Asymptotically optimal difference-based estimation of variance in nonparametric regression. Authors: Hall, Peter and Kay, JW and Titterinton, DM. Biometrika, pages 521–528

• MAD : the median absolute deviation estimator computed on diff(x)/sqrt(2) with x the vector of datapoints

• SD : the standard deviation estimator (function sd) computed on diff(x)/sqrt(2) with x the vector of datapoints

Usage

sdDiff(x, method = "HALL")

Arguments

x	vector of datapoints
method	Three available methods: "HALL", "MAD" and "SD"

Value

a value equal to the estimated standard deviation

Examples

data <- dataGenerator(300, seq(0.1,1,0.1), sample(10), sigma = 2)
sdDiff(data, method = "HALL")
sdDiff(data, method = "MAD")
sdDiff(data, method = "SD")

---

Start and End nodes for the graph

Description

Defining the beginning and ending states of a graph

Usage

StartEnd(start = NULL, end = NULL)

Arguments

start	a vector of states. The beginning nodes for the changepoint inference
end	a vector of states. The ending nodes for the changepoint inference

Value

dataframe with 9 variables with only state1 and type = "start" or "end" defined (not NA).

Examples

StartEnd(start = "A", end = c("A","B"))

StartEnd(start = 0)

StartEnd(start = 1, end = 1)

StartEnd(start = "v0", end = "v3")

StartEnd(end = "s0")

---

summary.gfpop

Description

Returns all information contains in gfpop object

Usage

## S3 method for class 'gfpop'
summary(object, ...)

Arguments

object	a gfpop class object
...	Other parameters

Value

summary of gfpop object

Examples

n <- 1000 #data length
data <- dataGenerator(n, c(0.3, 0.4, 0.7, 0.95, 1), c(1, 3, 1, -1, 4), "mean", sigma = 3)
myGraph <- graph(type = "relevant", gap = 0.5, penalty = 2 * sdDiff(data) ^ 2 * log(n))
g <- gfpop(data, myGraph, type = "mean")
summary(g)

---