R/RcppExports.R

In nVennR2: An Interface to 'nVenn2'

# Generated by using Rcpp::compileAttributes() -> do not edit by hand
# Generator token: 10BE3573-1514-4C36-9D1C-5A225CD40393

#' Estimates the time taken by minimization steps when preparing a diagram with
#' the exhaustive method at a given depth
#'
#' @param desc Description of sets, either as a file path, a list of lists, text or a 
#' previously created nVenn object (see [nVennDiagram()]).
#' @param maxlevel Depth of the exhaustive search. See the `maxlevel` parameter 
#' of [nVennDiagram()] for details. 
#' @param byCol If the input is a text, this parameter indicates whether 
#' each set is a column (1) or a row (2). Defaults to 0, which means that 
#' the package will try to guess which possibility makes more sense.
#' @returns float Estimated time for steps 3 and 4 in seconds. In case of 
#' error, the returned value is -1.
#'
#' @examples
#' estimateExhaustiveRunTime(exampledf, 4)
estimateExhaustiveRunTime <- function(desc, maxlevel = 0L, byCol = 0L) {
    .Call(`_nVennR2_estimateExhaustiveRunTime`, desc, maxlevel, byCol)
}

#' Creates nVenn plot
#'
#' @param desc Description of sets, either as a file path, a list of lists, text or a 
#' previously created nVenn object (see Details). 
#' @param plot If true (default), the resulting diagram is plotted. If false, 
#' only the object is returned.
#' @param outFile If it contains a valid file path and `plot` is also true, 
#' the svg code of the plot will 
#' be saved in that path.
#' @param systemShow If true, and `plot` is true, the function will attempt to 
#' open the resulting 
#' svg figure in the default editor. Defaults to false. 
#' @param verbose If true, shows messages as the nVenn plot is created.
#' @param maxlevel If higher than zero, the simulation uses an exhaustive
#' algorithm for the minimization steps. The number will represent the 
#' depth of the search. With a dept of one, every exchange of two regions
#' will be explored. With a depth of two, every exchange of four regions
#' will be explored. The computing resources necessary for this exploration
#' increase extremely fast with the depth, so users are advised to use
#' [estimateExhaustiveRunTime()] to determine whether it is feasible to use
#' this procedure. The process will be unresponsive during the simulation and 
#' no messages will be shown, 
#' regardless of `verbose`.
#' @param byCol If the input is a text, this parameter indicates whether 
#' each set is a column (1) or a row (2). Defaults to 0, which means that 
#' the package will try to guess which possibility makes more sense.
#' @return nVenn object. As a side effect, shows the nVenn plot. In case of
#' error, returns null object.
#' @details A list of lists contains inner lists with a name, which will be 
#' the corresponding set name. A dataframe can be used in the same way.
#' 
#' The input can also be a text containing a table, possibly with missing 
#' values. If a text is provided, the package will try to guess if each set
#' is encoded in columns or rows (use `byCol` to force) and which
#' character separates fields (usually tab, space or comma). If the text
#' describes a valid text file path, the contents of the file will be used.
#' @examples
#' myv <- nVennDiagram(list(Set1=c("a", "b", "c"), Set2=c("a", "c", "d")), verbose=FALSE)
nVennDiagram <- function(desc, plot = TRUE, outFile = "", systemShow = FALSE, verbose = TRUE, maxlevel = 0L, byCol = 0L) {
    .Call(`_nVennR2_nVennDiagram`, desc, plot, outFile, systemShow, verbose, maxlevel, byCol)
}

#' Creates nVenn plot
#'
#' @param svgFile File name of an SVG or HTML file created by nVenn. 
#' @param plot If true (default), the resulting diagram is plotted. If false, 
#' only the object is returned.
#' @param outFile If it contains a valid file path and `plot` is also true, 
#' the svg code of the plot will 
#' be saved in that path.
#' @param systemShow If true, and `plot` is true, the function will attempt to 
#' open the resulting 
#' svg figure in the default editor. Defaults to false. 
#' @returns nVenn object.
#' @details In principle, this function should work with any SVG or HTML file
#' created by nVenn, with either nVennR2, a web interface or nVennPy.
#' @examples
#' if (file.exists('example.svg')){
#'   readVennSVG('example.svg')
#' }
readVennSVG <- function(svgFile, plot = TRUE, outFile = "", systemShow = FALSE) {
    .Call(`_nVennR2_readVennSVG`, svgFile, plot, outFile, systemShow)
}

#' Gets the names of the sets
#'
#' @param nVennObj nVennR2 object generated with [nVennDiagram()].
#' @return List of set names.
#' @examples
#' myv <- nVennDiagram(list(Set1=c("a", "b", "c"), Set2=c("a", "c", "d")), verbose=FALSE)
#' getVennSetNames(myv)
getVennSetNames <- function(nVennObj) {
    .Call(`_nVennR2_getVennSetNames`, nVennObj)
}

#' Gets a list of the elements in a region of the diagram
#'
#' @param nVennObj nVennR2 object generated with [nVennDiagram()].
#' @param n Region, either as an integer or as a vector of set names. See Details
#' @return List of set names.
#' @details An integer expresses a region by considering its binary representation
#' in reverse. A 1 in a position means "belongs to" and a 0 or empty position
#' means "does not belong to". Thus, the binary representation of 19  (10011),
#' read from right to left, means "region that belongs to
#' sets 1, 2 and 5 and does not belong to any other set".
#' 
#' A vector of set names expresses a region by giving the sets the region
#' belongs to. It is understood that the region does not belong to any other
#' set.
#' @examples
#' myv <- nVennDiagram(list(Set1=c("a", "b", "c"), Set2=c("a", "c", "d")), verbose=FALSE)
#' #Both commands are equivalent:
#' getVennRegion(myv, 3)
#' getVennRegion(myv, c("Set1", "Set2"))
getVennRegion <- function(nVennObj, n) {
    .Call(`_nVennR2_getVennRegion`, nVennObj, n)
}

#' Lists the elements in every region of the diagram
#'
#' @param nVennObj nVennR2 object generated with [nVennDiagram()].
#' @param showEmpty If true, lists every region, even if empty. 
#' If false (default), only lists regions containing elements.
#' @return List of non-empty regions with the elements contained
#' @examples
#' myv <- nVennDiagram(list(Set1=c("a", "b", "c"), Set2=c("a", "c", "d")), verbose=FALSE)
#' mylist <- listVennRegions(myv)
#' mylist
listVennRegions <- function(nVennObj, showEmpty = FALSE) {
    .Call(`_nVennR2_listVennRegions`, nVennObj, showEmpty)
}

#' Get the svg code of an nVenn diagram
#'
#' @param nVennObj nVennR2 object generated with [nVennDiagram()].
#' @return String with svg code.
#' @details
#' The code returned by the funciton can be saved to a file and then 
#' edited with vectorial image 
#' software. This can be done directly with [nVennDiagram()] or
#' [plotVenn()] by using the `outFile` param.
#' @examples
#' myv <- nVennDiagram(list(Set1=c("a", "b", "c"), Set2=c("a", "c", "d")), verbose=FALSE)
#' getVennSvg(myv)
getVennSvg <- function(nVennObj) {
    .Call(`_nVennR2_getVennSvg`, nVennObj)
}

#' Rotate a diagram
#'
#' @param nVennObj nVennR2 object generated with [nVennDiagram()].
#' @param angle Angle of rotation in degrees. Positive values rotate
#' counterclockwise.
#' @param plot If true (default), prints the diagram after the rotation.
#' @return nVenn object. 
#' @examples
#' myv <- nVennDiagram(list(Set1=c("a", "b", "c"), Set2=c("a", "c", "d")), verbose=FALSE)
#' myv <- rotateVenn(myv, 45)
rotateVenn <- function(nVennObj, angle, plot = TRUE) {
    .Call(`_nVennR2_rotateVenn`, nVennObj, angle, plot)
}