@@ -95,6 +95,7 @@ Collate:

     'gmql_difference.R'

     'gmql_extend.R'

     'gmql_group.R'

+    'gmql_init.R'

     'gmql_join.R'

     'gmql_map.R'

     'gmql_materialize.R'

@@ -57,6 +57,7 @@ export(show_jobs_list)

 export(show_queries_list)

 export(show_samples_list)

 export(show_schema)

+export(stop_gmql)

 export(stop_job)

 export(trace_job)

 export(upload_dataset)

@@ -80,6 +81,7 @@ importClassesFrom(GenomicRanges,GRangesList)

 importClassesFrom(S4Vectors,DataTable)

 importFrom(BiocGenerics,setdiff)

 importFrom(BiocGenerics,union)

+importFrom(GenomicRanges,GRangesList)

 importFrom(GenomicRanges,makeGRangesFromDataFrame)

 importFrom(S4Vectors,aggregate)

 importFrom(S4Vectors,merge)

@@ -6,7 +6,7 @@

 #' @slot value value associated to GMQL dataset

 #' @name GMQLDataset-class

 #' @rdname GMQLDataset-class

-#' 

+#' @noRd

 #' @return instance of GMQL dataset

 #' 

 setClass("GMQLDataset",

@@ -22,7 +22,7 @@ setClass("GMQLDataset",

 #' 

 #' @param value value associated to GMQL dataset

 #' @rdname GMQLDataset-class

-#' 

+#' @noRd

 GMQLDataset <- function(value) {

     dataset <- new("GMQLDataset",value = value)

     return(dataset)

@@ -10,7 +10,7 @@ setGeneric("cover", function(data, ...) standardGeneric("cover"))

 #' Method map

 #' 

-#' Wrapper to GMQL map function

+#' Wrapper to GMQL MAP operator

 #' 

 #' @name map

 #' @rdname map

@@ -21,7 +21,7 @@ setGeneric("map", function(x, y, ...) standardGeneric("map"))

 #' Method take

 #' 

-#' Wrapper to take function

+#' Wrapper to TAKE operation

 #' 

 #' @name take

 #' @rdname take

@@ -32,7 +32,7 @@ setGeneric("take", function(data, ...) standardGeneric("take"))

 #' Method extend

 #' 

-#' Wrapper to GMQL extend function

+#' Wrapper to GMQL EXTEND operator 

 #' 

 #' @name extend

 #' @rdname extend

@@ -1,7 +1,7 @@

-#' Create GRangesList from GMQL Dataset

+#' Create GRangesList from GMQL dataset

 #'

-#' It create a GrangesList from GMQL samples in dataset

-#' It reads sample files in GTF or GDM/tabulated format

+#' It creates a GRangesList from GMQL samples in dataset. 

+#' It reads sample files in GTF or GDM/tab-delimited format.

 #'

 #' @importFrom rtracklayer import

 #' @importClassesFrom GenomicRanges GRangesList

@@ -9,16 +9,19 @@

 #' @importFrom utils read.delim

 #' @import xml2

 #'

-#' @param dataset_path string GMQL dataset folder path

-#' @param is_gtf logical value indicating if samples inside are in GTF format

-#' if TRUE and dataset does not contain gtf sample an error occures 

+#' @param dataset_path string with GMQL dataset folder path

+#' @param is_gtf logical value indicating if dataset samples are in GTF format;

+#' if TRUE and dataset does not contain GTF samples an error occurs 

 #' 

-#' @return GrangesList containing all GMQL samples in dataset

+#' @return GRangesList containing all GMQL samples in dataset

 #'

 #' @seealso \code{\link{export_gmql}}

 #'

 #' @examples

-#'

+#' 

+#' ## This statement defines the path to the subdirectory "example" of the 

+#' ## package "RGMQL" and import as GRangesList the GMQL dataset

+#' 

 #' test_path <- system.file("example", "DATASET", package = "RGMQL")

 #' grl = import_gmql(test_path, TRUE)

 #'

@@ -1,6 +1,6 @@

-#' Create GMQL dataset from GrangesList

+#' Create GMQL dataset from GRangesList

 #'

-#' It create GMQL dataset from GRangesList.

+#' It creates GMQL dataset from GRangesList.

 #' All samples are in GDM (tab-separated values) or GTF file format

 #'

 #' @import xml2

@@ -11,8 +11,9 @@

 #' @importFrom S4Vectors metadata

 #' @import GenomicRanges

 #'

-#' @param samples GrangesList

-#' @param dir_out folder path where create a folder and write the sample files

+#' @param samples GRangesList

+#' @param dir_out folder path where to create a folder and write the sample 

+#' files

 #' @param is_gtf logical value indicating if samples have to be exported

 #' with GTF or GDM format

 #'

@@ -21,28 +22,43 @@

 #' @seealso \code{\link{import_gmql}} 

 #'

 #' @details

-#' The GMQL dataset is made up by two differet file type

+#' The GMQL dataset is made up by two different file types:

 #'

 #' \itemize{

-#' \item{metadata files: contain metadata associated to corrisponding sample}

-#' \item{region files: contain many genomic regions }

-#' \item{region schema file: XML file contains region attributes 

+#' \item{metadata files: they contain metadata associated to corrisponding 

+#' sample.}

+#' \item{region files: they contain many genomic regions data.}

+#' \item{region schema file: XML file that contains region attribute name 

 #' (e.g. chr, start, end, pvalue)}

 #' }

-#' region sample files and metadata files are associated through file name:

+#' Region sample files and metadata files are associated through file name:

 #' for example S_0001.gdm for region file and S_0001.gdm.meta for 

 #' its metadata file

 #'

 #'

 #' @examples

 #' 

+#' ## load and attach add-on GenomicRanges package

 #' library(GenomicRanges)

+#' 

+#' ## These statemens create two GRanges with the region attribute: seqnames, 

+#' ## ranges (region coordinates) and strand, plus two column element:  

+#' ## score and GC

+#' 

 #' gr1 <- GRanges(seqnames = "chr2", ranges = IRanges(3, 6), strand = "+", 

 #' score = 5L, GC = 0.45)

 #' gr2 <- GRanges(seqnames = c("chr1", "chr1"),

 #' ranges = IRanges(c(7,13), width = 3), strand = c("+", "-"), 

 #' score = 3:4, GC = c(0.3, 0.5))

+#' 

+#' ## This statement creates a GRangesList using the previous GRanges 

+#' 

 #' grl = GRangesList(gr1, gr2)

+#' 

+#' ## This statement defines the path to the subdirectory "example" of the 

+#' ## package "RGMQL" and export the GRangesList as GMQL dataset using the 

+#' ## last name of 'dir_out' path as dataset name

+#' 

 #' test_out_path <- system.file("example", package = "RGMQL")

 #' export_gmql(grl, test_out_path,TRUE)

 #' 

@@ -72,22 +72,22 @@ take_value.META_AGGREGATES <- function(obj){

 #' function sum, performing all the type conversions needed  }

 #' \item{COUNT: It prepares input parameter to be passed to the library 

 #' function count, performing all the type conversions needed }

-#' \item{MIN:It prepares input parameter to be passed to the library 

+#' \item{MIN: It prepares input parameter to be passed to the library 

 #' function minimum, performing all the type conversions needed  }

 #' \item{MAX: It prepares input parameter to be passed to the library 

 #' function maximum, performing all the type conversions needed }

-#' \item{BAG: It prepares input parameter to be passed to the library 

-#' function bag, this function creates comma-separated strings of 

-#' attribute values, performing all the types conversions needed}

-#' \item{BAGD: It prepares input parameter to be passed to the library 

-#' function bag, this function creates comma-separated strings of distinct 

-#' attribute values, performing all the types conversions needed}

 #' \item{AVG: It prepares input parameter to be passed to the library 

 #' function mean, performing all the type conversions needed }

 #' \item{MEDIAN: It prepares input parameter to be passed to the library 

 #' function median, performing all the type conversions needed }

 #' \item{STD: It prepares input parameter to be passed to the library 

 #' function standard deviation, performing all the type conversions needed}

+#' \item{BAG: It prepares input parameter to be passed to the library 

+#' function bag; this function creates comma-separated strings of 

+#' attribute values, performing all the type conversions needed}

+#' \item{BAGD: It prepares input parameter to be passed to the library 

+#' function bag; this function creates comma-separated strings of distinct 

+#' attribute values, performing all the type conversions needed}

 #' \item{Q1: It prepares input parameter to be passed to the library 

 #' function fist quartile, performing all the type conversions needed}

 #' \item{Q2: It prepares input parameter to be passed to the library 

@@ -98,61 +98,66 @@ take_value.META_AGGREGATES <- function(obj){

 #' 

 #' @param value string identifying name of metadata or region attribute

 #'

-#' @return aggregate object

+#' @return Aggregate object

 #' 

 #' @examples

 #' 

-#' ## local with CustomParser

+#' ## This statement initializes and runs the GMQL server for local execution 

+#' ## and creation of results on disk. Then, with system.file() it defines 

+#' ## the path to the folder "DATASET" in the subdirectory "example"

+#' ## of the package "RGMQL" and opens such folder as a GMQL dataset 

+#' ## named "exp" using customParser

+#' 

 #' init_gmql()

 #' test_path <- system.file("example", "DATASET", package = "RGMQL")

 #' exp = read_dataset(test_path)

 #' 

-#' ## This statement copies all samples of exp into res dataset, and 

-#' ## then calculates new metadata attributes for each of them: 

+#' ## This statement copies all samples of exp dataset into res dataset, and 

+#' ## then calculates new metadata attribute for each of them: 

 #' ## sum_score is the sum of score of the sample regions.

 #' 

 #' res = extend(exp, sum_score = SUM("score"))

 #' 

-#' ## This statement copies all samples of exp into res dataset, 

-#' ## and then calculates new metadata attributes for each of them: 

-#' ## MinP is the minimum pvalue of the sample regions.

+#' ## This statement copies all samples of exp dataset into res dataset, 

+#' ## and then calculates new metadata attribute for each of them: 

+#' ## min_pvalue is the minimum pvalue of the sample regions.

 #' 

-#' res = extend(exp, minP = MIN("pvalue"))

+#' res = extend(exp, min_pvalue = MIN("pvalue"))

 #' 

-#' ## This statement copies all samples of exp into res dataset, 

-#' ## and then calculates new metadata attributes for each of them: 

+#' ## This statement copies all samples of exp dataset into res dataset, 

+#' ## and then calculates new metadata attribute for each of them: 

 #' ## max_score is the maximum score of the sample regions.

 #' 

 #' res = extend(exp, max_score = MAX("score"))

 #' 

 #' ## The following cover operation produces output regions where at least 2 

-#' ## and at most 3 regions ofexp overlap, having as resulting region 

-#' ## attributes the average signal of the overlapping regions; 

+#' ## and at most 3 regions of exp dataset overlap, having as resulting region 

+#' ## attribute the average signal of the overlapping regions; 

 #' ## the result has one sample for each input cell.

 #' 

 #' res = cover(exp, 2, 3, groupBy = list(DF("cell")), 

 #' avg_signal = AVG("signal") )

 #' 

-#' ## It copies all samples of DATA into OUT dataset, and then for each of 

-#' ## them it adds another metadata attribute, allScores, 

+#' ## This statement copies all samples of DATA dataset into OUT dataset, 

+#' ## and then for each of them it adds another metadata attribute, allScores, 

 #' ## which is the aggregation comma-separated list of all the values 

 #' ## that the region attribute score takes in the sample.

 #' 

 #' out = extend(exp, allScore = BAG("score"))

 #' 

-#' ## counts the regions in each sample and stores their number as value 

-#' ## of the new metadata RegionCount attribute of the sample.

+#' ## This statement counts the regions in each sample and stores their number 

+#' ## as value of the new metadata RegionCount attribute of the sample.

 #' 

 #' out = extend(exp, RegionCount = COUNT())

 #' 

-#' ## This statement copies all samples of exp into res dataset, 

-#' ## and then calculates new metadata attributes for each of them: 

+#' ## This statement copies all samples of exp dataset into res dataset, 

+#' ## and then calculates new metadata attribute for each of them: 

 #' ## std_score is the standard deviation score of the sample regions.

 #' 

 #' res = extend(exp, std_score = STD("score"))

 #' 

-#' ## This statement copies all samples of exp into res dataset, 

-#' ## and then calculates new metadata attributes for each of them: 

+#' ## This statement copies all samples of exp dataset into res dataset, 

+#' ## and then calculates new metadata attribute for each of them: 

 #' ## m_score is the median score of the sample regions.

 #' 

 #' res = extend(exp, m_score = MEDIAN("score"))

@@ -173,6 +178,25 @@ SUM <- function(value)

     return(list)

 }

+#' @name AGGREGATES-Object

+#' @aliases COUNT

+#' @rdname aggr-class

+#' @export

+#'

+COUNT <- function()

+{

+    list <- list()

+    ## Set the name for the class

+    class(list) <- c("COUNT","AGGREGATES","META_AGGREGATES")

+    return(list)

+}

+as.character.COUNT <- function(obj) {

+    class <- class(obj)[1]

+    c(class,"")

+}

+check.COUNT <- function(obj){}

+

+

 #' @name AGGREGATES-Object

 #' @aliases MIN

 #' @rdname aggr-class

@@ -220,66 +244,63 @@ AVG <- function(value)

 }

 #' @name AGGREGATES-Object

-#' @aliases BAG

+#' @aliases MEDIAN

 #' @rdname aggr-class

 #' @export

 #'

-BAG <- function(value)

+MEDIAN <- function(value)

 {

     check.META_AGGREGATES(value)

     list <- list(value = value)

     ## Set the name for the class

-    class(list) <- c("BAG","AGGREGATES","META_AGGREGATES")

+    class(list) <- c("MEDIAN","AGGREGATES","META_AGGREGATES")

     return(list)

 }

+

 #' @name AGGREGATES-Object

-#' @aliases COUNT

+#' @aliases STD

 #' @rdname aggr-class

 #' @export

 #'

-COUNT <- function()

+STD <- function(value)

 {

-    list <- list()

+    check.META_AGGREGATES(value)

+    

+    list <- list(value = value)

     ## Set the name for the class

-    class(list) <- c("COUNT","AGGREGATES","META_AGGREGATES")

+    class(list) <- c("STD","META_AGGREGATES")

     return(list)

 }

-as.character.COUNT <- function(obj) {

-    class <- class(obj)[1]

-    c(class,"")

-}

-check.COUNT <- function(obj){}

 #' @name AGGREGATES-Object

-#' @aliases STD

+#' @aliases BAG

 #' @rdname aggr-class

 #' @export

 #'

-STD <- function(value)

+BAG <- function(value)

 {

     check.META_AGGREGATES(value)

     list <- list(value = value)

     ## Set the name for the class

-    class(list) <- c("STD","META_AGGREGATES")

+    class(list) <- c("BAG","AGGREGATES","META_AGGREGATES")

     return(list)

 }

-

 #' @name AGGREGATES-Object

-#' @aliases MEDIAN

+#' @aliases BAGD

 #' @rdname aggr-class

 #' @export

 #'

-MEDIAN <- function(value)

+BAGD <- function(value)

 {

     check.META_AGGREGATES(value)

     list <- list(value = value)

     ## Set the name for the class

-    class(list) <- c("MEDIAN","AGGREGATES","META_AGGREGATES")

+    class(list) <- c("BAGD","AGGREGATES","META_AGGREGATES")

     return(list)

 }

@@ -327,18 +348,4 @@ Q3 <- function(value)

     return(list)

 }

-#' @name AGGREGATES-Object

-#' @aliases BAGD

-#' @rdname aggr-class

-#' @export

-#'

-BAGD <- function(value)

-{

-    check.META_AGGREGATES(value)

-    

-    list <- list(value = value)

-    ## Set the name for the class

-    class(list) <- c("BAGD","AGGREGATES","META_AGGREGATES")

-    return(list)

-}

@@ -31,71 +31,80 @@ check.DISTAL <- function(value)

 #' DISTAL object class constructor

 #'

 #' This class constructor is used to create instances of DISTAL object

-#' to be used in GMQL functions that use genometric predicate parameter

-#' requiring distal condition on value

+#' to be used in GMQL JOIN operations (RGMQL merge functions) that use 

+#' genometric predicate parameter requiring distal condition on value

 #' 

 #' \itemize{

 #' \item{DL: It denotes the less distance clause, 

-#' which selects all the regions of the experiment such that their distance 

-#' from the anchor region is less than 'value' bases.}

+#' which selects all the regions of a joined experiment dataset sample such 

+#' that their distance from the anchor region of a joined reference dataset 

+#' sample is less than 'value' bases.}

 #' \item{DLE: It denotes the less distance clause, 

-#' which selects all the regions of the experiment such that their distance 

-#' from the anchor region is less than, or equal to, 'value' bases.}

-#' \item{DG: it denotes the less distance clause, 

-#' which selects all the regions of the experiment such that their distance 

-#' from the anchor region is greater than 'value' bases. }

-#' \item{DGE: It denotes the less distance clause, which selects all the 

-#' regions of the experiment such that their distance from the anchor region 

-#' is greater than, or equal to, 'value' bases.}

+#' which selects all the regions of a joined experiment dataset sample such 

+#' that their distance from the anchor region of a joined reference dataset 

+#' sample is less than, or equal to, 'value' bases.}

+#' \item{DG: It denotes the less distance clause, 

+#' which selects all the regions of a joined experiment dataset sample such 

+#' that their distance from the anchor region of a joined reference dataset 

+#' sample is greater than 'value' bases. }

+#' \item{DGE: It denotes the less distance clause, 

+#' which selects all the regions of a joined experiment dataset sample such 

+#' that their distance from the anchor region of a joined reference dataset 

+#' sample is greater than, or equal to, 'value' bases.}

 #' \item{MD: It denotes the minimum distance clause, which selects 

-#' the 'value' regions of the experiment at minimial distance from the 

-#' anchor region.}

+#' the first 'value' regions of a joined experiment at minimial distance 

+#' from the anchor region of a joined reference dataset sample.}

 #' \item{UP: It denotes the upstream direction of the genome.

-#' They are interpreted as predicates that must hold on the regions 

-#' of the experiment.

-#' UP is true when region of experiment is in the upstream genome 

-#' of the anchor region.

+#' It makes predicates to be hold on the upstream of the regions of a joined 

+#' experiment dataset sample.

+#' UP is true when region of a joined experiment dataset sample is in the

+#' upstream genome of the anchor region of a joined reference dataset sample.

 #' When this clause is not present, distal conditions apply to both 

-#' the directions of the genome.}

-#' \item{DOWN: It denotes the downstream direction of the genome.

-#' They are interpreted as predicates that must hold on the regions of 

-#' the experiment.

-#' DOWN is true when region of experiment is in the downstream genome of 

-#' the anchor region.

-#' When this clause is not present, distal conditions apply to both the 

-#' directions of the genome. }

+#' directions of the genome.}

+#' \item{DOWN:  It denotes the downstream direction of the genome.

+#' It makes predicates to be hold on the downstream of the regions of a joined 

+#' experiment dataset sample.

+#' UP is true when region of a joined experiment dataset sample is in the

+#' downstream genome of the anchor region of a joined reference dataset sample.

+#' When this clause is not present, distal conditions apply to both 

+#' directions of the genome.}

 #' }

 #' 

 #' @param value string identifying distance between genomic regions 

-#' in base pairs, 

+#' in base pair, 

 #'

-#' @return distal object

+#' @return Distal object

 #' 

 #' @examples

+#' ## Thi statement initializes and runs the GMQL server for local execution 

+#' ## and creation of results on disk. Then, with system.file() it defines 

+#' ## the path to the folders "DATASET" and "DATASET_GDM" in the subdirectory 

+#' ## "example" of the package "RGMQL" and opens such folder as a GMQL 

+#' ## dataset named "TSS" and "HM" respectively using customParser

 #' 

 #' init_gmql()

-#' test_path <- system.file("example","DATASET",package = "RGMQL")

-#' test_path2 <- system.file("example","DATASET_GDM",package = "RGMQL")

+#' test_path <- system.file("example", "DATASET", package = "RGMQL")

+#' test_path2 <- system.file("example", "DATASET_GDM", package = "RGMQL")

 #' TSS = read_dataset(test_path)

 #' HM = read_dataset(test_path2)

 #' 

 #' ## Given a dataset HM and one called TSS with a sample including 

-#' # Transcription Start Site annotations, it searches for those regions of hm 

-#' # that are at a minimal distance from a transcription start site (TSS) 

-#' # and takes the first/closest one for each TSS, 

-#' # provided that such distance is lesser than 1200 bases and joined TSS 

-#' # and HM samples are obtained from the same provider (joinby clause).

+#' ## Transcription Start Site annotations, it searches for those regions of HM 

+#' ## that are at a minimal distance from a transcription start site (TSS) 

+#' ## and takes the first/closest one for each TSS, provided that such 

+#' ## distance is lesser than 1200 bases and joined TSS and HM samples are 

+#' ## obtained from the same provider (joinby clause).

 #' 

 #' join_data = merge(TSS, HM, 

 #' genometric_predicate = list(MD(1), DL(1200)), DF("provider"), 

 #' region_output = "RIGHT")

 #'

-#' #' # Given a dataset 'hm' and one called 'tss' with a sample including 

-#' # Transcription Start Site annotations, it searches for those regions of hm 

-#' # that are at a minimal distance from a transcription start site (TSS) 

-#' # and takes the first/closest one for each TSS, provided that such distance 

-#' # is greater than 12K bases and joined 'tss' and 'hm' samples are obtained 

-#' # from the same provider (joinby clause).

+#' ## Given a dataset 'HM' and one called 'TSS' with a sample including 

+#' ## Transcription Start Site annotations, it searches for those regions of HM 

+#' ## that are at a minimal distance from a transcription start site (TSS) 

+#' ## and takes the first/closest one for each TSS, provided that such distance 

+#' ## is greater than 12K bases and joined 'tss' and 'hm' samples are obtained 

+#' ## from the same provider (joinby clause).

 #' 

 #' join_data = merge(TSS, HM, 

 #' genometric_predicate = list(MD(1), DGE(12000), DOWN()), 

@@ -39,37 +39,41 @@ as.character.OPERATOR <- function(obj) {

 #' to be used in GMQL functions that require operator on value.

 #' 

 #' \itemize{

-#' \item{META: It prepared input parameter to be passed to library function 

-#' meta, performing all the type conversion needed}

-#' \item{SQRT: It prepared input parameter to be passed to library function 

-#' sqrt, performing all the type conversion needed}

-#' \item{NIL: It prepared input parameter to be passed to library function 

-#' null, performing all the type conversion needed}

+#' \item{META: It prepares input parameter to be passed to library function 

+#' meta, performing all the type conversions needed}

+#' \item{SQRT: It prepares input parameter to be passed to library function 

+#' sqrt, performing all the type conversions needed}

+#' \item{NIL: It prepares input parameter to be passed to library function 

+#' null, performing all the type conversions needed}

 #' }

 #' 

-#' @param value string identifying name of metadata attribute or region 

-#' attribute

-#' @param type string identifying the type of the attribute value

-#' must be: integer, double or string

+#' @param value string identifying name of metadata attribute

+#' @param type string identifying the type of the attribute value;

+#' it must be: INTEGER, DOUBLE or STRING

 #'

-#' @return operator object

+#' @return Operator object

 #' 

 #' 

 #' @examples

+#' ## Thi statement initializes and runs the GMQL server for local execution 

+#' ## and creation of results on disk. Then, with system.file() it defines 

+#' ## the path to the folders "DATASET" in the subdirectory "example" 

+#' ## of the package "RGMQL" and opens such folder as a GMQL dataset 

+#' ## named "exp"

 #' 

 #' init_gmql()

 #' test_path <- system.file("example", "DATASET", package = "RGMQL")

 #' exp = read_dataset(test_path)

 #' 

-#' ## allows to select, in all input sample, all those regions for which the 

-#' ## region attribute score has a value which is greater than the metadata 

-#' ## attribute value "avg_score" in their sample.

+#' ## This statement allows to select, in all input sample, all those regions 

+#' ## for which the region attribute score has a value which is greater 

+#' ## than the metadata attribute value "avg_score" in their sample.

 #' 

 #' data = filter(exp, r_predicate = score > META("avg_score"))

 #' 

-#' ## It define a new numeric region attribute with "null" value. 

+#' ## This statement defines a new numeric region attribute with "null" value. 

 #' ## The syntax for creating a new attribute with null value is 

-#' ## attribute_name = NULL(TYPE), where type may be INTEGER or DOUBLE.

+#' ## attribute_name = NULL(TYPE), where type may be INTEGER, DOUBLE or STRING.

 #' 

 #' out = select(exp, regions_update = list(signal = NIL("INTEGER"), 

 #' pvalue = NIL("DOUBLE")))

@@ -82,9 +86,6 @@ as.character.OPERATOR <- function(obj) {

 #' ## with value correspondent to the mathematical squared root 

 #' ## of the pre-existing metadata attribute concentration.

 #' 

-#' init_gmql()

-#' test_path <- system.file("example", "DATASET", package = "RGMQL")

-#' exp = read_dataset(test_path)

 #' out = select(exp, metadata_update = list(concSq = SQRT("concentration")))

 #' 

 #' @name OPERATOR-Object

@@ -92,7 +93,7 @@ as.character.OPERATOR <- function(obj) {

 #' @rdname operator-class

 #' @export

 #'

-META <- function(value,type=NULL)

+META <- function(value, type = NULL)

 {

     check.OPERATOR(value)

     if(!is.null(type))

@@ -128,11 +129,11 @@ check.META <- function(type)

 #' @rdname operator-class

 #' @export

 #'

-NIL <- function(value)

+NIL <- function(type)

 {

-    check.NIL(value)

+    check.NIL(type)

-    list <- list(value = value)

+    list <- list(value = type)

     ## Set the name for the class

     class(list) <- c("NIL","OPERATOR")

     return(list)

@@ -5,7 +5,7 @@

 #' Condition evaluation functions

 #'

 #' These functions are used to support joinBy and/or groupBy function parameter.

-#' It create a list of one element: matrix containing the two coloumn:

+#' They create a 2-D array made up by two coloumn:

 #' type of condition evaluation and the metadata attribute name

 #'

 #' \itemize{

@@ -13,16 +13,16 @@

 #' FULL evaluation: two attributes match if they both end with value and,

 #' if they have further prefixes, the two prefix sequences are identical}

 #' \item{EX: It defines a EXACT evaluation of the input values.

-#' EXACT evaluation: only attributes exactly as value will match; 

+#' EXACT evaluation: only attributes exactly as value match; 

 #' no further prefixes are allowed. }

 #' \item{DF: It defines a DEFAULT evaluation of the input values.

 #' DEFAULT evaluation: the two attributes match if both end with value.}

 #' }

 #'

-#' @param ... series of string identifying name of metadata attribute 

+#' @param ... series of string identifying a name of metadata attribute 

 #' to be evaluated

 #' 

-#' @return list of 2-D array containing method of evaluation and metadata

+#' @return 2-D array containing method of evaluation and metadata

 #' 

 #' @examples

 #' 

@@ -20,9 +20,9 @@

 #' this condition is logically "ANDed" with prefix filtering (see below)

 #' if NULL no filtering action occures

 #' (i.e every sample is taken for region filtering)

-#' @param metadata_prefix vector of strings that will filter metadata

-#' containing rispectively every element of this vector.

-#' number of element in both vector must match

+#' @param metadata_prefix vector of strings that will support the metadata

+#' filtering. If defined every defined 'metadata' are concatenated with the 

+#' corresponding prefix.

 #' @param regions vector of strings that extracts only region attribute 

 #' specified; if NULL no regions attribute is taken and the output is only 

 #' GRanges made up by the region coordinate attributes 

@@ -33,18 +33,26 @@

 #' selected regions

 #'

 #' @details

-#' This function works only with datatset or GRangesList that has the same

-#' information about regions attribute (but of course different value)

+#' This function works only with datatset or GRangesList which samples or 

+#' Granges have the same regions coordinates (chr, ranges, strand)

+#' 

 #' In case of Grangeslist data input the function will search for metadata

 #' into metadata() function associated to Grangeslist.

 #'

-#' @return Granges with selected regions (if any) in elementMetadata

+#' @return GRanges with selected regions

 #'

 #' @examples

-#'

+#' 

+#' ## This statement defines the path to the folders "DATASET" in the 

+#' ## subdirectory "example" of the package "RGMQL" and filter such folder 

+#' ## dataset including at output only "pvalue" and "peak" regions

+#' 

 #' test_path <- system.file("example", "DATASET", package = "RGMQL")

-#' filter_and_extract(test_path,regions = c("pvalue", "peak"))

-#'

+#' filter_and_extract(test_path, regions = c("pvalue", "peak"))

+#' 

+#' ## This statement import a GMQL dataset as GRangesList and filter it 

+#' ## including at output only "pvalue" and "peak" regions

+#' 

 #' grl = import_gmql(test_path, TRUE)

 #' filter_and_extract(grl, regions = c("pvalue", "peak"))

 #'

@@ -1,13 +1,13 @@

 #' Method setdiff

 #' 

-#' @description Wrapper to GMQL difference function

+#' @description Wrapper to GMQL DIFFERENCE operator

 #' 

 #' @description It produces one sample in the result for each sample of the 

 #' left operand, by keeping the same metadata of the left input sample 

 #' and only those regions (with their schema and values) of the left input 

 #' sample which do not intersect with any region in the right operand sample.

 #' The optional \emph{joinby} clause is used to extract a subset of couples

-#' from the cartesian product of two dataset \emph{x} and \emph{y} 

+#' from the Cartesian product of two dataset \emph{x} and \emph{y} 

 #' on which to apply the DIFFERENCE operator:

 #' only those samples that have the same value for each attribute

 #' are considered when performing the difference.

@@ -17,19 +17,16 @@

 #' 

 #' @param x GMQLDataset class object

 #' @param y GMQLDataset class object

-#' @param ... Additional arguments for use in specific methods.

-#' 

-#' This method accept a function to define condition evaluation on metadata.

+#' @param joinBy list of evalation functions to define evaluation on metadata:

 #' \itemize{

-#' \item{\code{\link{FN}}: Fullname evaluation, two attributes match 

-#' if they both end with value and, if they have a further prefixes,

+#' \item{\code{\link{FN}}(value): Fullname evaluation, two attributes match 

+#' if they both end with \emph{value} and, if they have further prefixes,

 #' the two prefix sequence are identical}

-#' \item{\code{\link{EX}}: Exact evaluation, only attributes exactly 

-#' as value will match; no further prefixes are allowed. }

-#' \item{\code{\link{DF}}: Default evaluation, the two attributes match 

-#' if both end with value.}

+#' \item{\code{\link{EX}}(value): Exact evaluation, only attributes exactly 

+#' as \emph{value} match; no further prefixes are allowed. }

+#' \item{\code{\link{DF}}(value): Default evaluation, the two attributes match 

+#' if both end with \emph{value}.}

 #' }

-#' 

 #' @param is_exact single logical value: TRUE means that the region difference 

 #' is executed only on regions in left_input_data with exactly the same 

 #' coordinates of at least one region present in right_input_data; 

@@ -42,47 +39,48 @@

 #' 

 #'

 #' @examples

-#'

-#' ## This GMQL statement returns all the regions in the first dataset 

-#' ## that do not overlap any region in the second dataset.

+#' ## This statement initializes and runs the GMQL server for local execution 

+#' ## and creation of results on disk. Then, with system.file() it defines 

+#' ## the path to the folders "DATASET" and "DATASET_GDM" in the subdirectory 

+#' ## "example" of the package "RGMQL" and opens such folder as a GMQL 

+#' ## dataset named "data1" and "data2" respectively using customParser

 #' 

 #' init_gmql()

 #' test_path <- system.file("example", "DATASET", package = "RGMQL")

 #' test_path2 <- system.file("example", "DATASET_GDM", package = "RGMQL")

-#' r_left = read_dataset(test_path)

-#' r_right = read_dataset(test_path2)

-#' out = setdiff(r_left, r_right)

+#' data1 = read_dataset(test_path)

+#' data2 = read_dataset(test_path2)

+#' 

+#' ## This GMQL statement returns all the regions in the first dataset 

+#' ## that do not overlap any region in the second dataset.

+#' 

+#' out = setdiff(data1, data2)

 #' 

-#' \dontrun{

 #' ## This GMQL statement extracts for every pair of samples s1 in EXP1 

 #' ## and s2 in EXP2 having the same value of the metadata 

 #' ## attribute 'antibody_target' the regions that appear in s1 but 

 #' ## do not overlap any region in s2; 

 #' ## metadata of the result are the same as the metadata of s1.

 #' 

-#' init_gmql()

-#' test_path <- system.file("example", "DATASET", package = "RGMQL")

-#' test_path2 <- system.file("example", "DATASET_GDM", package = "RGMQL")

-#' exp1 = read_dataset(test_path)

-#' exp2 = read_dataset(test_path2)

-#' out = setdiff(exp1, exp2, DF("antibody_target"))

+#' out_t = setdiff(data1, data2, DF("antibody_target"))

 #'

-#' }

 #' @name setdiff

 #' @aliases setdiff,GMQLDataset,GMQLDataset-method

 #' @aliases setdiff-method

 #' @export

 setMethod("setdiff", c("GMQLDataset","GMQLDataset"),

-            function(x, y, ..., is_exact = FALSE)

+            function(x, y, joinBy = NULL, is_exact = FALSE)

             {

                 ptr_data_x = x@value

                 ptr_data_y = y@value

-                joinBy = list(...)

                 gmql_difference(ptr_data_x, ptr_data_y, is_exact, joinBy)

             })

 gmql_difference <- function(left_data, right_data, is_exact, joinBy)

 {

+    if(!is.list(joinBy))

+        stop("joinBy: must be a list")

+    

     if(!is.null(joinBy) && !length(joinBy) == 0)

     {

         cond <- .join_condition(joinBy)

@@ -5,24 +5,20 @@

 #' and adds them to the existing metadata attributes of the sample.

 #' Aggregate functions are applied sample by sample.

 #'

-#' @importFrom rJava .jnull

-#' @importFrom rJava J

-#' @importFrom rJava .jarray

+#' @importFrom rJava J .jnull .jarray

 #'

 #' @param .data GMQLDataset class object 

-#' @param ... Additional arguments for use in specific methods.

-#' It accept a series of aggregate function on region attribute.

-#' All the element in the form \emph{key} = \emph{aggregate}.

-#' The \emph{aggregate} is an object of class AGGREGATES

-#' The aggregate functions available are: \code{\link{SUM}}, 

+#' @param ... a series of expressions separated by comma in the form 

+#' \emph{key} = \emph{aggregate}. The \emph{aggregate} is an object of 

+#' class AGGREGATES. The aggregate functions available are: \code{\link{SUM}}, 

 #' \code{\link{COUNT}}, \code{\link{MIN}}, \code{\link{MAX}}, 

 #' \code{\link{AVG}}, \code{\link{MEDIAN}}, \code{\link{STD}}, 

 #' \code{\link{BAG}}, \code{\link{BAGD}}, \code{\link{Q1}}, 

 #' \code{\link{Q2}}, \code{\link{Q3}}.

-#' Every aggregate accepts a string value, execet for COUNT, which does not 

+#' Every aggregate accepts a string value, except for COUNT, which does not 

 #' have any value.

 #' Argument of 'aggregate function' must exist in schema, i.e. among region 

-#' attributes. Two style are allowed:

+#' attributes. Two styles are allowed:

 #' \itemize{

 #' \item list of key-value pairs: e.g. sum = SUM("pvalue")

 #' \item list of values: e.g. SUM("pvalue")

@@ -33,28 +29,29 @@

 #' for the subsequent GMQLDataset method

 #' 

 #' @examples

-#'

-#' ## it counts the regions in each sample and stores their number as value 

-#' ## of the new metadata RegionCount attribute of the sample.