impulse_DE: Differential expression analysis using impulse models

Description Usage Arguments Details Value Author(s) References See Also Examples


Fits an impulse model to time course data and uses this model as a basis to detect differentially expressed (DE) genes. If a single time course data set is given, DE genes are detected over time, whereas if an additional control time course data set is present, DE genes are detected between both datasets.


impulse_DE(expression_table = NULL, annotation_table = NULL,
  colname_time = NULL, colname_condition = NULL,
  control_timecourse = FALSE, control_name = NULL, case_name = NULL,
  expr_type = "Array", plot_clusters = TRUE, n_iter = 100,
  n_randoms = 50000, n_process = 4, Q_value = 0.01, new_device = TRUE)



numeric matrix of expression values; genes should be in rows, samples in columns. Data should be properly normalized and log2-transformed as well as filtered for present or variable genes.


table providing co-variables for the samples including condition and time points. Time points must be numeric numbers.


character string specifying the column name of the co-variable "Time" in annotation_table


character string specifying the column name of the co-variable "Condition" in annotation_table


logical indicating whether a control time timecourse is part of the data set (TRUE) or not (FALSE). Default is FALSE.


character string specifying the name of the control condition in annotation_table.


character string specifying the name of the case condition in annotation_table. Should be set if more than two conditions are present in annotation_table.


character string with allowed values "Array" or "Seq". Default is "Array".


logical indicating whether to plot the clusters (TRUE) or not (FALSE). Default is TRUE.


numeric value specifying the number of iterations, which are performed to fit the impulse model to the clusters. Default is 100.


numeric value specifying the number of generated randomized background iterations, which are used for differential expression analysis. Default is 50000 and this value should not be decreased.


numeric value indicating the number of processes, which can be used on the machine to run calculations in parallel. Default is 4. The specified value is internally changed to min(detectCores() - 1, n_process) using the detectCores function from the package parallel to avoid overload.


numeric value specifying the cutoff to call genes significantly differentially expressed after FDR correction (adjusted p-value). Default is 0.01.


logical indicating whether each plot should be plotted into a new device (TRUE) or not (FALSE). Default is TRUE.


ImpulseDE is based on the impulse model proposed by Chechik and Koller, which reflects a two-step behavior of genes within a cell responding to environmental changes (Chechik and Koller, 2009). To detect differentially expressed genes, a five-step workflow is followed:

  1. The genes are clustered into a limited number of groups using k-means clustering. If plot_clusters = TRUE, the clusters are plotted.

  2. The impulse model is fitted to the mean expression profiles of the clusters. The best parameter sets are then used for the next step.

  3. The impulse model is fitted to each gene separately using the parameter sets from step 2 as optimal start point guesses.

  4. The impulse model is fitted to a randomized dataset (bootstrap), which is essential to detect significantly differentially expressed genes (Storey et al., 2005).

  5. Detection of differentially expressed genes utilizing the fits to the real and randomized data sets. FDR-correction is performed to obtain adjusted p-values (Benjamini and Hochberg, 1995).


List containing the following elements:

  • impulse_fit_results List containing fitted values and model parameters:

    • impulse_parameters_case Matrix of fitted impulse model parameters and sum of squared fitting errors for the case dataset. If a control time course is present, corresponding list entries will exist for the control and the combined dataset as well (named impulse_parameters_control and impulse_parameters_combined, respectively).

    • impulse_fits_case Matrix of impulse values calculated based on the analyzed time points and the fitted model parameters for the combined dataset. If a control time course is present, corresponding list entries will exist for the control and the combined dataset as well (named impulse_fits_control and impulse_fits_combined, respectively).

  • DE_results List containg the results from the differential expression analysis:

    • DE_genes data.frame containing the names of genes being called as differentially expressed according to the specified cutoff Q_value together with the adjusted p-values.

    • pvals_and_flags data.frame containing all gene names together with the adjusted p-values and flags for differential expression according to additional tests.

  • clustering_results List containing the clustering results:

    • kmeans_clus_case Numeric vector of clusters IDs, to which the genes were finally assigned.

    • cluster_means_case Matrix containing the mean expression values for each cluster (taken over all genes assigned to a cluster).

    • pre_clus_case Numeric number of clusters determined after the first (preliminary) clustering step.

    • fine_clus_case Numeric number of final clusters determined after the second clustering step.

    If a control time course is present, those four list entries will exist correspondingly for the control and the combined dataset as well (ending with _control and _combined instead of _case, respectively).


Jil Sander


Benjamini, Y. and Hochberg, Y. (1995) Controlling the false discovery rate: a practical and powerful approach to multiple testing. J. R. Stat. Soc. Series B Stat. Methodol., 57, 289-300.

Storey, J.D. et al. (2005) Significance analysis of time course microarray experiments. Proc. Natl. Acad. Sci. USA, 102, 12837-12841.

Rangel, C., Angus, J., Ghahramani, Z., Lioumi, M., Sotheran, E., Gaiba, A., Wild, D.L., Falciani, F. (2004) Modeling T-cell activation using gene expression profiling and state-space models. Bioinformatics, 20(9), 1361-72.

Chechik, G. and Koller, D. (2009) Timing of Gene Expression Responses to Envi-ronmental Changes. J. Comput. Biol., 16, 279-290.

Yosef, N. et al. (2013) Dynamic regulatory network controlling TH17 cell differentiation. Nature, 496, 461-468.

See Also

plot_impulse, calc_impulse.


#' Install package longitudinal and load it
#' Attach datasets
#' check dimension of data matrix of interest
#' generate a proper annotation table
annot <-"Time" =
   "Condition" = "activated"), stringsAsFactors = FALSE)
#' Time columns must be numeric
annot$Time <- as.numeric(annot$Time)
#' rownames of annotation table must appear in data table
rownames(annot) = rownames(tcell.10)
#' apply ImpulseDE in single time course mode
#' since genes must be in rows, transpose data matrix using t()
#' For the example, reduce iterations to 10, randomizations to 50, number of
#' genes to 20 and number of used processors to 1:
impulse_results <- impulse_DE(t(tcell.10)[1:20,], annot, "Time", "Condition",
   n_iter = 10, n_randoms = 50, n_process = 1)

Search within the ImpulseDE package
Search all R packages, documentation and source code

Questions? Problems? Suggestions? or email at

Please suggest features or report bugs with the GitHub issue tracker.

All documentation is copyright its authors; we didn't write any of that.