org.broadinstitute.hellbender.tools.copynumber.utils.segmentation

Class KernelSegmenter<DATA>

java.lang.Object

org.broadinstitute.hellbender.tools.copynumber.utils.segmentation.KernelSegmenter<DATA>

public final class KernelSegmenter<DATA>
extends java.lang.Object

Segments data (i.e., finds multiple changepoints) using a method based on the kernel-segmentation algorithm described in https://hal.inria.fr/hal-01413230/document, which gives a framework to quickly calculate the cost of a segment given a low-rank approximation to a specified kernel. However, unlike the algorithm described there, which seeks to minimize a global segmentation cost, the method implemented here instead finds candidate changepoints based on the local costs within windows of various sizes.

Given N sequential data points of type DATA to segment, the basic steps of the method are:

1. Select C_max, the maximum number of changepoints to discover.
2. Select a kernel (linear for sensitivity to changes in the distribution mean, Gaussian with a specified variance for multimodal data, etc.) and a subsample of p points to approximate it using singular value decomposition. This is provided via a lambda of the form (DATA, DATA) -> double.
3. Select window sizes w_j for which to calculate local costs at each point. To be precise, we calculate the cost of a changepoint at the point with index i, assuming adjacent segments containing the points with indices [i - w_j + 1, i] and [i + 1, i + w_j].
4. For each of these cost functions, find (up to) the C_max most significant local minima. The problem of finding local minima of a noisy function can be solved by using topological persistence (see, e.g., https://www.csc.kth.se/~weinkauf/notes/persistence1d.html and http://www2.iap.fr/users/sousbie/web/html/indexd3dd.html?post/Persistence-and-simplification).
5. These sets of local minima from all window sizes together provide the pool of candidate changepoints (some of which may overlap exactly or approximately). We perform backward selection using the global segmentation cost. That is, we calculate the global segmentation cost given all the candidate changepoints, calculate the cost change for removing each of the changepoints individually, remove the changepoint with the minimum cost change, and repeat. This gives the global cost as a function of the number of changepoints C.
6. Add a penalty A * C + B * C * log (N / C) to the global cost and find the minimum to determine the number of changepoints, where A and B are specified penalty factors.

Note that we break with camelCase naming convention in places to match some notation in the paper

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	KernelSegmenter.ChangepointSortOrder

Constructor Summary

Constructors

Constructor and Description
KernelSegmenter(java.util.List<DATA> data)

Method Summary

Modifier and Type

Method and Description

java.util.List<java.lang.Integer>

findChangepoints(int maxNumChangepoints, java.util.function.BiFunction<DATA,DATA,java.lang.Double> kernel, int kernelApproximationDimension, java.util.List<java.lang.Integer> windowSizes, double numChangepointsPenaltyLinearFactor, double numChangepointsPenaltyLogLinearFactor, KernelSegmenter.ChangepointSortOrder changepointSortOrder) Returns a list of the indices of the changepoints, either sorted by decreasing change to the global segmentation cost or by increasing index order.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

KernelSegmenter

public KernelSegmenter(java.util.List<DATA> data)

Method Detail

findChangepoints

public java.util.List<java.lang.Integer> findChangepoints(int maxNumChangepoints,
                                                          java.util.function.BiFunction<DATA,DATA,java.lang.Double> kernel,
                                                          int kernelApproximationDimension,
                                                          java.util.List<java.lang.Integer> windowSizes,
                                                          double numChangepointsPenaltyLinearFactor,
                                                          double numChangepointsPenaltyLogLinearFactor,
                                                          KernelSegmenter.ChangepointSortOrder changepointSortOrder)

Returns a list of the indices of the changepoints, either sorted by decreasing change to the global segmentation cost or by increasing index order.

Parameters:

maxNumChangepoints - maximum number of changepoints to return (first and last points do not count towards this number)

kernel - kernel function used to calculate segment costs

kernelApproximationDimension - dimension of low-rank approximation to the kernel

windowSizes - list of sizes to use for the flanking segments used to calculate local changepoint costs

numChangepointsPenaltyLinearFactor - factor A for penalty of the form A * C, where C is the number of changepoints

numChangepointsPenaltyLogLinearFactor - factor B for penalty of the form B * C * log (N / C), where C is the number of changepoints and N is the number of data points

changepointSortOrder - sort by decreasing change to the global segmentation cost or by increasing index order