1.2.1 Run the Web Application with Docker (Optional)

Alternatively, if docker is installed, the DiscoRhythm container on Docker Hub can be pulled and used to run the web application locally avoiding the need to install DiscoRhythm and its dependencies (See instructions on Docker Hub).

3.3.1 Processed Metadata Table

The data extracted above is stored in the DiscoRhythm application as:

Note: If there are more groupings in the dataset or if the dataset does not fit into this design, it may be appropriate to split the dataset into subgroups that fit this design (each subgroup as one input dataset to DiscoRhythm).

4.3.1 Inter-sample Correlation

Purpose: Samples are pairwise correlated using either the Pearson or Spearman method of correlation to detect outliers.

Heatmap: The values of these pairwise correlations can be visualized in this tab, where samples with similar correlation values are grouped together using clustering.

Outlier Detection: The average correlation value for each sample is used as a metric of its overall similarity to all other samples and is summarized in this figure.

Samples with a high deviation below the mean will be flagged as outliers where the user may specify a number of standard deviations below the mean to use as a threshold.

Figure 3: Screenshot of the ‘Inter-sample Correlation’ section of the DiscoRhythm interface

4.3.2 Principal Component Analysis

Purpose: Utilize principal component analysis (PCA) to detect outliers.

PCA is used to extract the strongest recurring patterns in the dataset. Outliers detected in these patterns (PC scores) are flagged by their deviation from the mean where again the user may specify a threshold in units of standard deviations to use.

Scale Before PCA: Whether to scale rows to a standard deviation of 1 prior to PCA such that all rows are on an equal scale. Scaling is usually advisable.

PCs to Use For Outlier Detection: Click to change the list of PCs to use for outlier removal in the case a PC is determined inappropriate for use in outlier detection. You can remove unwanted PCs by pressing “delete” and add extra ones by typing their number.

Before CSV/After CSV: Downloadable summaries of the PCA before and after the detected outliers are removed.

Figures:

Distributions: The distributions of PC scores used to detect outliers. Only the PCs colored darkly are used for the final outlier flagging. Outliers will be shown with an ‘x’.

Scree: PCs are numbered where the amount of variance explained by each PC (therefore their ‘importance’) decreases with increasing PC number. This can be seen in the “Scree” figure. Users should choose an appropriate number of PCs to use for outlier detection by the shape of this scree plot.

One Pair and All Pairs: Plotting the PC scores of the components versus one another may reveal grouping that cannot be determined from simple analysis of individual PCs.

Figure 4: Screenshot of the ‘PCA’ section of the DiscoRhythm interface

4.3.3 Filtering Summary

Purpose: Determine how to proceed with outlier removal.

The user may at this point choose to remove the flagged outliers or may disregard these flags if it is suspected the dissimilarity of these samples may be biologically relevant. The user may also remove samples which they deem to be unreliable for further analysis by other metrics (e.g. experimental quality metrics).

Raw Distributions: A boxplot for each individual sample which can be used to further evaluate sample selection.

Input and Final: Shows summary tables for data before and after outlier removal.

Figure 5: Screenshot of the ‘Filtering Summary’ section of the DiscoRhythm interface

4.5.1 Period Detection

Purpose: Detecting the strength of a range of periods of oscillation across the entire dataset using a Cosinor based approach.

Spectral analysis will be limited33 For circular time, only harmonics of the base-cycle will be available for testing. from a smallest period of 3 times the sampling-interval up to the sampling duration and 12 periods will be tested evenly spaced across this range.

Note: Experiments typically have a hypothesized period length (such as the organisms period of activity) and that period should be used for analysis in section 4.6 when possible. When using this tool for determining which periodicity to use, follow up experiments may be appropriate for validation.

Figure 7: Screenshot of the ‘Period Detection’ section of the DiscoRhythm interface

4.5.2 PC fits

To determine the presence of a single rhythmic pattern in the data, PCA is performed to visualize and test the summarized temporal signal for rhythmicity (using the Cosinor method).

Figure 8: Screenshot of the ‘PC Cosinor Fits’ section of the DiscoRhythm interface

4.6.1 Rhythmicity Calculation Configuration

The user must choose a single period44 If it is unknown which periodicity to test start with the dominant period seen in section 4.5. of oscillation to test across all rows of the dataset. The application may show warnings/messages regarding the choice of period. By default, the period input in the ‘Select Data’ section will be chosen.

JTK Cycle, Lomb-Scargle, and ARSER results are all obtained through the MetaCycle R package (meta2d function using minper=maxper). Cosinor is a built-in function of DiscoRhythm. A brief summary of each method:

Cosinor - a.k.a “Harmonic Regression” Fits a sinusoid with a free phase parameter.
JTK Cycle - non-parametric test of rhythmicity robust to outliers.
Lomb-Scargle - an approach using spectral power density. ARSER - removes linear trends and performs the Cosinor test.

Exclusion Criteria Matrix: A table is presented which describes the criteria which exclude a method from use and shown are criteria which are true for the loaded dataset55 If no criteria are present, the table will be absent.. The reasons may be due to either computational (causes errors under given conditions) or statistical restrictions (requirements of study design) of the method.

Figure 9: Screenshot of the ‘Oscillation Detection (Preview)’ section of the DiscoRhythm interface

4.6.2 Visualizing Results

Once rhythmicity computation is completed, 3 sections become available for viewing the results:

Individual Models: Allows inspection of the raw data for individual rows of the dataset. User may click a row of the table to display the raw data and a fitted curve for that row. If the Cosinor method is being viewed, the line will be the Cosinor fit, all other methods utilize a loess fit. If the error bar option is selected, a 95% confidence interval on the mean will be displayed for each timepoint.

Summary: Summarizes calculated rhythm parameters across all tested rows by all executed methods.

Method Comparison: Offers pairwise comparison of rhythmic parameters calculated by each method to determine the degree of agreement between methods.

Figure 10: Screenshot of the ‘Oscillation Detection’ section of the DiscoRhythm interface

5.1.1 discoDFtoSE

The CSV inputs to the DiscoRhythm web interface described in section 3 can be read into R as a data.frame. To allow for users using the web application to use the same input for analysis in R, the function discoDFtoSE is available to convert the tabular input into an apporpriate format for analysis in R described in 5.1 above.

The sample metadata will be extracted from the column names by matching the format66 See ?discoParseMeta for regular expression specifications. described in section 3.3. The checks for validity and uniqueness mentioned in section 4.2 will also be performed. Alternatively, this metadata may also be input directly to discoDFtoSE as a data.frame.

Loading in the same example dataset as section 3 using discoGetSimu() to read in the CSV system file as a data.frame:

library(DiscoRhythm)
indata <- discoGetSimu()
knitr::kable(head(indata[,1:6]), format = "markdown") # Inspect the data

And importing as a SummarizedExperiment.

se <- discoDFtoSE(indata)

5.1.2 discoSEtoDF

The reverse operation, discoSEtoDF, is also available and is mainly intended for the purpose of exporting data as CSV for input to the web application.

write.csv(discoSEtoDF(se),file = "DiscoRhythmInputFile.csv",row.names = FALSE)

Will export data for usage in the web application.

5.1.3 discoCheckInput

This function performs the row-wise checks for missing values and constant values as mentioned in section 4.2.

selectDataSE <- discoCheckInput(se)

5.1.4 discoDesignSummary

The sample collection information present in colData(selectDataSE) can be summarized by the discoDesignSummary function to detail the number of biological and technical replicates available at each collection time. Number of technical replicates is shown in brackets.

library(SummarizedExperiment)
Metadata <- colData(selectDataSE)
knitr::kable(discoDesignSummary(Metadata),format = "markdown")

5.2.1 discoInterCorOutliers

Performs the analysis described in 4.3.1 to return some intermediate results and a vector indicating which samples were determined to be outliers.

CorRes <- discoInterCorOutliers(selectDataSE,
                                cor_method="pearson",
                                threshold=3,
                                thresh_type="sd")

5.2.2 discoPCAoutliers

Performs the analysis described in 4.3.2 to return some intermediate results and a vector indicating which samples were determined to be outliers.

PCAres <- discoPCAoutliers(selectDataSE,
                           threshold=3,
                           scale=TRUE,
                           pcToCut = c("PC1","PC2","PC3","PC4"))

5.2.3 discoPCA

A light wrapper was written for the stats::prcomp function for better use with the web application and it can be utilized as:

discoPCAres <- discoPCA(selectDataSE)

This returns the same output as prcomp with the addition of a reformatted summary table (available as PCAresAfter$table).

5.2.4 Filtering Summary

Below the results of the outlier detection analysis (CorRes and PCAres) are used to subset the data to remove outliers:

FilteredSE <- selectDataSE[,!PCAres$outliers & !CorRes$outliers]

DT::datatable(as.data.frame(
  colData(selectDataSE)[PCAres$outliers | CorRes$outliers,]
))

knitr::kable(discoDesignSummary(colData(FilteredSE)),format = "markdown")

5.3.1 discoRepAnalysis

Performs the analysis described in 4.4 returning the results of the ANOVA test and the se data object where technical replicates are combined.

ANOVAres <- discoRepAnalysis(FilteredSE,
                             aov_method="Equal Variance",
                             aov_pcut=0.05,
                             aov_Fcut=1,
                             avg_method="Median")

FinalSE <- ANOVAres$se

5.4.1 discoPeriodDetection

Performs the analysis described in 4.5 to return a data.frame of Cosinor fits across a range of periods.

PeriodRes <- discoPeriodDetection(FinalSE,
                                  timeType="linear",
                                  main_per=24)

The main period of interest is fit using a Cosinor model to principal component scores as described in 4.5.

OVpca <- discoPCA(FinalSE)
OVpcaSE <- discoDFtoSE(data.frame("PC"=1:ncol(OVpca$x),t(OVpca$x)),
                                  colData(FinalSE))
knitr::kable(discoODAs(OVpcaSE,period = 24,method = "CS")$CS,
             format = "markdown")

5.5.1 discoODAs

Performs the analysis described in 4.6.1 using just the Cosinor method. discoODAs will automatically run all appropraite methods if none are provided.

discoODAres <- discoODAs(FinalSE,
                         period=24,
                         method="CS",
                         ncores=1,
                         circular_t=FALSE)

5.6.1 discoBatch

The entire analysis performed in section 5 may be run through a single call to discoBatch() to obtain the final discoODAres results.

discoBatch(indata=indata,
  report="discoBatch_example.html",
  ncores=1,
  main_per=24,
  timeType="linear",
  cor_threshold=3,
  cor_method="pearson",
  cor_threshType="sd",
  pca_threshold=3,
  pca_scale=TRUE,
  pca_pcToCut=paste0("PC",seq_len(4)),
  aov_method="None",
  aov_pcut=0.05,
  aov_Fcut=0,
  avg_method="Median",
  osc_method="CS",
  osc_period=24)

This command will generate an html report called “discoBatch_example.html” which includes the visualizations seen in the DiscoRhythm application. indata may be in either of the two input formats described in 5.1 (data.frame or SummarizedExperiment).