Merge pull request #15 from maize-genetics/jvm-enhancement

Add JVM metrics and plotting requests

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: rPHG2
 Title: R interface to PHGv2
-Version: 0.6.1
+Version: 0.7
 Authors@R:
     person(
         given = "Brandon",

NAMESPACE

@@ -11,6 +11,7 @@ export(PHGServerCon)
 export(brapiURL)
 export(brapiVersion)
 export(buildHaplotypeGraph)
+export(classPath)
 export(filterRefRanges)
 export(filterSamples)
 export(hVcfFiles)
@@ -19,14 +20,19 @@ export(httProtocol)
 export(initPhg)
 export(javaMemoryAddress)
 export(javaRefObj)
+export(javaVersion)
+export(jvmMemStats)
+export(jvmStats)
 export(metricsIds)
 export(metricsMetaData)
 export(metricsTable)
 export(numberOfChromosomes)
 export(numberOfHaplotypes)
+export(numberOfJars)
 export(numberOfRefRanges)
 export(numberOfSamples)
 export(phgType)
+export(phgVersion)
 export(plotDot)
 export(plotGvcf)
 export(plotHaploCounts)
@@ -40,6 +46,7 @@ export(readRefRanges)
 export(readSamples)
 export(serverInfo)
 exportClasses(HaplotypeGraph)
+exportClasses(JvmStats)
 exportClasses(PHGCon)
 exportClasses(PHGDataSet)
 exportClasses(PHGLocalCon)
@@ -51,21 +58,26 @@ exportMethods("metricsTable<-")
 exportMethods("seqnames<-")
 exportMethods(brapiURL)
 exportMethods(brapiVersion)
+exportMethods(classPath)
 exportMethods(filterRefRanges)
 exportMethods(filterSamples)
 exportMethods(hVcfFiles)
 exportMethods(host)
 exportMethods(httProtocol)
 exportMethods(javaMemoryAddress)
 exportMethods(javaRefObj)
+exportMethods(javaVersion)
+exportMethods(jvmMemStats)
 exportMethods(metricsIds)
 exportMethods(metricsMetaData)
 exportMethods(metricsTable)
 exportMethods(numberOfChromosomes)
 exportMethods(numberOfHaplotypes)
+exportMethods(numberOfJars)
 exportMethods(numberOfRefRanges)
 exportMethods(numberOfSamples)
 exportMethods(phgType)
+exportMethods(phgVersion)
 exportMethods(plotDot)
 exportMethods(plotGvcf)
 exportMethods(plotHaploCounts)

NEWS.md

@@ -2,14 +2,26 @@
 * Added new parameter to `plotHaploCounts()`:
   + `geom`
   + allows user to specify a given geometry (line, bar, or point)
+* Added new conditionals for to `buildHaplotypeGraph()`:
+  + Checks to see if the JVM is initialized. If not, it will cause an exception 
+    and direct user to run `initPhg()`
+* Added new class `JvmStats`:
+  + Returns internal Java and PHG versions and memory information for JVM
+    session
+  + Can be instantiated using the `jvmStats()` constructor function
+* Added new checks for `initPhg()`
+* Added new parameters to `plotGvcf()` function:
+  + `colorOverride`: Overrides bar color based on given user defined color
+  + `sampleOrder`: Overrides default bar ordering based on user defined
+    `character` vector
 
 
 ## rPHG2 0.6
 * Added new parameters to `plogtGvcf()`:
   + `mData` and `mVar`
-  + allows user to override default sample color option with categorical data
+  + Allows user to override default sample color option with categorical data
 * Added new generic, `numberOfHaplotypes()`:
-  + returns the number of unique haplotypes found within each reference range or
+  + Returns the number of unique haplotypes found within each reference range or
     the total value found within a `PHGDataSet` object
 * Added getters to `PHGDataSet` objects:
   + `numberOfChromosomes()`
@@ -26,8 +38,8 @@
 
 ## rPHG2 0.5
 * Added new visualization method, `plotGvcf()`:
-  + auto plotting various gVCF metrics
-  + granular metric support through formula subsetting
+  + Auto plotting various gVCF metrics
+  + Granular metric support through formula subsetting
 * Added new accessor and setting method, `seqnames()`
   + Returns all contig IDs found in a `PHGMetrics` object
   + Setter version (`seqnames()<-`) will update old IDs found within a
@@ -76,10 +88,12 @@
 * Added new function `readHapIdMetaData()`
   + Reads ALT header metadata for each haplotype ID from a connection object
 * Added new function `readHapIdPosMetaData()`
-  + Reads ALT header positional metadata for each haplotype ID from a connection object
+  + Reads ALT header positional metadata for each haplotype ID from a 
+    connection object
 * Added new function `readSamples()`
   + Reads sample IDs from a connection object
 * Added new function `readRefRanges()`
-  + Read reference range positional information as a `GRanges` object from a connection object
+  + Reads reference range positional information as a `GRanges` object from a 
+    connection object
 
 

R/class_all_generics.R

@@ -26,6 +26,20 @@ setGeneric("brapiURL", function(object, ...) standardGeneric("brapiURL"))
 setGeneric("brapiVersion", function(object, ...) standardGeneric("brapiVersion"))
 
 
+## ----
+#' @title Return JAR files from class path
+#'
+#' @description
+#' Returns a list of JAR files from an added class path for JVM use.
+#'
+#' @param object an \code{rPHG2 JvmStats} object
+#' @param ... Additional arguments, for use in specific methods
+#'
+#' @rdname brapiVersion
+#' @export
+setGeneric("classPath", function(object, ...) standardGeneric("classPath"))
+
+
 ## ----
 #' @title Filter data by reference range
 #'
@@ -110,6 +124,21 @@ setGeneric("hVcfFiles", function(object, ...) standardGeneric("hVcfFiles"))
 setGeneric("javaMemoryAddress", function(object, ...) standardGeneric("javaMemoryAddress"))
 
 
+## ----
+#' @title Return Java version
+#'
+#' @description
+#' This generic function retrieves the Java version associated with the
+#' specified object.
+#'
+#' @param object an \code{rPHG2 JvmStats} object
+#' @param ... Additional arguments passed to methods.
+#'
+#' @rdname javaVersion
+#' @export
+setGeneric("javaVersion", function(object, ...) standardGeneric("javaVersion"))
+
+
 ## ----
 #' @title Return \code{rJava} reference object
 #'
@@ -124,6 +153,20 @@ setGeneric("javaMemoryAddress", function(object, ...) standardGeneric("javaMemor
 setGeneric("javaRefObj", function(object, ...) standardGeneric("javaRefObj"))
 
 
+## ----
+#' @title Return JVM memory stats
+#'
+#' @description
+#' Returns the set memory stats for initialized JVM session
+#'
+#' @param object an \code{rPHG2 JvmStats} object
+#' @param ... Additional arguments, for use in specific methods
+#'
+#' @rdname jvmMemStats
+#' @export
+setGeneric("jvmMemStats", function(object, ...) standardGeneric("jvmMemStats"))
+
+
 ## ----
 #' @title Return metrics table IDs
 #'
@@ -203,6 +246,20 @@ setGeneric("numberOfChromosomes", function(object, ...) standardGeneric("numberO
 setGeneric("numberOfHaplotypes", function(object, ...) standardGeneric("numberOfHaplotypes"))
 
 
+## ----
+#' @title Return number of JAR files in class path
+#'
+#' @description
+#' Returns the number of JAR files for a given \code{JvmStats} object
+#'
+#' @param object an \code{rPHG2 JvmStats} object
+#' @param ... Additional arguments, for use in specific methods
+#'
+#' @rdname numberOfJars
+#' @export
+setGeneric("numberOfJars", function(object, ...) standardGeneric("numberOfJars"))
+
+
 ## ----
 #' @title Return number of reference ranges
 #'
@@ -246,6 +303,21 @@ setGeneric("numberOfSamples", function(object, ...) standardGeneric("numberOfSam
 setGeneric("phgType", function(object, ...) standardGeneric("phgType"))
 
 
+## ----
+#' @title Return PHG version
+#'
+#' @description
+#' This generic function retrieves the PHG version associated with the
+#' specified object.
+#'
+#' @param object an \code{rPHG2 JvmStats} object
+#' @param ... Additional arguments passed to methods.
+#'
+#' @rdname phgVersion
+#' @export
+setGeneric("phgVersion", function(object, ...) standardGeneric("phgVersion"))
+
+
 ## ----
 #' @title Generate dot plots
 #'

R/class_haplotype_graph.R

@@ -80,12 +80,16 @@ setValidity("HaplotypeGraph", function(object) {
 buildHaplotypeGraph <- function(
     phgLocalCon
 ) {
+    if (!isJvmInitialized()) {
+        rlang::abort("JVM is not initialized - please run 'initPhg()' with PHGv2 library path")
+    }
+
     if (!is(phgLocalCon, "PHGLocalCon")) {
-        stop("phgLocalCon object is not of type PHGLocalCon")
+        rlang::abort("phgLocalCon object is not of type PHGLocalCon")
     }
 
     if (!is.na(host(phgLocalCon))) {
-        stop("TileDB retrieval methods currently not implemented")
+        rlang::abort("TileDB retrieval methods currently not implemented")
     } else {
         jvmGraph <- hapGraphConstructor(hVcfFiles(phgLocalCon))
     }