gvtrack.create: Creates a new virtual track

Description

Creates a new virtual track.

Usage

gvtrack.create(vtrack = NULL, src = NULL, func = NULL, params = NULL, ...)

Value

None.

Arguments

vtrack: virtual track name
src: source (track/intervals). NULL for PWM functions
func: function name (see above)
params: function parameters (see above)
...: additional PWM parameters

Details

This function creates a new virtual track named 'vtrack' with the given source, function and parameters. 'src' can be either a track or intervals (1D or 2D). Use the following table for a reference of all valid source, function and parameters combinations:

src = [Track], func = "avg", params = NULL
Average track value in iterator interval.

src = [Track], func = "max", params = NULL
Maximal track value in iterator interval.

src = [Track], func = "min", params = NULL
Minimal track value in iterator interval.

src = ['Dense' / 'Sparse' / 'Array' track], func = "nearest", params = NULL
Mean track value in iterator interval. If there are no track values covered by an iterator interator (can occur only in 'Sparse' track), the nearest track value is returned.

src = ['Dense' / 'Sparse' / 'Array' track], func = "stddev", params = NULL
Unbiased standard deviation of track values in iterator interval.

src = ['Dense' / 'Sparse' / 'Array' track], func = "sum", params = NULL
Sum of track values in iterator interval.

src = ['Dense' / 'Sparse' / 'Array' track], func = "quantile", params = [Percentile in the range of [0, 1]]
Quantile of track values in iterator interval.

src = ['Dense' track], func = "global.percentile", params = NULL
Percentile of an average track value in iterator interval relatively to all values of the track.

src = ['Dense' track], func = "global.percentile.max", params = NULL
Percentile of a maximal track value in iterator interval relatively to all values of the track.

src = ['Dense' track], func = "global.percentile.min", params = NULL
Percentile of a minimal track value in iterator interval relatively to all values of the track.

src = [2D track], func = "area", params = NULL
Area covered by iterator interval.

src = [2D track], func = "weighted.sum", params = NULL
Weighted sum of values where each weight equals to the intersection area between the iterator interval and the rectangle containing the value.

src = [1D intervals], func = "distance", params = [Minimal distance from center (default: 0)]
Given the center 'C' of the current iterator interval returns 'DC * X/2', where 'DC' is the normalized distance to the center of the interval that contains 'C', and 'X' is the value of the parameter. If no interval contains 'C' the resulted value is 'D + XXX/2' where 'D' is the distance between 'C' and the edge of the closest interval. Distance can be positive or negative depending on the position of the coordinate relative to the interval and the strand (-1 or 1) of the interval. Distance is always positive if 'strand' is '0' or if 'strand' column is missing. Distance is 'NA' if no intervals exist for the current chromosome.

src = [1D intervals], func = "distance.center", params = NULL
Given the center 'C' of the current iterator interval returns 'NaN' if 'C' is outside of the intervals, otherwise returns the distance between 'C' and the center of the closest interval. Distance can be positive or negative depending on the position of the coordinate relative to the interval and the strand (-1 or 1) of the interval. Distance is always positive if 'strand' is '0' or if 'strand' column is missing.

src = [1D intervals], func = "coverage", params = NULL
For each iterator interval, calculates the fraction of its length that is covered by the source intervals. Returns a value between 0 and 1. For example, if an iterator interval is [100,200] and the source intervals cover positions 120-140 and 160-170, the coverage would be 0.3 ((20 + 10) / 100 = 0.3). Overlapping source intervals are first unified.

func = "pwm", params = list(pssm = matrix, bidirect = TRUE, prior = 0.01, extend = TRUE)
Calculates total log-likelihood score of DNA sequence against PSSM. Uses log-sum-exp over all positions. For bidirect=TRUE, scans both strands. Prior adds pseudocounts, extend=TRUE allows scoring at boundaries.

func = "pwm.max", params = list(pssm = matrix, bidirect = TRUE, prior = 0.01, extend = TRUE)
Returns maximum log-likelihood score of best PSSM match. bidirect=TRUE checks both strands. Prior adds pseudocounts, extend=TRUE allows boundary scoring.

func = "pwm.max.pos", params = list(pssm = matrix, bidirect = TRUE, prior = 0.01, extend = TRUE)
Returns 1-based position of best PSSM match. If bidirect=TRUE, the position would be positive if the best hit was at the forward strand, and negative if it was at the reverse strand. When strand is -1 the position is still according to the forward strand, but the hit is at the end of the match. Prior adds pseudocounts, extend=TRUE allows boundary scoring.

For all PWM functions:

pssm: Position-specific scoring matrix (A,C,G,T frequencies)
bidirect: If TRUE, scans both strands; if FALSE, forward only
prior: Pseudocount for frequencies (default: 0.01)
extend: If TRUE, computes boundary scores
strand: If 1, scans forward strand; if -1, scans reverse strand. For strand == 1, the energy (and position of the best match) would be at the beginning of the match, for strand == -1, the energy (and position of the best match) would be at the end of the match.

PWM parameters are accepted as list or individual parameters (see examples).

func = "kmer.count", params = list(kmer = "ACGT", extend = TRUE, strand = 0)
Counts occurrences of the specified kmer in each interval. The extend=TRUE parameter (default) allows counting kmers that span interval boundaries. The strand parameter can be 1 (forward strand), -1 (reverse strand), or 0 (both strands).

func = "kmer.frac", params = list(kmer = "ACGT", extend = TRUE, strand = 0)
Calculates the fraction of possible positions in each interval that contain the specified kmer. The extend=TRUE parameter (default) allows counting kmers that span interval boundaries. The strand parameter can be 1 (forward strand), -1 (reverse strand), or 0 (both strands).

For kmer functions:

kmer: The DNA sequence to count (case-insensitive)
extend: If TRUE, counts kmers that span interval boundaries
strand: If 1, counts kmers on forward strand; if -1, counts kmers on reverse strand. If 0, counts kmers on both strands. Default is 0.

Kmer parameters are accepted as list or individual parameters (see examples). Note that for palindromic kmers, setting strand to 1 or -1 is recommended to avoid double counting.

Modify iterator behavior with 'gvtrack.iterator' or 'gvtrack.iterator.2d'.

Examples

Run this code

# \dontshow{
options(gmax.processes = 2)
# }

gdb.init_examples()

gvtrack.create("vtrack1", "dense_track", "max")
gvtrack.create("vtrack2", "dense_track", "quantile", 0.5)
gextract("dense_track", "vtrack1", "vtrack2",
    gintervals(1, 0, 10000),
    iterator = 1000
)

gvtrack.create("vtrack3", "dense_track", "global.percentile")
gvtrack.create("vtrack4", "annotations", "distance")
gdist(
    "vtrack3", seq(0, 1, l = 10), "vtrack4",
    seq(-500, 500, 200)
)

gvtrack.create("cov", "annotations", "coverage")
gextract("cov", gintervals(1, 0, 1000), iterator = 100)

pssm <- matrix(
    c(
        0.7, 0.1, 0.1, 0.1, # Example PSSM
        0.1, 0.7, 0.1, 0.1,
        0.1, 0.1, 0.7, 0.1,
        0.1, 0.1, 0.7, 0.1,
        0.1, 0.1, 0.7, 0.1,
        0.1, 0.1, 0.7, 0.1
    ),
    ncol = 4, byrow = TRUE
)
colnames(pssm) <- c("A", "C", "G", "T")
gvtrack.create(
    "motif_score", NULL, "pwm",
    list(pssm = pssm, bidirect = TRUE, prior = 0.01)
)
gvtrack.create("max_motif_score", NULL, "pwm.max",
    pssm = pssm, bidirect = TRUE, prior = 0.01
)
gvtrack.create("max_motif_pos", NULL, "pwm.max.pos",
    pssm = pssm
)
gextract(
    c(
        "dense_track", "motif_score", "max_motif_score",
        "max_motif_pos"
    ),
    gintervals(1, 0, 10000),
    iterator = 500
)

# Kmer counting examples
gvtrack.create("cg_count", NULL, "kmer.count", kmer = "CG", strand = 1)
gvtrack.create("cg_frac", NULL, "kmer.frac", kmer = "CG", strand = 1)
gextract(c("cg_count", "cg_frac"), gintervals(1, 0, 10000), iterator = 1000)

gvtrack.create("at_pos", NULL, "kmer.count", kmer = "AT", strand = 1)
gvtrack.create("at_neg", NULL, "kmer.count", kmer = "AT", strand = -1)
gvtrack.create("at_both", NULL, "kmer.count", kmer = "AT", strand = 0)
gextract(c("at_pos", "at_neg", "at_both"), gintervals(1, 0, 10000), iterator = 1000)

# GC content
gvtrack.create("g_frac", NULL, "kmer.frac", kmer = "G")
gvtrack.create("c_frac", NULL, "kmer.frac", kmer = "C")
gextract("g_frac + c_frac", gintervals(1, 0, 10000),
    iterator = 1000,
    colnames = "gc_content"
)