FNTN_matrix.recycle

Description

Recycle an expansion matrix

Usage

FNTN_matrix.recycle(
  FNTN_matrix,
  B_FN_old,
  B_TN_old,
  B_FN_new,
  B_TN_new,
  xp_FN,
  xp_TN,
  par
)

Arguments

F_beta

Description

Compute a F_beta score comparing two boolean vectors

Usage

F_beta(pred, truth, beta = 1)

Arguments

Examples

data(Samusik_01_subset)
truth=c(rep(TRUE,40),rep(FALSE,60))
pred=rep(c(TRUE,FALSE),50)
table(pred,truth) ##40% purity, 50% yield
#' F_beta(pred=pred,truth=truth,beta=2) ##Closer to yield
F_beta(pred=pred,truth=truth,beta=1.5) ##Closer to yield
F_beta(pred=pred,truth=truth,beta=1) ##Harmonic mean
F_beta(pred=pred,truth=truth,beta=0.75) ##Closer to purity
F_beta(pred=pred,truth=truth,beta=0.5) ##Closer to purity

2000 events randomly sampled from the 'Samusik_01' dataset

Description

2000 events randomly sampled from the 'Samusik_01' dataset

Usage

Samusik_01_subset

Format

list with four elements: fs_src (a flowSet), xp_src (its expression matrix), labels (manual gates of the events) and tsne (a tSNE projection of the dataset)

References

https://flowrepository.org/id/FR-FCM-ZZPH

boolmat

Description

Convert an expression matrix and a gating strategy to a boolean matrix (whether each event is gated out by each channel)

Usage

boolmat(gate, xp)

Arguments

Examples

data(Samusik_01_subset)
xp=Samusik_01_subset$xp_src
gate_vector=Samusik_01_subset$labels
hg=hypergate(xp=xp,gate_vector=gate_vector,level=23,delta_add=0.01)
head(boolmat(hg,xp))

channels_contributions

Description

Gives scores for the contribution of individual channels to a gating strategy

Usage

channels_contributions(gate, xp, gate_vector, level, beta = 1)

Arguments

Examples

data(Samusik_01_subset)
xp=Samusik_01_subset$xp_src[,Samusik_01_subset$regular_channels]
gate_vector=Samusik_01_subset$labels
hg=hypergate(xp=xp,gate_vector=gate_vector,level=23,delta_add=0)
contribs=channels_contributions(gate=hg,xp=xp,gate_vector=gate_vector,level=23,beta=1)
contribs

Colors a biplot according to a vector with discrete values

Description

Colors a biplot according to a vector with discrete values

Usage

color_biplot_by_discrete(
  matrix,
  discrete_vector,
  ...,
  bty = "l",
  pch = 16,
  cex = 0.5,
  colors = NULL
)

Arguments

Examples

data(Samusik_01_subset)
levels=unique(sort(Samusik_01_subset$labels))
colors=setNames(colorRampPalette(palette())(length(levels)),sort(levels))
with(Samusik_01_subset,color_biplot_by_discrete(matrix=tsne,discrete_vector=labels,colors=colors))

contract

Description

Test (some) possible contractions of the hyperrectangle

Usage

contract(
  par = par,
  xp_pos = envir$xp_pos,
  state_pos = envir$state_pos,
  xp_neg = envir$xp_neg,
  state_neg = envir$state_neg,
  n = envir$n,
  TP = envir$TP,
  TN = envir$TN,
  beta = envir$beta2,
  envir = parent.frame()
)

Arguments

contract.update

Description

Update the hyperrectangle to the best contraction move found

Usage

contract.update(
  contract_object,
  pars = envir$pars,
  active_channels = envir$active_channels,
  b_pos = envir$b_pos,
  b_neg = envir$b_neg,
  state_pos = envir$state_pos,
  state_neg = envir$state_neg,
  TN = envir$TN,
  TP = envir$TP,
  xp_pos = envir$xp_pos,
  xp_neg = envir$xp_neg,
  envir = parent.frame()
)

Arguments

coreloop

Description

Core optimization loop of hypergate

Usage

coreloop(par, hg.env = hg.env$hg.env)

Arguments

Wrapper to locator that plots segments on the fly

Description

Wrapper to locator that plots segments on the fly

Usage

en.locator()

expand

Description

Test (some) possible expansions of the hyperrectangle

Usage

expand(
  FN = envir$FN,
  FNTN_matrix = envir$FNTN_matrix,
  TP = envir$TP,
  TN = envir$TN,
  n = envir$n,
  beta = envir$beta2,
  envir = parent.frame()
)

Arguments

expand.update

Description

Update the hyperrectangle to the best expansion move found

Usage

expand.update(
  expand.object,
  pars = envir$pars,
  xp_pos = envir$xp_pos,
  xp_neg = envir$xp_neg,
  state_pos = envir$state_pos,
  state_neg = envir$state_neg,
  b_pos = envir$b_pos,
  b_neg = envir$b_neg,
  n = envir$n,
  TP = envir$TP,
  TN = envir$TN,
  envir = parent.frame()
)

Arguments

f

Description

Computes the F_beta score given an intenger number of True Positives (TP), True Negatives (TN). It is optimized for speed and n is thus not the total number of events

Usage

f(TP, TN, n, beta2 = 1)

Arguments

fill_FNTN_matrix

Description

fill_FNTN_matrix Used for assessing whether an expansion move is possible

Usage

fill_FNTN_matrix(xp_FN, xp_TN, B_FN, B_TN, par)

Arguments

gate_from_biplot

Description

From a biplot let the user interactively draw polygons to create a "Gate" vector

Usage

gate_from_biplot(
  matrix,
  x_axis,
  y_axis,
  ...,
  bty = "l",
  pch = 16,
  cex = 0.5,
  sample = NULL
)

Arguments

Details

Data will be displayed as a bi-plot according to user-specified x_axis and y_axis arguments, then a call to locator() is made. The user can draw a polygon around parts of the plot that need gating. When done, 'right-click' or 'escape' (depending on the IDE) escapes locator() and closes the polygon. Then the user can press "n" to draw another polygon (that will define a new population), "c" to cancell and draw the last polygon again, or "s" to exit. When exiting, events that do not fall within any polygon are assigned NA, the others are assigned an integer value corresponding to the last polygon they lie into.

Value

A named vector of length nrow(matrix) and names rownames(matrix). Ungated events are set to NA

Examples

if(interactive()){
    ##See the details section to see how this function works
    gate_from_biplot(matrix=Samusik_01_subset$tsne,x_axis="tSNE1",y_axis="tSNE2")
}

hgate_info

Description

Extract information about a hypergate return: the channels of the phenotype, the sign of the channels, the sign of the comparison, the thresholds. The function could also compute the Fscores if the xp, gate_vector and level parameters are given.

Usage

hgate_info(hgate, xp, gate_vector, level, beta = 1)

Arguments

Value

A data.frame with channel, sign, comp and threshold columns, and optionnally deltaF (score deterioration when parameter is ignored),Fscore1d (F_value when using only this parameter) and Fscore (F score when all parameters up to this one are included). Fscores are computed if xp, gate_vector and level are passed to the function.

See Also

hg_pheno, hg_rule

Examples

data(Samusik_01_subset)
xp=Samusik_01_subset$xp_src[,Samusik_01_subset$regular_channels]
gate_vector=Samusik_01_subset$labels
hg=hypergate(xp=xp,gate_vector=gate_vector,level=23,delta_add=0.01)
hgate_info(hgate=hg)
hgate_pheno(hgate=hg)
hgate_rule(hgate=hg)

hgate_pheno

Description

Build a human readable phenotype, i.e. a combination of channels and sign (+ or -) from a hypergate return.

Usage

hgate_pheno(hgate, collapse = ", ")

Arguments

Value

A string representing the phenotype.

See Also

hg_rule, hg_info

Examples

## See hgate_info

hgate_rule

Description

Build a human readable rule i.e. a combination of channels, sign of comparison and threshold.

Usage

hgate_rule(hgate, collapse = ", ", digits = 2)

Arguments

Value

A data.frame with channel, sign, comp and threshold columns

See Also

hg_pheno, hg_rule

Examples

## See hgate_info

hgate_sample

Description

Downsample the data in order to fasten the computation and reduce the memory usage.

Usage

hgate_sample(gate_vector, level, size = 1000, method = "prop")

Arguments

Value

A logical vector with TRUE correspond to the events being sampled, ie kept to further analysis

Note

No replacement is applied. If there are less events in one group or the alternate than the algorithm requires, then all available events are returned. NA values in gate_vector are not sampled, ie ignored.

Examples

# Standard procedure with downsampling
data(Samusik_01_subset)
xp <- Samusik_01_subset$xp_src[,Samusik_01_subset$regular_channels]
gate_vector <- Samusik_01_subset$labels
sampled <- hgate_sample(gate_vector, level=8, 100)
table(sampled)
table(gate_vector[sampled])
xp_sampled <- xp[sampled, ]
gate_vector_sampled <- gate_vector[sampled]
hg <- hypergate(xp_sampled, gate_vector_sampled, level=8, delta_add=0.01)
# cluster 8 consists in 122 events
table(gate_vector)
# Downsampling
table(gate_vector[hgate_sample(gate_vector, level=8, 100)])
# Downsampling reduces the alternate events
table(gate_vector[hgate_sample(gate_vector, level=8, 100, "10x")])
# Downsampling is limited to the maximum number of events of interest
table(gate_vector[hgate_sample(gate_vector, level=8, 150)])
# Downsampling is limited to the maximum number of events of interest, and
# the alternate events are downsampled to a total of 10 times
table(gate_vector[hgate_sample(gate_vector, level=8, 150, "10x")])
# More details about sampling
# Convert -1 to NA, NA are not sampled
gate_vector[gate_vector==-1] = NA
gate_vector = factor(gate_vector)
table(gate_vector, useNA = "alw")
#
# target size = 100 whereas initial freq is 122 for pop 8
smp.prop = hgate_sample(gate_vector, level = 8, size = 100, method = "prop")
smp.10x  = hgate_sample(gate_vector, level = 8, size = 100, method = "10x")
smp.ceil = hgate_sample(gate_vector, size = 10, method = "ceil")
table(smp.prop)
table(smp.10x)
table(smp.ceil)
rbind(raw = table(gate_vector),
      prop = table(gate_vector[smp.prop]),
      `10x` = table(gate_vector[smp.10x]),
      ceil = table(gate_vector[smp.ceil]))
#
# target size = 30 whereas initial freq is 25 for pop 14
smp.prop = hgate_sample(gate_vector, level = 14, size = 30, method = "prop")
smp.10x  = hgate_sample(gate_vector, level = 14, size = 30, method = "10x")
table(smp.prop)
table(smp.10x)
rbind(raw = table(gate_vector),
      prop = table(gate_vector[smp.prop]),
      `10x` = table(gate_vector[smp.10x]))
# prop returns original data, because target size ids larger than initial freq
# 10x  returns sampled data according to initial freq, such as the total amount
# of other events equals 10x initial freq of pop 14

hypergate

Description

Finds a hyperrectangle gating around a population of interest

Usage

hypergate(xp, gate_vector, level, delta_add = 0, beta = 1, verbose = FALSE)

Arguments

See Also

channels_contributions for ranking parameters within the output, reoptimize_strategy for reoptimizing a output on a subset of the markers, plot_gating_strategy for plotting an output, subset_matrix_hg to apply the output to another input matrix, boolmat to obtain a boolean matrix stating which events are filtered out because of which markers

Examples

data(Samusik_01_subset)
xp=Samusik_01_subset$xp_src[,Samusik_01_subset$regular_channels]
gate_vector=Samusik_01_subset$labels
hg=hypergate(xp=xp,gate_vector=gate_vector,level=23,delta_add=0.01)

plot_gating_strategy

Description

Plot a hypergate return

Usage

plot_gating_strategy(
  gate,
  xp,
  gate_vector,
  level,
  cex = 0.5,
  highlight = "black",
  path = "./",
  ...
)

Arguments

Examples

data(Samusik_01_subset)
xp=Samusik_01_subset$xp_src[,Samusik_01_subset$regular_channels]
gate_vector=Samusik_01_subset$labels
hg=hypergate(xp=xp,gate_vector=gate_vector,level=23,delta_add=0.01)
par(mfrow=c(1,ceiling(length(hg$active_channels)/2)))
plot_gating_strategy(gate=hg,xp=xp,gate_vector=gate_vector,level=23,highlight="red")

Remove self intersection in polygons

Description

Remove self intersection in polygons

Usage

polygon.clean(poly)

Arguments

Value

A polygon without overlapping edges and new vertices corresponding to non-inner points of intersection

reoptimize_strategy

Description

Optimize a gating strategy given a manual selection of channels

Usage

reoptimize_strategy(
  gate,
  channels_subset,
  xp,
  gate_vector,
  level,
  beta = 1,
  verbose = FALSE
)

Arguments

Examples

data(Samusik_01_subset)
xp=Samusik_01_subset$xp_src[,Samusik_01_subset$regular_channels]
gate_vector=Samusik_01_subset$labels
hg=hypergate(xp=xp,gate_vector=gate_vector,level=23,delta_add=0)
contribs=channels_contributions(gate=hg,xp=xp,gate_vector=gate_vector,level=23,beta=1)
significant_channels=names(contribs)[contribs>=0.01]
hg_reoptimized=reoptimize_strategy(gate=hg,channels_subset=significant_channels,xp,gate_vector,23)

subset_matrix_hg

Description

Returns a boolean vector whose TRUE elements correspond to events inside the hyperrectangle

Usage

subset_matrix_hg(gate, xp)

Arguments

Examples

data(Samusik_01_subset)
xp=Samusik_01_subset$xp_src[,Samusik_01_subset$regular_channels]
gate_vector=Samusik_01_subset$labels
hg=hypergate(xp=xp,gate_vector=gate_vector,level=23,delta_add=0.01)
gating_state=subset_matrix_hg(hg,xp)
gating_state=ifelse(gating_state,"Gated in","Gated out")
target=ifelse(gate_vector==23,"Target events","Others")
table(gating_state,target)

Updates a gate vector

Description

Updates a gate vector

Usage

update_gate(xp, polygon, gate_vector = rep(0, nrow(xp)), value = 1)

Arguments

Value

The updated gate_vector