Vignette fix

CITATION.cff

@@ -0,0 +1,30 @@
+# YAML 1.2
+---
+authors: 
+  -
+    family-names: Pai
+    given-names: Shraddha
+  -
+    family-names: Shah
+    given-names: Ahmad
+  -
+    family-names: Hui
+    given-names: Shirley
+  -
+    family-names: Isserlin
+    given-names: Ruth
+  -
+    family-names: Kaka
+    given-names: Hussam
+  -
+    family-names: Bader
+    given-names: Gary
+cff-version: "1.1.0"
+date-released: 2019
+doi: "10.15252/msb.20188497"
+license: MIT
+message: "If you use this software, please cite it using these metadata."
+repository-code: "https://github.com/RealPaiLab/netDx"
+title: "netDx: Network-based patient classifier"
+version: "1.5.5"
+...

R/fileCache.R

@@ -24,11 +24,11 @@ getGMjar_path <- function(verbose = FALSE) {
 	)
 	if (any(grep(" 11",java_ver)) || any(grep(" 12",java_ver)) || any(grep(" 13",java_ver)) || any(grep(" 14",java_ver)) || any(grep(" 16",java_ver))) {
 		if (verbose) message("Java 11+ detected")
-    	fileURL <- paste("https://download.baderlab.org/netDx/java11/", 
+    	fileURL <- paste("https://downloads.res.oicr.on.ca/pailab/netDx/java11/", 
 			"genemania-netdx.jar",sep="")
 	} else {
 		if (verbose) message("Java 8 detected")
-    	fileURL <- paste("https://download.baderlab.org/netDx/java8/", 
+    	fileURL <- paste("https://downloads.res.oicr.on.ca/pailab/netDx/java8/", 
 			"genemania-netdx.jar",sep="")
 	}
 
@@ -72,7 +72,7 @@ fetchPathwayDefinitions <- function(month=NULL,year=NULL,day=1,verbose=FALSE){
 		month <- month.name[month]
 	}
 		pdate <- sprintf("%s_%02d_%i",month,day,year)
-    	pathwayURL <- paste("https://downloads.res.oicr.on.ca/pailab/EM_Genesets/", 
+    	pathwayURL <- paste("https://downloads.res.oicr.on.ca/pailab/public/EM_Genesets/", 
 		sprintf("%s/Human/symbol/",pdate),
         sprintf("Human_AllPathways_%s_symbol.gmt",pdate),
 		 sep = "")
@@ -83,7 +83,7 @@ fetchPathwayDefinitions <- function(month=NULL,year=NULL,day=1,verbose=FALSE){
 	if (chk$status_code==404) {
 		stop(paste(sprintf("The pathway file for %02d %s %i doesn't exist.",day,month,year),
 				"Select a different date. ",
-				"See https://downloads.res.oicr.on.ca/pailab/EM_Genesets/Human/symbol for options.",
+				"See https://downloads.res.oicr.on.ca/pailab/public/EM_Genesets/Human/symbol for options.",
 				sep=" "))
 	}
     bfcrpath(bfc, pathwayURL)

README.md

@@ -1,3 +1,8 @@
+# netDx: Network-based patient classifier
+[![Docker Build](https://github.com/RealPaiLab/netDx/actions/workflows/push-docker.yml/badge.svg)](https://github.com/RealPaiLab/netDx/actions/workflows/push-docker.yml)
+[![R CMD check bioc](https://github.com/RealPaiLab/netDx/actions/workflows/check-bioc.yml/badge.svg)](https://github.com/RealPaiLab/netDx/actions/workflows/check-bioc.yml)
+
+
 ### Main repo for netDx dev work as of Sep 2021.
 
 netDx is a general-purpose algorithm for building patient classifiers by using patient similarity networks as features. It excels at interpretability and handling missing data. It also allows custom grouping rules for features, notably grouping genes into pathways. It integrates with RCy3 for network visualization of predictive pathways.

vignettes/RawDataConversion.Rmd

@@ -1,48 +1,49 @@
 ---
-title: "Converting raw assay data/tables into format compatible with netDx algorithm"
+title: "Building a binary classifier from assay data using pathway level features"
 author: "Shraddha Pai & Indy Ng"
 package: netDx
 date: "`r Sys.Date()`"
 output: 
   BiocStyle::html_document:
     toc_float: true
 vignette: >
-    %\VignetteIndexEntry{02. Running netDx with data in table format}.
+    %\VignetteIndexEntry{01. Build binary predictor and view performance, top features and integrated Patient Similarity Network}.
     %\VignetteEngine{knitr::rmarkdown}
     %\VignetteEncoding{UTF-8}
 ---
 
 # Introduction
 
-In this example we will use the convertToMAE() wrapper function to transform raw experimental assay data/tables into the MultiAssayExperiment class, to illustrate how a typical netDx workflow might be initiated. 
+In this example we will build a predictor to classify breast tumours as being either of Luminal A subtype or otherwise. The process is identical for classifying three or more labels, and the example uses minimal data for quick runtime.
 
-For this we will use data from The Cancer Genome Atlas, converting it from the MultiAssayExperiment class into a list so that it is compatible with the convertToMAE() wrapper function.
+Although the netDx algorithm requires assay data to be provided in the form of a `MultiAssayExperiment` object, the package comes equipped with the `convertToMAE()` wrapper function to transform raw experimental assay data/tables into a `MultiAssayExperiment` object. We will use data from The Cancer Genome Atlas to build the predictor, converting it from a `MultiAssayExperiment` object into a list to illustrate how to utilize the `convertToMAE()` wrapper function.
 
 We will integrate two types of -omic data:
 
 * gene expression from Agilent mRNA microarrays and
 * miRNA sequencing 
 
-
 ```{r, include = FALSE}
 knitr::opts_chunk$set(crop=NULL)
 ```
 
 # Setup
-Load the `netDx` package.
+
+First, we load the `netDx` package.
 
 ```{r,eval=TRUE}
 suppressWarnings(suppressMessages(require(netDx)))
 ```
 
 # Data 
 
-For this example we pull data from the The Cancer Genome Atlas through the BioConductor `curatedTCGAData` package. The fetch command automatically brings in a `MultiAssayExperiment` object. 
+For this example we pull data from the The Cancer Genome Atlas through the BioConductor `curatedTCGAData` package.
+
 ```{r,eval=TRUE}
 suppressMessages(library(curatedTCGAData))
 ```
 
-We fetch the data two layers of data that we need:
+We fetch the two layers of data that we need:
 
 ```{r, eval=TRUE}
 brca <- suppressMessages(curatedTCGAData("BRCA",
@@ -51,6 +52,12 @@ brca <- suppressMessages(curatedTCGAData("BRCA",
                                          dry.run=FALSE, version="1.1.38"))
 ```
 
+The fetch command automatically brings in a `MultiAssayExperiment` object.
+
+```{r, eval = TRUE}
+summary(brca)
+```
+
 This next code block prepares the TCGA data. In practice you would do this once, and save the data before running netDx, but we run it here to see an end-to-end example. 
 
 ```{r, eval=TRUE}
@@ -65,9 +72,16 @@ pID <- colData(brca)$patientID
 colData(brca)$ID <- pID
 ```
 
-## Create feature design rules
+# Create feature design rules (patient similarity networks)
+
+To build the predictor using the netDx algorithm, we call the `buildPredictor()` function which takes patient data and variable groupings, and returns a set of patient similarity networks (PSN) as an output. The user can customize what datatypes are used, how they are grouped, and what defines patient similarity for a given datatype.
+
+## groupList object
+
+The `groupList` object tells the predictor how to group units when constructing a network. For examples, genes may be grouped into a network representing a pathway. This object is a list; the names match those of `dataList` while each value is itself a list and reflects a potential network.
+
+In this simple example we just create a single PSN for each datatype (mRNA gene expression, and miRNA expression data), containing all measures from that datatype, where measures can be individual genes, proteins, CpG bases (in DNA methylation data), clinical variables, etc., 
 
-We follow the workflow in the vignette "01: Build binary predictor and view performance, top features and integrated Patient Similarity Network" to generate the groupList parameter.
 
 ```{r, eval=TRUE}
 expr <- assays(brca)
@@ -83,77 +97,58 @@ for (k in 1:length(expr)) {	# loop over all layers
 }
 ```
 
+## Define patient similarity for each network
+
+`sims` is a list that specifies the choice of similarity metric to use for each grouping we're passing to the netDx algorithm. You can choose between several built-in similarity functions provided in the `netDx` package:
+
+* `normDiff` (normalized difference)
+* `avgNormDiff` (average normalized difference)
+* `sim.pearscale` (Pearson correlation followed by exponential scaling)
+* `sim.eucscale` (Euclidean distance followed by exponential scaling) or
+* `pearsonCorr` (Pearson correlation)
+
+You may also define custom similarity functions in this block of code and pass those to `makePSN_NamedMatrix()`, using the `customFunc` parameter.
+
+```{r,eval=TRUE}
+sims <- list(a="pearsonCorr", b="pearsonCorr")
+names(sims) <- names(groupList)
+```
+
 # Conversion of raw assay data into MultiAssayExperiment format
 
-Data pulled from The Cancer Genome Atlas through the BioConductor `curatedTCGAData` package automatically fetches data in the form of a `MultiAssayExperiment` object. However, most workflows that might utilize the netDx algorithm will have experimental assay data and patient metadata in the form of data frames/matrices/tables. 
+Data pulled from The Cancer Genome Atlas through the BioConductor `curatedTCGAData` package automatically fetches data in the form of a `MultiAssayExperiment` object. However, most workflows that might utilize the netDx algorithm will have experimental assay data and patient metadata in the form of data frames/matrices/tables.
 
-To facilitate ease-of-use, the netDx package has a built-in wrapper function convertToMAE() that takes in an input list of key-value pairs of experimental assay data and patient metadata, converting it into a MultiAssayExperiment object compatible with further analysis using the netDx algorithm. 
+To facilitate ease-of-use, the netDx package has a built-in wrapper function `convertToMAE()` that takes in an input list of key-value pairs of experimental assay data and patient metadata, converting it into a `MultiAssayExperiment` object compatible with further analysis using the netDx algorithm. However, all relevant data engineering/preparation should be done before using the `convertToMAE()` wrapper function.
 
-This next code block converts the TCGA data into a list format.
+This next code block converts the TCGA data into a list format to illustrate how one might use the `convertToMAE()` wrapper function.
 
 ```{r, eval=TRUE}
 brcaData <- dataList2List(brca, groupList)
 ```
 
-The keys of the input list of key-value pairs should be labelled according to the type of data corresponding to the value pairs (methylation, mRNA, proteomic, etc) and there must be a key-value pair that corresponds to patient IDs/metadata labelled pheno.
+The keys of the input list of key-value pairs should be labelled according to the type of data corresponding to the value pairs (methylation, mRNA, proteomic, etc) and there must be a key-value pair that corresponds to patient IDs/metadata labelled `pheno`.
 
 ```{r, eval=TRUE}
 brcaList <- brcaData$assays
 brcaList <- c(brcaList, list(brcaData$pheno))
 names(brcaList)[3] <- "pheno"
 ```
 
-We can now call the convertToMAE() wrapper function to convert the list containing experimental assay data and patient metadata into a MAE object.
+We can now call the `convertToMAE()` wrapper function to convert the list containing experimental assay data and patient metadata into a `MultiAssayExperiment` object.
 
 ```{r, eval=TRUE}
 brca <- convertToMAE(brcaList)
 ```
 
-The rest of the workflow follows the vignette "01: Build binary predictor and view performance, top features and integrated Patient Similarity Network".
-
-### Define patient similarity for each network
-The `makeNets` function tells the predictor how to create networks from provided input data.
-
-This function requires `dataList`,`groupList`, and `netDir` as input variables. The residual `...` parameter is to pass additional variables to `makePSN_NamedMatrix()`, notably `numCores` (number of parallel jobs).
+We can then proceed with the rest of the netDx workflow.
 
-netDx requires that this function have:
-
-* `dataList`,`groupList`, and `netDir` as input variables. The residual `...` parameter is to pass additional variables to `makePSN_NamedMatrix()`, notably number of cores for parallel processing (`numCores`). 
-
-
-```{r,  eval=TRUE}
-makeNets <- function(dataList, groupList, netDir,...) {
-	netList <- c() # initialize before is.null() check
-
-	layerNames <- c("BRCA_miRNASeqGene-20160128",
-		"BRCA_mRNAArray-20160128")
-
-	for (nm in layerNames){  			## for each layer
-		if (!is.null(groupList[[nm]])){ ## must check for null for each layer
-			netList_cur <- makePSN_NamedMatrix(
-				dataList[[nm]],
-				rownames(dataList[[nm]]),	## names of measures (e.g. genes, CpGs)
-				groupList[[nm]],			## how to group measures in that layer
-				netDir,						## leave this as-is, netDx will figure out where this is.
-				verbose=FALSE, 			
-				writeProfiles=TRUE,   		## use Pearson correlation-based similarity
-				...
-				)
-
-			netList <- c(netList,netList_cur)	## just leave this in
-		}
-	}
-	return(unlist(netList))	## just leave this in 
-}
-```
-
-## Build predictor
+# Build predictor
 
 Finally we call the function that runs the netDx predictor. We provide:
 
 * patient data  (`dataList`)
 * grouping rules (`groupList`)
-* function to create PSN from data, includes choice of similarity metric (`makeNetFunc`)
+* list specifying choice of similarity metric to use for each grouping (`sims`)
 * number of train/test splits over which to collect feature scores and average performance (`numSplits`), 
 * maximum score for features in one round of feature selection  (`featScoreMax`, set to 10)
 * threshold to call feature-selected networks for each train/test split (`featSelCutoff`); only features scoring this value or higher will be used to classify test patients,
@@ -168,41 +163,40 @@ Within each split, it:
 
 In practice a good starting point is `featScoreMax=10`, `featSelCutoff=9` and `numSplits=10L`, but these parameters depend on the sample sizes in the dataset and heterogeneity of the samples. 
 
-This step can take a few hours based on the current parameters, so we're commenting this out for the tutorial and will simply load the results.
+This step can take a few hours based on the current parameters, so we comment this out for the tutorial and will simply load the results.
 
 ```{r lab1-buildpredictor ,eval=TRUE}
 nco <- round(parallel::detectCores()*0.75) # use 75% available cores
 message(sprintf("Using %i of %i cores", nco, parallel::detectCores()))
+
 t0 <- Sys.time()
 set.seed(42) # make results reproducible
 outDir <- paste(tempdir(),randAlphanumString(),
 	"pred_output",sep=getFileSep())
 if (file.exists(outDir)) unlink(outDir,recursive=TRUE)
-model <- suppressMessages(buildPredictor(
-	dataList=brca,			## your data
-	groupList=groupList,	## grouping strategy
-	makeNetFunc=makeNets,	## function to build PSNs
-	outDir=outDir, 			## output directory
-	trainProp=0.8,			## pct of samples to use to train model in
-							## each split
-	numSplits=2L,			## number of train/test splits
- featSelCutoff=1L,		## threshold for calling something
-							## feature-selected
-	featScoreMax=2L,		## max score for feature selection
- numCores=nco,			## set higher for parallelizing
- debugMode=FALSE,
- keepAllData=FALSE,	## set to TRUE for debugging or low-level files used by the dictor
- logging="none"
+model <- suppressMessages(
+	buildPredictor(
+		dataList=brca,			## your data
+		groupList=groupList,	## grouping strategy
+		sims = sims,
+		outDir=outDir, 			## output directory
+		trainProp=0.8,			## pct of samples to use to train model in each split
+		numSplits=2L,			## number of train/test splits
+		featSelCutoff=1L,		## threshold for calling something feature-selected
+		featScoreMax=2L,		## max score for feature selection
+		numCores=nco,			## set higher for parallelizing
+		debugMode=FALSE,
+		keepAllData=FALSE,	## set to TRUE for debugging or low-level files used by the dictor
+		logging="none"
   ))
 t1 <- Sys.time()
 print(t1-t0)
 ```
 
-## Examine results
+# Examine results
 
 Now we get model output, including performance for various train/test splits and consistently high-scoring features. 
 
-
 In the function below, we define top-scoring features as those which score two out of two in at least half of the train/test splits:
 
 ```{r lab1-getresults,eval=TRUE}
@@ -239,21 +233,19 @@ And here are selected features, which are those scoring 2 out of 2 in at least h
 ```{r, eval=TRUE}
 results$selectedFeatures
 ```
-
 We finally get the integrated PSN and visualize it using a tSNE plot:
 
 ```{r, fig.width=8,fig.height=8, eval=TRUE}
 ## this call doesn't work in Rstudio; for now we've commented this out and saved the PSN file. 
-psn <- getPSN(brca,groupList,makeNetFunc=makeNets,selectedFeatures=results$selectedFeatures)
-
+psn <- getPSN(brca,groupList,sims = sims,selectedFeatures=results$selectedFeatures)
 require(Rtsne)
 tsne <- tSNEPlotter(
 	psn$patientSimNetwork_unpruned, 
 	colData(brca)
 	)
 ```
 
-## sessionInfo
+# sessionInfo
 ```{r}
 sessionInfo()
 ```