From 8f5c97a9229970892dfec96f3729cb6287941296 Mon Sep 17 00:00:00 2001 From: Svetlana Date: Fri, 17 Jan 2020 17:05:47 +0100 Subject: [PATCH] presubmission changes --- DESCRIPTION | 2 +- NEWS.md | 9 +- R/lc.R | 12 +- api.md | 1045 +++++++++++++++++++++++++----------------- cran-comments.md | 19 + generateMd.R | 2 +- man/lc_bars.Rd | 2 +- man/lc_line.Rd | 5 +- man/lc_scatter.Rd | 2 +- man/setProperties.Rd | 3 +- 10 files changed, 678 insertions(+), 423 deletions(-) diff --git a/DESCRIPTION b/DESCRIPTION index d5f93e2..8ea87c8 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -2,7 +2,7 @@ Package: rlc Type: Package Title: Create Interactive Linked Charts with Minimal Code Version: 0.2.0 -Date: 2019-10-11 +Date: 2020-01-17 Authors@R: c( person("Svetlana", "Ovchinnikova", role = c("aut", "cre"), email = "s.ovchinnikova@zmbh.uni-heidelberg.de"), person("Simon", "Anders", role = c("aut"), email = "sanders@fs.tum.de") diff --git a/NEWS.md b/NEWS.md index b94dae6..f457768 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,4 +1,11 @@ -# rlc 0.1.1 +# rlc 0.2.0 + +* It is possible now to create server apps that can be accessed by multiple users simultaneously. To this end, one should use arguments +`sessionVars`, `beforeLoad` and `afterLoad` of the `openPage` functions. `sessionVars` defines local variables with their default values +for each client, `beforeLoad` and `afterLoad` are callback functions that are called once for each new web page. Other than that, there are +no differences between creating an `rlc` app locally or on a server. + +* `rlc` has been restructured so that the entire app is now stored inside a single `R6` object of class `LCApp` (see man pages for more details). * Property `axesTitlePos` added for all the charts that have axes. This property allows to place axis labels above or below the x-axis (to the left or to the right from the y-axis) and at the end, in the middle or next to the start of the axis. diff --git a/R/lc.R b/R/lc.R index 7180766..c626d13 100644 --- a/R/lc.R +++ b/R/lc.R @@ -1277,7 +1277,8 @@ removeLayer <- function(chartId, layerId) { #' setProperties(dat(symbolValue = iris$Species, y = iris$Petal.Length), chartId = "irisScatter") #' updateCharts("irisScatter") #' -#' lc_line(dat(x = iris$Sepal.Length, y = iris$Petal.Length), chartId = "irisScatter", layerId = "line") +#' lc_line(dat(x = iris$Sepal.Length, y = iris$Petal.Length), chartId = "irisScatter", +#' layerId = "line") #' setProperties(dat(colour = "red"), chartId = "irisScatter", layerId = "line") #' updateCharts("irisScatter")} #' @@ -1690,7 +1691,7 @@ closePage <- function() { #' \item \code{axisTitleX, axisTitleY} - axes titles. #' \item \code{axisTitlePosX, axisTitlePosY} - position of axes titles. For each axis one can specify title position #' across or along the corresponding axis. Possible options are \code{"up"} (for title inside the plotting area) -#' or \code{"down"} (outside the plottting area, under the axis), and +#' or \code{"down"} (outside the plotting area, under the axis), and #' \code{"start"}, \code{"middle"}, \code{"end"}. This property must be a string with one or two of the abovementioned options #' (e.g. \code{"middle down"}, \code{"start"}, etc.). #' \item \code{ticksRotateX, ticksRotateY} - angle by which to rotate ticks (in degrees). Must be between @@ -1837,7 +1838,7 @@ lc_beeswarm <- function(data = list(), place = NULL, ..., chartId = NULL, layerI #' \item \code{axisTitleX, axisTitleY} - axes titles. #' \item \code{axisTitlePosX, axisTitlePosY} - position of axes titles. For each axis one can specify title position #' across or along the corresponding axis. Possible options are \code{"up"} (for title inside the plotting area) -#' or \code{"down"} (outside the plottting area, under the axis), and +#' or \code{"down"} (outside the plotting area, under the axis), and #' \code{"start"}, \code{"middle"}, \code{"end"}. This property must be a string with one or two of the abovementioned options #' (e.g. \code{"middle down"}, \code{"start"}, etc.). #' \item \code{ticksRotateX, ticksRotateY} - angle by which to rotate ticks (in degrees). Must be between @@ -1897,7 +1898,8 @@ lc_beeswarm <- function(data = list(), place = NULL, ..., chartId = NULL, layerI #' x = x, #' colour = "#555555"), chartId = "ribbonTest") #' lc_scatter(dat(x = x, y = y), size = 2, chartId = "ribbonTest", addLayer = TRUE) -#' lc_abLine(dat(a = fit$coefficients[2], b = fit$coefficients[1]), chartId = "ribbonTest", addLayer = TRUE) +#' lc_abLine(dat(a = fit$coefficients[2], b = fit$coefficients[1]), +#' chartId = "ribbonTest", addLayer = TRUE) #' #' lc_hLine(dat(h = seq(1, 9, 1), domainX = c(0, 10), domainY = c(0, 10)), chartId = "grid") #' lc_vLine(dat(v = seq(1, 9, 1)), chartId = "grid", addLayer = TRUE)} @@ -1993,7 +1995,7 @@ lc_ribbon <- function(data = list(), place = NULL, ..., chartId = NULL, layerId #' \item \code{axisTitleX, axisTitleY} - axes titles. #' \item \code{axisTitlePosX, axisTitlePosY} - position of axes titles. For each axis one can specify title position #' across or along the corresponding axis. Possible options are \code{"up"} (for title inside the plotting area) -#' or \code{"down"} (outside the plottting area, under the axis), and +#' or \code{"down"} (outside the plotting area, under the axis), and #' \code{"start"}, \code{"middle"}, \code{"end"}. This property must be a string with one or two of the abovementioned options #' (e.g. \code{"middle down"}, \code{"start"}, etc.). #' \item \code{ticksRotateX, ticksRotateY} - angle by which to rotate ticks (in degrees). Must be between diff --git a/api.md b/api.md index b163a50..2b6c082 100644 --- a/api.md +++ b/api.md @@ -4,21 +4,30 @@ title: 'R/LinkedCharts API' hideTOC: 'true' api: true --- -# Add a default layout to the opened web page +# `chartEvent` -* `addDefaultLayout` +Trigger an event + + +## Alias + +`chartEvent` ## Description -`addDefaultLayout` adds a layout that can be later used to arrange charts on the page (by - default each new chart is added to the bottom of the page). +This function is called whenever any interactive element of a chart is activated by clicking, marking, + hovering, etc. In turn, + it calls a corresponding callback function, if any has been specified. This function + is meant to be used internally. However, an experienced user can still use it to simulate mouse events, + even those triggered by non-existing elements. This function is a wrapper around method + `chartEvent` of class [`LCApp`](#lcapp) . ## Usage ```r -addDefaultLayout(layoutName) +chartEvent(d, chartId, layerId = "main", event, sessionId = .id, app = .app) ``` @@ -26,34 +35,35 @@ addDefaultLayout(layoutName) Argument |Description ------------- |---------------- -`layout` | Type of the layout. See 'Details' for more information. - - -## Details - -Currently the only supported type - of a default layout is table with arbitrary number of rows and columns. - To use it set the layout argument to `tableMxN` , where `N` is the - number of rows and `M` is the number of columns. Each cell will get an ID that consists of - a letter (inticating the row) and a number (indicating the column) (e.g. `B3` is an ID of - the second row and third column). +`d` | Value that is used to identify interactive element or its state. A single numeric index for a point or a line, vector or row and column indices of a cell for a heatmap, value for an input block (please, check [`lc_input`](#lcinput) for more details about input blocks and their values). Should be `NULL` for `mouseout` or `marked` events. N.B. This function is called from the web page and therefore all element indices start from zero as it is happens in JavaScript. +`chartId` | ID of the chart. +`layerId` | ID of the layer. You can print IDs of all charts and their layers with [`listCharts`](#listcharts) . +`event` | Type of event. Must be one of `"click"` , `"mouseover"` , `"mouseout"` , `"marked"` , `"labelClickRow"` , `"labelClickCol"` . +`sessionId` | ID of the session (opened client page) that triggered the event. The default value uses a local session variable. This must be a single session ID. You can get a list of IDs of all currently active with the method `getSessionIds` inherited from class [`App`](#app) by [`LCApp`](#lcapp) . Possible errors in evaluation of this argument are ignored. +`app` | Object of class [`LCApp`](#lcapp) for which the event was triggered. Note that this argument is here for internal use and its default value is a variable, stored in each session locally. If you are not using wrapper functions, it is preferred to call method `chartEvent` of an object of class [`LCApp`](#lcapp) . ## Examples ```r -addDefaultLayout("table3x2") +list("x <- rnorm(50)\n", "lc_scatter(x = x, y = 2*x + rnorm(50, 0.1), on_click = function(d) print(d))\n", "chartEvent(51, \"Chart1\", \"Layer1\", \"click\")") ``` -# Close page +# `closePage` + +Stop server + -* `closePage` +## Alias + +`closePage` ## Description -Close an opened web page and clear the list of charts. +Stops the server and closes all currently opened pages (if any). This function is a + wrapper of `stopServer` method inherited by the [`LCApp`](#lcapp) class from the [`App`](#app) class. ## Usage @@ -66,22 +76,26 @@ closePage() ## Examples ```r -openPage(useViewer = F) -closePage() +list("openPage(useViewer = FALSE)\n", "closePage()") ``` -# Link data to the chart +# `dat` + +Link data to the chart -* `dat` + +## Alias + +`dat` ## Description `dat` allows to link variables from the current environment to chart's properties. - On every [`updateCharts`](#updatecharts) call all the data, provided via the `dat` function, + On every [`updateCharts`](#updatecharts) call all the data provided via the `dat` function will be automatically reevaluated and the chart will be changed accordingly. One can also - put properties outside of the `dat` function, if they are going to be constant. + put properties outside of the `dat` function to prevent their reevaluation. ## Usage @@ -95,35 +109,38 @@ dat(...) Argument |Description ------------- |---------------- -`...` | List of name values pair to define the properties. +`...` | List of name-value pairs to define the properties. ## Examples ```r -lc_scatter(dat(x = rnorm(30)), y = rnorm(30)) -#note that the Y values remain the same after each updateCharts call -updateCharts() +list("lc_scatter(dat(x = rnorm(30)), y = rnorm(30))\n", "#note that the Y values remain the same after each updateCharts call\n", "updateCharts()") ``` -# Get currently marked elements +# `getMarked` + +Get currently marked elements -* `getMarked` + +## Alias + +`getMarked` ## Description `getMarked` returns indices of the chart's elements that are currently - marked. To mark elements select them with you mouse while pressing the Shift key. - Double click on the chart while pressing the Shift key will unmark all the - elements. + marked. To mark elements select them with your mouse while holding the Shift key. + Double click on the chart with the Shift key pressed will deselect all the + elements. This function is a wrapper of method `getMarked` of class [`LCApp`](#lcapp) . ## Usage ```r -getMarked(chartId = NULL, layerId = NULL) +getMarked(chartId = NULL, layerId = NULL, sessionId = NULL) ``` @@ -131,45 +148,94 @@ getMarked(chartId = NULL, layerId = NULL) Argument |Description ------------- |---------------- -`chartId` | An ID of the chart. -`layerId` | An ID of the layer. This argument is required, if the chart has more than one layer. +`chartId` | An ID of the chart. This argument is optional, if there is only one chart. +`layerId` | An ID of the layer. This argument is optional, if there is only one chart. than one layer. +`sessionId` | An ID of the session from which to get the marked elements. Can be `NULL` if there is only one active session. Otherwise must be a valid session ID. Check [`Session`](#session) for more information on client sessions. If a call to this function was triggered from an opened web page, ID of the corresponding session will be used automatically. ## Value a vector of indices or, in case of heatmaps, an n x 2 matrix were first and - second columns contain, respectively, row and colunm indices of the marked cells. + second columns contain row and column indices of the marked cells, respectively. ## Examples ```r -data(iris) +list("data(iris)\n", "\n", "lc_scatter(dat(x = iris$Sepal.Length, y = iris$Petal.Length))\n", "\n", "#now mark some points by selecting them with your mouse with Shift pressed\n", "\n", "getMarked(\"Chart1\")") +``` + + +# `getPage` + +Get the currently running app + + +## Alias + +`getPage` -lc_scatter(dat(x = iris$Sepal.Length, y = iris$Petal.Length)) -#now mark some points by selecting them with your mouse with Shift pressed +## Description + +`rlc` offers two ways to control an interactive app. One is by using methods of class + [`LCApp`](#lcapp) . This allows one to have any number of apps within one + R session, but requires some understanding of object oriented programming. Another way is to use + provided wrapper functions that are exported by the package. These functions internally work with + the [`LCApp`](#lcapp) object, which is stored in the package namespace upon initialization with + [`openPage`](#openpage) function. `getPage` returns this object if any. + -getMarked("Chart1") +## Usage + +```r +getPage() ``` -# Create a barplot +## Details + +Note that `rlc` package is based on `jrc` library. Both packages are organized in similar manner. + Both have a central class that represents the entire app and can be fully managed with their methods ( [`LCApp`](#lcapp) + and [`App`](#app) , respectively). And both also provide a set of wrapper functions, that can be used instead of + the methods. However, wrapper functions of the `jrc` package can't be use for `rlc` apps, while all the + methods of class [`App`](#app) are inherited by [`LCApp`](#lcapp) . Therefore, if you want to get more low level + control over your app, such as managing client sessions, local variables and memory usage, you should methods of + [`App`](#app) class. + + +## Value + +Object of class [`LCApp`](#lcapp) or `NULL` if there is no active app. + + +# `lc_bars` + +Create a barplot -* `lc_bars` + +## Alias + +`lc_bars` ## Description -`lc_bars` creates a new barplot and adds it on the page +`lc_bars` creates a new barplot and adds it to the app and to the all currently opened pages as a new chart or as a new layer of an existing chart. ## Usage ```r -lc_bars(data = list(), place = NULL, ..., id = NULL, - layerId = NULL, addLayer = F) +lc_bars( + data = list(), + place = NULL, + ..., + chartId = NULL, + layerId = NULL, + addLayer = FALSE +) ``` @@ -178,11 +244,11 @@ lc_bars(data = list(), place = NULL, ..., id = NULL, Argument |Description ------------- |---------------- `data` | Name value pairs of properties, passed through the [`dat`](#dat) function. These properties will be reevaluated on each [`updateCharts`](#updatecharts) call. -`place` | An ID of a container, where to place the chart. Will be ignored if the chart already exists. If not defined, the chart will be placed directly in the body of the opened page. -`...` | Name value pairs of properties that can be evaluated only once and then will remain constant. These properties can still be changed later using the [`setProperties`](#setproperties) function -`id` | An ID for the chart. All charts must have unique IDs. If a chart with the same ID already exists, a new layer will be added to it. If you want to replace one chart with another, use [`removeChart`](#removechart) first. If not defined, the ID will be set to `ChartN` , where `N - 1` is the number of currently existing charts. +`place` | ID of a container, where to place new chart. Will be ignored if the chart already exists. If not defined, the chart will be appended to the body of the web pages. +`...` | Name-value pairs of properties that will be evaluated only once and then will remain constant. These properties can still be changed later using the [`setProperties`](#setproperties) function. +`chartId` | ID for the chart. All charts must have unique IDs. If a chart with the same ID already exists, it will be replaced unless `addLayer = TRUE` . If ID is not defined, it will be the same as value of the `place` argument. And if both are not defined, the ID will be set to `ChartN` , where `N - 1` is the number of existing charts. `layerId` | An ID for the new layer. All layers within one chart must have different IDs. If a layer with the same ID already exists, it will be replaced. If not defined, will be set to `LayerN` , where `N - 1` is the number of currently existing layers in this chart. -`addLayer` | whether to add a new layer or to replace the existing one. This argument influences the chart only if it has only one layer and the `layerId` is not defined. +`addLayer` | if there is already a chart with the same ID, this argument defines whether to replace it or to add a new layer to it. This argument is ignored if both `place` and `chartId` are `NULL` or if there is no chart with the given ID. ## Available Properties @@ -194,11 +260,11 @@ You can read more about different properties * `value` - heights of bars/stacks. -* `stackIds` - IDs for all stacks (if necessary). Must be the same size as `values` . +* `stackIds` - IDs of all stacks ( optional ). Must be the same size as `values` . -* `barIds` - IDs for all bars (if necessary). Must be the same size as `values` . +* `barIds` - IDs of all bars ( optional ). Must be the same size as `values` . -* `groupIds` - IDs for all groups (if necessary). Must be the same size as `values` . +* `groupIds` - IDs of all groups ( optional ). Must be the same size as `values` . * `groupWidth` - ratio of width of a group of bars to the space, available to the group. @@ -207,9 +273,9 @@ You can read more about different properties * `opacity` - opacity of each bar|stack in the range from 0 to 1. -* `colour` - colour of each bar|stack. Must be a colour name or hexidecimal code. +* `colour` - colour of each bar|stack. Must be a colour name or hexadecimal code. -* `colourValue` - grouping values for different colours. Can be numbers or charachters. +* `colourValue` - grouping values for different colours. Can be numbers or characters. * `colourDomain` - vector of all possible values for discrete colour scales or range of all possible colour values for the continuous ones. @@ -221,7 +287,7 @@ You can read more about different properties * `globalColourScale` - whether or not to use one colour scale for all the layers. -* `stroke` - stroke colour of each bar|stack. Must be a colour name or hexidecimal code. +* `stroke` - stroke colour of each bar|stack. Must be a colour name or hexadecimal code. * `strokeWidth` - width of the strokes of each bar|stack. @@ -234,13 +300,15 @@ You can read more about different properties * `domainX, domainY` - default axes ranges for the entire chart. If not defined, is automatically set to include all layer domains. -* `contScaleX, consScaleY` - whether or not the axis should be continuous. +* `contScaleX, contScaleY` - whether or not the axis should be continuous. * `aspectRatio` - aspect ratio. * `axisTitleX, axisTitleY` - axes titles. -* `ticksRotateX, ticksRotateY` - degrees of angle to rotate ticks. Must be between 0 (horisontal ticks, default) and 90 (vertical ticks). +* `axisTitlePosX, axisTitlePosY` - position of axes titles. For each axis one can specify title position across or along the corresponding axis. Possible options are `"up"` (for title inside the plotting area) or `"down"` (outside the plottting area, under the axis), and `"start"` , `"middle"` , `"end"` . This property must be a string with one or two of the abovementioned options (e.g. `"middle down"` , `"start"` , etc.). + +* `ticksRotateX, ticksRotateY` - angle by which to rotate ticks (in degrees). Must be between 0 (horizontal ticks, default) and 90 (vertical ticks). * `ticksX, ticksY` - set of ticks for the axes. @@ -253,7 +321,7 @@ You can read more about different properties * `on_mouseout` - function, to be called, when mouse moves out of one of the bars. -* `on_marked` - function, to be called, when any of the bars are selected (marked) or deselected. Use [`getMarked`](#getmarked) function to get the IDs of the currently marked bars. +* `on_marked` - function, to be called, when any of the bars are selected (marked) or deselected. Use [`getMarked`](#getmarked) function to get the IDs of the currently marked bars. To mark bars, select them with your mouse while holding the Shift key. Global chart settings @@ -266,7 +334,7 @@ You can read more about different properties * `plotHeight` - height of the plotting area in pixels. -* `paddings` - paddings size in pixels. Must be a list with all the following fields: `"top", "bottom", "left", "right"` . +* `paddings` - padding sizes in pixels. Must be a list with all the following fields: `"top", "bottom", "left", "right"` . * `title` - title of the chart. @@ -276,43 +344,28 @@ You can read more about different properties * `showLegend` - whether or not to show the legend. -* `showPanel` - whether of not to show the tools panel. +* `showPanel` - whether of not to show the instrument panel (grey triangle in the upper-left corner of the chart). -* `transitionDuration` - duration of the transtions between any two states of the chart. If 0, no animated transition is shown. It can be useful to turn the transition off, when lots of frequent changes happen to the chart. +* `transitionDuration` - duration of the transitions between any two states of the chart. If 0, no animated transition is shown. It can be useful to turn the transition off, when lots of frequent changes happen to the chart. ## Examples ```r -data("esoph") - -lc_bars(dat(value = tapply(esoph$ncases, esoph$agegp, sum), -title = "Number of cases per age group", -axisTitleX = "Age group", -axisTitleY = "Number of esophageal cases")) - -lc_bars(dat(value = c(tapply(esoph$ncases, esoph$agegp, sum), tapply(esoph$ncontrols, esoph$agegp, sum)), -stackIds = c(rep("case", 6), rep("control", 6)))) +list("data(\"esoph\")\n", "\n", "lc_bars(dat(value = tapply(esoph$ncases, esoph$agegp, sum), \n", " title = \"Number of cases per age group\",\n", " axisTitleX = \"Age group\", \n", " axisTitleY = \"Number of esophageal cases\",\n", " axisTitlePosX = \"down\"))\n", "\n", "lc_bars(dat(value = c(tapply(esoph$ncases, esoph$agegp, sum), \n", " tapply(esoph$ncontrols, esoph$agegp, sum)),\n", " stackIds = c(rep(\"case\", 6), rep(\"control\", 6))))\n", + "\n", "#It is easy to put data in a convenient form for barplots using tidyverse\n", "library(magrittr)\n", "library(dplyr)\n", "library(tidyr)\n", "library(stringr)\n", "\n", "esoph %>%\n", " gather(type, cases, (ncases:ncontrols)) %>%\n", " mutate(type = str_sub(type, 2, -2)) %>%\n", " group_by(agegp, alcgp, type) %>%\n", " summarise(ncases = sum(cases)) -> newData\n", "\n", "lc_bars(dat(value = newData$ncases,\n", " stackIds = newData$type,\n", " barIds = newData$alcgp,\n", + " groupIds = newData$agegp))") +``` -#It is ease to put data in a convenient form for barplots using tidyverse -library(tidyverse) -esoph %>% -gather(type, cases, (ncases:ncontrols)) %>% -mutate(type = str_sub(type, 2, -2)) %>% -group_by(agegp, alcgp, type) %>% -summarise(ncases = sum(cases)) -> newData +# `lc_colourSlider` -lc_bars(dat(value = newData$ncases, -stackIds = newData$type, -barIds = newData$alcgp, -groupIds = newData$agegp)) -``` +Add a colour slider -# Add a colour slider +## Alias -* `lc_colourSlider` +`lc_colourSlider` ## Description @@ -326,7 +379,7 @@ Colour slider provides an easy way to change any continuous colour scale ## Usage ```r -lc_colourSlider(data = list(), place = NULL, ..., id = NULL) +lc_colourSlider(data = list(), place = NULL, ..., chartId = NULL) ``` @@ -335,9 +388,9 @@ lc_colourSlider(data = list(), place = NULL, ..., id = NULL) Argument |Description ------------- |---------------- `data` | Name value pairs of properties, passed through the [`dat`](#dat) function. These properties will be reevaluated on each [`updateCharts`](#updatecharts) call. -`place` | An ID of a container, where to place the chart. Will be ignored if the chart already exists. If not defined, the chart will be placed directly in the body of the opened page. -`...` | Name value pairs of properties that can be evaluated only once and then will remain constant. These properties can still be changed later using the [`setProperties`](#setproperties) function -`id` | An ID for the chart. All charts must have unique IDs. If a chart with the same ID already exists, a new layer will be added to it. If you want to replace one chart with another, use [`removeChart`](#removechart) first. If not defined, the ID will be set to `ChartN` , where `N - 1` is the number of currently existing charts. +`place` | ID of a container, where to place new chart. Will be ignored if the chart already exists. If not defined, the chart will be appended to the body of the web pages. +`...` | Name-value pairs of properties that will be evaluated only once and then will remain constant. These properties can still be changed later using the [`setProperties`](#setproperties) function. +`chartId` | ID for the chart. All charts must have unique IDs. If a chart with the same ID already exists, it will be replaced. If ID is not defined, it will be the same as value of the `place` argument. And if both are not defined, the ID will be set to `ChartN` , where `N - 1` is the number of existing charts.. ## Available Properties @@ -347,9 +400,9 @@ You can read more about different properties -* `chart` - id of the chart whose colour scale should be linked to the colour slider. +* `chart` - ID of the chart to which the colour slider should be linked. -* `layer` - id of the layer whose colour scale should be linked to the colour slider. If chart has only one layer, this property can be omitted. +* `layer` - id of the layer to which the colour slider should be linked. If the chart has only one layer, this property is optional. Global chart settings @@ -358,7 +411,7 @@ You can read more about different properties * `heigth` - height of the chart in pixels. -* `paddings` - paddings size in pixels. Must be a list with all the following fields: `"top", "bottom", "left", "right"` . +* `paddings` - padding sizes in pixels. Must be a list with all the following fields: `"top", "bottom", "left", "right"` . * `title` - title of the chart. @@ -370,39 +423,31 @@ You can read more about different properties ## Examples ```r -data("iris") -lc_scatter(dat(x = iris$Sepal.Length, -y = iris$Petal.Length, -colourValue = iris$Petal.Width, -symbolValue = iris$Species), -title = "Iris dataset", -axisTitleY = "Petal Length", -axisTitleX = "Sepal Length", -colourLegendTitle = "Petal Width", -symbolLegendTitle = "Species", -showLegend = F, -id = "scatter") - -lc_colourSlider(chart = "scatter") +list("data(\"iris\")\n", "lc_scatter(dat(x = iris$Sepal.Length, \n", " y = iris$Petal.Length,\n", " colourValue = iris$Petal.Width,\n", " symbolValue = iris$Species),\n", " title = \"Iris dataset\",\n", " axisTitleY = \"Petal Length\",\n", " axisTitleX = \"Sepal Length\",\n", " colourLegendTitle = \"Petal Width\",\n", " symbolLegendTitle = \"Species\",\n", " showLegend = FALSE,\n", " chartId = \"scatter\")\n", + "\n", "lc_colourSlider(chart = \"scatter\")") ``` -# Create a heatmap +# `lc_heatmap` + +Create a heatmap + -* `lc_heatmap` +## Alias + +`lc_heatmap` ## Description -`lc_heatmap` creates a new heatmaps. Unlike charts with axes, heatmaps do not have +`lc_heatmap` creates a new heatmap. Unlike charts with axes, heatmaps do not have any layers. ## Usage ```r -lc_heatmap(data = list(), place = NULL, ..., id = NULL, - pacerStep = 50) +lc_heatmap(data = list(), place = NULL, ..., chartId = NULL, pacerStep = 50) ``` @@ -411,10 +456,10 @@ lc_heatmap(data = list(), place = NULL, ..., id = NULL, Argument |Description ------------- |---------------- `data` | Name value pairs of properties, passed through the [`dat`](#dat) function. These properties will be reevaluated on each [`updateCharts`](#updatecharts) call. -`place` | An ID of a container, where to place the chart. Will be ignored if the chart already exists. If not defined, the chart will be placed directly in the body of the opened page. -`...` | Name value pairs of properties that can be evaluated only once and then will remain constant. These properties can still be changed later using the [`setProperties`](#setproperties) function -`id` | An ID for the chart. All charts must have unique IDs. If a chart with the same ID already exists, a new layer will be added to it. If you want to replace one chart with another, use [`removeChart`](#removechart) first. If not defined, the ID will be set to `ChartN` , where `N - 1` is the number of currently existing charts. -`pacerStep` | Time in ms between to consequentive calls of onmouseover event. Prevents overqueuing in case of cumbersome computations. May be important when the chart works in canvas mode. +`place` | ID of a container, where to place new chart. Will be ignored if the chart already exists. If not defined, the chart will be appended to the body of the web pages. +`...` | Name-value pairs of properties that will be evaluated only once and then will remain constant. These properties can still be changed later using the [`setProperties`](#setproperties) function. +`chartId` | ID for the chart. All charts must have unique IDs. If a chart with the same ID already exists, it will be replaced. If ID is not defined, it will be the same as value of the `place` argument. And if both are not defined, the ID will be set to `ChartN` , where `N - 1` is the number of existing charts. +`pacerStep` | Time in ms between two consecutive calls of an `onmouseover` event. Prevents overqueuing in case of cumbersome computations. May be important when the chart works in canvas mode. ## Available Properties @@ -424,7 +469,7 @@ You can read more about different properties -* `value` - matrix of values. +* `value` - matrix of values that will be displayed as a heatmap. * `rowLabel, colLabel` - vector of labels for all rows or columns. @@ -436,27 +481,27 @@ You can read more about different properties * `heatmapRow, heatmapCol` - default order of rows and columns of the heatmap. -* `showValue` - if `TRUE` , than in the values will be shown as text in each cell. +* `showValue` - if `TRUE` , values will be shown as text in each cell. Style settings -* `rowTitle, colTilte` - titles of rows and columns. +* `rowTitle, colTilte` - titles for rows and columns (similar to axes titles). -* `palette` - vector of colours to construct the colour scale. +* `palette` - vector of colours to construct a colour scale. * `colourDomain` - domain of the colour scale. All values outside it will be clamped to its edges. Interactivity settings -* `on_click` - function, to be called, when one of the cells is clicked. Gets row and column idices of the clicked cell as its arguments. +* `on_click` - function, to be called, when one of the cells is clicked. Gets a vector of row and column indices of the clicked cell as its arguments. -* `on_mouseover` - function, to be called, when mouse hovers over one of the cells. Gets row and column indices of the clicked cell as its arguments. +* `on_mouseover` - function, to be called, when mouse hovers over one of the cells. Gets a vector of row and column indices of the clicked cell as its arguments. -* `on_mouseout` - function, to be called, when mouse moves out of one of the cells. +* `on_mouseout` - function, to be called, when mouse moves away from one of the cells. -* `on_marked` - function, to be called, when any of the cells are selected (marked) or deselected. Use [`getMarked`](#getmarked) function to get the IDs of the currently marked cells. +* `on_marked` - function, to be called, when any of the cells are selected (marked) or deselected. Use [`getMarked`](#getmarked) function to get the IDs of the currently marked cells. To mark cells, select them with your mouse while holding the Shift key. Global chart settings @@ -469,7 +514,7 @@ You can read more about different properties * `plotHeight` - height of the plotting area in pixels. -* `paddings` - paddings size in pixels. Must be a list with all the following fields: `"top", "bottom", "left", "right"` . +* `paddings` - padding sizes in pixels. Must be a list with all the following fields: `"top", "bottom", "left", "right"` . * `title` - title of the chart. @@ -479,45 +524,28 @@ You can read more about different properties * `showLegend` - whether or not to show the legend. -* `showPanel` - whether of not to show the tools panel. +* `showPanel` - whether of not to show the instrument panel (grey triangle in the upper-left corner of the chart). -* `transitionDuration` - duration of the transtions between any two states of the chart. If 0, no animated transition is shown. It can be useful to turn the transition off, when lots of frequent changes happen to the chart. +* `transitionDuration` - duration of the transitions between any two states of the chart. If 0, no animated transition is shown. It can be useful to turn the transition off, when lots of frequent changes happen to the chart. ## Examples ```r -#create a test matrix -test <- cbind(sapply(1:10, function(i) c(rnorm(10, mean = 1, sd = 3), -rnorm(6, mean = 5, sd = 2), -runif(14, 0, 8))), -sapply(1:10, function(i) c(rnorm(10, mean = 3, sd = 2), -rnorm(6, mean = 1, sd = 2), -runif(14, 0, 8)))) -test[test < 0] <- 0 -rownames(test) <- paste0("Gene", 1:30) -colnames(test) <- paste0("Sample", 1:20) - -lc_heatmap(dat(value = test)) - -# when you want to cluster rows or columns, it can be -# a good idea to make bottom and right paddings larger to -# fit labels -lc_heatmap(dat(value = test), -clusterRows = T, -clusterCols = T, -paddings = list(top = 50, left = 30, bottom = 75, right = 75)) - -lc_heatmap(dat(value = cor(test), -colourDomain = c(-1, 1), -palette = RColorBrewer::brewer.pal(11, "RdYlBu"))) +list("\n", "library(RColorBrewer)\n", "#create a test matrix\n", "test <- cbind(sapply(1:10, function(i) c(rnorm(10, mean = 1, sd = 3), \n", " rnorm(6, mean = 5, sd = 2), \n", " runif(14, 0, 8))),\n", " sapply(1:10, function(i) c(rnorm(10, mean = 3, sd = 2), \n", " rnorm(6, mean = 1, sd = 2), \n", " runif(14, 0, 8))))\n", "test[test < 0] <- 0\n", + "rownames(test) <- paste0(\"Gene\", 1:30)\n", "colnames(test) <- paste0(\"Sample\", 1:20)\n", "\n", "lc_heatmap(dat(value = test))\n", "\n", "# when you want to cluster rows or columns, it can be\n", "# a good idea to make bottom and right paddings larger to\n", "# fit labels\n", "lc_heatmap(dat(value = test),\n", " clusterRows = TRUE,\n", " clusterCols = TRUE,\n", " paddings = list(top = 50, left = 30, bottom = 75, right = 75))\n", "\n", "lc_heatmap(dat(value = cor(test), \n", + " colourDomain = c(-1, 1),\n", " palette = brewer.pal(11, \"RdYlBu\")))") ``` -# Histograms and density plots +# `lc_hist` + +Histograms and density plots -* `lc_hist` -* `lc_dens` + +## Alias + +`lc_hist`, `lc_dens` ## Description @@ -529,10 +557,22 @@ These functions make either a histogram or a density plot of the given data ## Usage ```r -lc_hist(data = list(), place = NULL, ..., id = NULL, - layerId = NULL, addLayer = F) -lc_dens(data = list(), place = NULL, ..., id = NULL, - layerId = NULL, addLayer = F) +lc_hist( + data = list(), + place = NULL, + ..., + chartId = NULL, + layerId = NULL, + addLayer = FALSE +) +lc_dens( + data = list(), + place = NULL, + ..., + chartId = NULL, + layerId = NULL, + addLayer = FALSE +) ``` @@ -541,11 +581,11 @@ lc_dens(data = list(), place = NULL, ..., id = NULL, Argument |Description ------------- |---------------- `data` | Name value pairs of properties, passed through the [`dat`](#dat) function. These properties will be reevaluated on each [`updateCharts`](#updatecharts) call. -`place` | An ID of a container, where to place the chart. Will be ignored if the chart already exists. If not defined, the chart will be placed directly in the body of the opened page. -`...` | Name value pairs of properties that can be evaluated only once and then will remain constant. These properties can still be changed later using the [`setProperties`](#setproperties) function -`id` | An ID for the chart. All charts must have unique IDs. If a chart with the same ID already exists, a new layer will be added to it. If you want to replace one chart with another, use [`removeChart`](#removechart) first. If not defined, the ID will be set to `ChartN` , where `N - 1` is the number of currently existing charts. +`place` | ID of a container, where to place new chart. Will be ignored if the chart already exists. If not defined, the chart will be appended to the body of the web pages. +`...` | Name-value pairs of properties that will be evaluated only once and then will remain constant. These properties can still be changed later using the [`setProperties`](#setproperties) function. +`chartId` | ID for the chart. All charts must have unique IDs. If a chart with the same ID already exists, it will be replaced unless `addLayer = TRUE` . If ID is not defined, it will be the same as value of the `place` argument. And if both are not defined, the ID will be set to `ChartN` , where `N - 1` is the number of existing charts. `layerId` | An ID for the new layer. All layers within one chart must have different IDs. If a layer with the same ID already exists, it will be replaced. If not defined, will be set to `LayerN` , where `N - 1` is the number of currently existing layers in this chart. -`addLayer` | whether to add a new layer or to replace the existing one. This argument influences the chart only if it has only one layer and the `layerId` is not defined. +`addLayer` | if there is already a chart with the same ID, this argument defines whether to replace it or to add a new layer to it. This argument is ignored if both `place` and `chartId` are `NULL` or if there is no chart with the given ID. ## Functions @@ -557,37 +597,46 @@ Argument |Description ## Available Properties -* `value` - vector of data. +You can read more about different properties + [here](https://anders-biostat.github.io/linked-charts/rlc/tutorials/props.html) . + + + +* `value` - vector of data values. * `nbins` - (only for `lc_hist` ) number of bins. These functions are extensions of [`lc_line`](#lcline) ( `lc_dens` ) or [`lc_bars`](#lcbars) - ( `lc_hist` ) and therefore can also understand their properties. + ( `lc_hist` ) and therefore also accept all their properties. ## Examples ```r -lc_hist(dat(value = rnorm(1000), nbins = 30, height = 300)) -lc_dens(dat(value = rnorm(1000), height = 300)) +list("\n", "lc_hist(dat(value = rnorm(1000), nbins = 30, height = 300))\n", "lc_dens(dat(value = rnorm(1000), height = 300)) ") ``` -# Add HTML code to the page +# `lc_html` + +Add HTML code to the page + -* `lc_html` +## Alias + +`lc_html` ## Description -`lc_html` adds a block with HTML code. It uses [`hwrite`](#hwrite) function +`lc_html` adds a block of HTML code. It uses [`hwrite`](#hwrite) function to transform some data structures (e.g. data frames) to HTML tables. ## Usage ```r -lc_html(data = list(), place = NULL, ..., id = NULL) +lc_html(data = list(), place = NULL, ..., chartId = NULL) ``` @@ -596,9 +645,9 @@ lc_html(data = list(), place = NULL, ..., id = NULL) Argument |Description ------------- |---------------- `data` | Name value pairs of properties, passed through the [`dat`](#dat) function. These properties will be reevaluated on each [`updateCharts`](#updatecharts) call. -`place` | An ID of a container, where to place the chart. Will be ignored if the chart already exists. If not defined, the chart will be placed directly in the body of the opened page. -`...` | Name value pairs of properties that can be evaluated only once and then will remain constant. These properties can still be changed later using the [`setProperties`](#setproperties) function -`id` | An ID for the chart. All charts must have unique IDs. If a chart with the same ID already exists, a new layer will be added to it. If you want to replace one chart with another, use [`removeChart`](#removechart) first. If not defined, the ID will be set to `ChartN` , where `N - 1` is the number of currently existing charts. +`place` | ID of a container, where to place new chart. Will be ignored if the chart already exists. If not defined, the chart will be appended to the body of the web pages. +`...` | Name-value pairs of properties that will be evaluated only once and then will remain constant. These properties can still be changed later using the [`setProperties`](#setproperties) function. +`chartId` | ID for the chart. All charts must have unique IDs. If a chart with the same ID already exists, it will be replaced. If ID is not defined, it will be the same as value of the `place` argument. And if both are not defined, the ID will be set to `ChartN` , where `N - 1` is the number of existing charts. ## Available Properties @@ -608,65 +657,166 @@ You can read more about different properties -* `content` - HTML code to display on the page. Can also be a vector, data.frame or any other structure, that can be transformed by [`hwrite`](#hwrite) . +* `content` - HTML code to display on the page. Can also be a vector, data.frame or any other structure, that can be transformed to HTML by [`hwrite`](#hwrite) . Global chart settings -* `width` - width of the chart in pixels. By default, the entire content will be displayed. If width is defined and it's smaller than content's width, scrolling will be possible. +* `width` - width of the chart in pixels. By default, width will be set to fit the content. If width is defined and it's smaller than content's width, scrolling will be possible. -* `heigth` - height of the chart in pixels. By default, the entire content will be displayed. If height is defined and it's smaller than content's height, scrolling will be possible. +* `heigth` - height of the chart in pixels. By default, height will be set to fit the content. If height is defined and it's smaller than content's height, scrolling will be possible. -* `paddings` - paddings size in pixels. Must be a list with all the following fields: `"top", "bottom", "left", "right"` . +* `paddings` - padding sizes in pixels. Must be a list with all the following fields: `"top", "bottom", "left", "right"` . -* `title` - title of the chart. -* `titleX, titleY` - coordinates of the chart title. +## Examples -* `titleSize` - font-size of the chart title. +```r +list("lc_html(content = \"Some HTML
code.\")\n", "lc_html(dat(content = matrix(1:12, nrow = 4)))\n", "data(iris)\n", "lc_html(content = iris, height = 200)") +``` + + +# `lc_input` + +Add input forms to the page + + +## Alias + +`lc_input` + + +## Description + +`lc_input` adds an input form. This function is an rlc wrapper for an + HTML `` tag. Five types of input are supported: `"text"` , `"range"` , + `"checkbox"` , `"radio"` and `"button"` . + + +## Usage + +```r +lc_input(data = list(), place = NULL, ..., chartId = NULL) +``` + + +## Arguments + +Argument |Description +------------- |---------------- +`data` | Name value pairs of properties, passed through the [`dat`](#dat) function. These properties will be reevaluated on each [`updateCharts`](#updatecharts) call. +`place` | ID of a container, where to place new chart. Will be ignored if the chart already exists. If not defined, the chart will be appended to the body of the web pages. +`...` | Name-value pairs of properties that will be evaluated only once and then will remain constant. These properties can still be changed later using the [`setProperties`](#setproperties) function. +`chartId` | ID for the chart. All charts must have unique IDs. If a chart with the same ID already exists, it will be replaced. If ID is not defined, it will be the same as value of the `place` argument. And if both are not defined, the ID will be set to `ChartN` , where `N - 1` is the number of existing charts. + + +## Available Properties + +You can read more about different properties + [here](https://anders-biostat.github.io/linked-charts/rlc/tutorials/props.html) . + + + +* `type` - type of input. Must be one of `"text"` , `"range"` , `"checkbox"` , `"radio"` or `"button"` . + +* `value` - current state of the input block. For radio buttons it is an index of the checked button. For checkboxes - a vector of `TRUE` (for each checked box) and `FALSE` (for each unchecked ones), for ranges and text boxes - a vector of values for each text field or slider. + +* `step` (only for `type = "range"` ) - stepping interval for values that can be selected with the slider. Must be a numeric vector with one value for each slider in the input block. + +* `min, max` (only for `type = "range"` ) - minimal and maximal values that can be selected with the slider. Must be a numeric vector with one value for each slider in the input block. + + Interactivity settings + + +* `on_click, on_change` - function, to be called, when user clicks on a button, enters text in a text field or moves a slider. The two properties are complete synonyms and can replace one another. + + Global chart settings + + +* `title` - title of the input block. + +* `width` - width of the chart in pixels. By default, width will be set to fit the content. If width is defined and it's smaller than content's width, scrolling will be possible. + +* `heigth` - height of the chart in pixels. By default, height will be set to fit the content. If height is defined and it's smaller than content's height, scrolling will be possible. + +* `paddings` - padding sizes in pixels. Must be a list with all the following fields: `"top", "bottom", "left", "right"` . ## Examples ```r -lc_html(content = "Some HTML
code.") -lc_html(dat(content = matrix(1:12, nrow = 4))) -data(iris) -lc_html(content = iris, height = 200) +list("lc_input(type = \"checkbox\", labels = paste0(\"el\", 1:5), on_click = function(value) print(value),\n", "value = TRUE)\n", "lc_input(type = \"radio\", labels = paste0(\"el\", 1:5), on_click = function(value) print(value),\n", " value = 1)\n", "lc_input(type = \"text\", labels = paste0(\"el\", 1:5), on_click = function(value) print(value),\n", " value = c(\"a\", \"b\", \"c\", \"e\", \"d\"))\n", "lc_input(type = \"range\", labels = paste0(\"el\", 1:5), on_click = function(value) print(value),\n", + " value = 10, max = c(10, 20, 30, 40, 50), step = c(0.5, 0.1, 1, 5, 25))\n", "lc_input(type = \"button\", labels = paste0(\"el\", 1:5), on_click = function(value) print(value))") ``` -# Lines and ribbons +# `lc_line` + +Lines and ribbons -* `lc_line` -* `lc_path` -* `lc_ribbon` -* `lc_abLine` -* `lc_hLine` -* `lc_vLine` + +## Alias + +`lc_line`, `lc_path`, `lc_ribbon`, `lc_abLine`, `lc_hLine`, `lc_vLine` ## Description -These functions create different kind of lines. They connect observations or - create filled area, bordered by a line. Each layer may have one or several lines. +These functions create various kinds of lines. They connect observations or + create filled areas with customized border. Each layer may have one or several lines. ## Usage ```r -lc_line(data = list(), place = NULL, ..., id = NULL, - layerId = NULL, addLayer = F) -lc_path(data = list(), place = NULL, ..., id = NULL, - layerId = NULL, addLayer = F) -lc_ribbon(data = list(), place = NULL, ..., id = NULL, - layerId = NULL, addLayer = F) -lc_abLine(data = list(), place = NULL, ..., id = NULL, - layerId = NULL, addLayer = F) -lc_hLine(data = list(), place = NULL, ..., id = NULL, - layerId = NULL, addLayer = F) -lc_vLine(data = list(), place = NULL, ..., id = NULL, - layerId = NULL, addLayer = F) +lc_line( + data = list(), + place = NULL, + ..., + chartId = NULL, + layerId = NULL, + addLayer = FALSE +) +lc_path( + data = list(), + place = NULL, + ..., + chartId = NULL, + layerId = NULL, + addLayer = FALSE +) +lc_ribbon( + data = list(), + place = NULL, + ..., + chartId = NULL, + layerId = NULL, + addLayer = FALSE +) +lc_abLine( + data = list(), + place = NULL, + ..., + chartId = NULL, + layerId = NULL, + addLayer = FALSE +) +lc_hLine( + data = list(), + place = NULL, + ..., + chartId = NULL, + layerId = NULL, + addLayer = FALSE +) +lc_vLine( + data = list(), + place = NULL, + ..., + chartId = NULL, + layerId = NULL, + addLayer = FALSE +) ``` @@ -675,11 +825,11 @@ lc_vLine(data = list(), place = NULL, ..., id = NULL, Argument |Description ------------- |---------------- `data` | Name value pairs of properties, passed through the [`dat`](#dat) function. These properties will be reevaluated on each [`updateCharts`](#updatecharts) call. -`place` | An ID of a container, where to place the chart. Will be ignored if the chart already exists. If not defined, the chart will be placed directly in the body of the opened page. -`...` | Name value pairs of properties that can be evaluated only once and then will remain constant. These properties can still be changed later using the [`setProperties`](#setproperties) function -`id` | An ID for the chart. All charts must have unique IDs. If a chart with the same ID already exists, a new layer will be added to it. If you want to replace one chart with another, use [`removeChart`](#removechart) first. If not defined, the ID will be set to `ChartN` , where `N - 1` is the number of currently existing charts. +`place` | ID of a container, where to place new chart. Will be ignored if the chart already exists. If not defined, the chart will be appended to the body of the web pages. +`...` | Name-value pairs of properties that will be evaluated only once and then will remain constant. These properties can still be changed later using the [`setProperties`](#setproperties) function. +`chartId` | ID for the chart. All charts must have unique IDs. If a chart with the same ID already exists, it will be replaced unless `addLayer = TRUE` . If ID is not defined, it will be the same as value of the `place` argument. And if both are not defined, the ID will be set to `ChartN` , where `N - 1` is the number of existing charts. `layerId` | An ID for the new layer. All layers within one chart must have different IDs. If a layer with the same ID already exists, it will be replaced. If not defined, will be set to `LayerN` , where `N - 1` is the number of currently existing layers in this chart. -`addLayer` | whether to add a new layer or to replace the existing one. This argument influences the chart only if it has only one layer and the `layerId` is not defined. +`addLayer` | if there is already a chart with the same ID, this argument defines whether to replace it or to add a new layer to it. This argument is ignored if both `place` and `chartId` are `NULL` or if there is no chart with the given ID. ## Functions @@ -692,7 +842,7 @@ Argument |Description * `lc_abLine` : creates straight lines by intercept and slope values -* `lc_hLine` : creates horisontal lines by y-intercept values +* `lc_hLine` : creates horizontal lines by y-intercept values * `lc_vLine` : creates vertical lines by x-intercept values @@ -706,7 +856,7 @@ You can read more about different properties * `x, y` - vector of x and y coordinates of the points to connect. Can be vectors for a single line or `m x n` matrix for `n` lines. -* `ymax, ymin` - (only for `lc_ribbon` ) vectors of maximal and minimal values of the ribbon. +* `ymax, ymin` - (only for `lc_ribbon` ) vectors of maximal and minimal values for a ribbon. * `a, b` - (only for `lc_abLine` ) vectors of slope and intercept values respectively. @@ -714,22 +864,22 @@ You can read more about different properties * `h` - (only for `lc_hLine` ) vector of y-intercepts. -* `lineWidth` - width of each line. +* `lineWidth` - (nor for `lc_ribbon` ) width of each line. -* `opacity` - opacity of the lines in the range from 0 to 1. +* `opacity` - opacity of each line in the range from 0 to 1. -* `label` - vector of text labels for each line. +* `label` - vector of text labels for each line (labels by default are shown, when mouse hovers over a line). * `dasharray` - defines pattern of dashes and gaps for each line. Colour settings -* `colour` - colour of the lines. Must be a colour name or hexidecimal code. For `lc_ribbon` this property defined the colour of the ribbon, not the strokes. +* `colour` - colour of the lines. Must be a colour name or hexadecimal code. For `lc_ribbon` this property defines colour of the ribbon, not the strokes. -* `fill` - colour with wich to fill area inside the line. Must be a colour name or hexidecimal code. +* `fill` - (not for `lc_ribbon` ) colour with which to fill area inside the line. Must be a colour name or hexadecimal code. -* `colourValue` - grouping values for different colours. Can be numbers or charachters. +* `colourValue` - grouping values for different colours. Can be numbers or characters. * `colourDomain` - vector of all possible values for discrete colour scales or range of all possible colour values for the continuous ones. @@ -741,7 +891,7 @@ You can read more about different properties * `globalColourScale` - whether or not to use one colour scale for all the layers. -* `stroke` - (only for `lc_ribbon` ) stroke colour for each ribbon. Must be a colour name or hexidecimal code. +* `stroke` - (only for `lc_ribbon` ) stroke colour for each ribbon. Must be a colour name or hexadecimal code. * `strokeWidth` - (only for `lc_ribbon` ) width of the strokes for each ribbon. @@ -754,13 +904,15 @@ You can read more about different properties * `domainX, domainY` - default axes ranges for the entire chart. If not defined, is automatically set to include all layer domains. -* `contScaleX, consScaleY` - whether or not the axis should be continuous. +* `contScaleX, contScaleY` - whether or not the axis should be continuous. * `aspectRatio` - aspect ratio. * `axisTitleX, axisTitleY` - axes titles. -* `ticksRotateX, ticksRotateY` - degrees of angle to rotate ticks. Must be between 0 (horisontal ticks, default) and 90 (vertical ticks). +* `axisTitlePosX, axisTitlePosY` - position of axes titles. For each axis one can specify title position across or along the corresponding axis. Possible options are `"up"` (for title inside the plotting area) or `"down"` (outside the plottting area, under the axis), and `"start"` , `"middle"` , `"end"` . This property must be a string with one or two of the abovementioned options (e.g. `"middle down"` , `"start"` , etc.). + +* `ticksRotateX, ticksRotateY` - angle by which to rotate ticks (in degrees). Must be between 0 (horizontal ticks, default) and 90 (vertical ticks). * `ticksX, ticksY` - set of ticks for the axes. @@ -773,7 +925,7 @@ You can read more about different properties * `on_mouseout` - function, to be called, when mouse moves out of one of the lines. -* `on_marked` - function, to be called, when any of the lines are selected (marked) or deselected. Use [`getMarked`](#getmarked) function to get the IDs of the currently marked lines. +* `on_marked` - function, to be called, when any of the lines are selected (marked) or deselected. Use [`getMarked`](#getmarked) function to get the IDs of the currently marked lines. To mark lines, select them with your mouse while holding the Shift key. Global chart settings @@ -786,7 +938,7 @@ You can read more about different properties * `plotHeight` - height of the plotting area in pixels. -* `paddings` - paddings size in pixels. Must be a list with all the following fields: `"top", "bottom", "left", "right"` . +* `paddings` - padding sizes in pixels. Must be a list with all the following fields: `"top", "bottom", "left", "right"` . * `title` - title of the chart. @@ -796,48 +948,28 @@ You can read more about different properties * `showLegend` - whether or not to show the legend. -* `showPanel` - whether of not to show the tools panel. +* `showPanel` - whether of not to show the instrument panel (grey triangle in the upper-left corner of the chart). -* `transitionDuration` - duration of the transtions between any two states of the chart. If 0, no animated transition is shown. It can be useful to turn the transition off, when lots of frequent changes happen to the chart. +* `transitionDuration` - duration of the transitions between any two states of the chart. If 0, no animated transition is shown. It can be useful to turn the transition off, when lots of frequent changes happen to the chart. ## Examples ```r -x <- seq(0, 8, 0.2) -lc_line(dat(x = x, y = cbind(cos(x), sin(x)), -aspectRatio = 1, -colour = c("blue", "red"), -dasharray = c("5", "1 5 5"))) - -points <- seq(0, 6.5, 0.1) -x <- cos(points) -y <- sin(points) -lc_path(dat(x = sapply(0:2, function(i) x + i), -y = sapply(0:2, function(i) y + i), -fill = c("blue", "red", "black"), -opacity = c(0.3, 0.5, 0.7))) - -x <- seq(0, 5, 0.1) -y <- x*3 + rnorm(length(x), sd = 2) -fit <- lm(y ~ x) -pred <- predict(fit, data.frame(x = x), se.fit = T) -lc_ribbon(dat(ymin = pred$fit - 1.96 * pred$se.fit, -ymax = pred$fit + 1.96 * pred$se.fit, -x = x, -colour = "#555555"), id = "ribbonTest") -lc_scatter(dat(x = x, y = y), size = 2, id = "ribbonTest") -lc_abLine(dat(a = fit$coefficients[2], b = fit$coefficients[1]), id = "ribbonTest") - -lc_hLine(dat(h = seq(1, 9, 1), domainX = c(0, 10), domainY = c(0, 10)), id = "grid") -lc_vLine(dat(v = seq(1, 9, 1)), id = "grid") +list("x <- seq(0, 8, 0.2)\n", "lc_line(dat(x = x, y = cbind(cos(x), sin(x)),\n", " aspectRatio = 1,\n", " colour = c(\"blue\", \"red\"),\n", " dasharray = c(\"5\", \"1 5 5\")))\n", " \n", "points <- seq(0, 6.5, 0.1)\n", "x <- cos(points)\n", "y <- sin(points)\n", "lc_path(dat(x = sapply(0:2, function(i) x + i), \n", " y = sapply(0:2, function(i) y + i),\n", " fill = c(\"blue\", \"red\", \"black\"),\n", " opacity = c(0.3, 0.5, 0.7)))\n", + " \n", "x <- seq(0, 5, 0.1)\n", "y <- x*3 + rnorm(length(x), sd = 2)\n", "fit <- lm(y ~ x)\n", "pred <- predict(fit, data.frame(x = x), se.fit = TRUE)\n", "lc_ribbon(dat(ymin = pred$fit - 1.96 * pred$se.fit,\n", " ymax = pred$fit + 1.96 * pred$se.fit,\n", " x = x,\n", " colour = \"#555555\"), chartId = \"ribbonTest\")\n", "lc_scatter(dat(x = x, y = y), size = 2, chartId = \"ribbonTest\", addLayer = TRUE)\n", "lc_abLine(dat(a = fit$coefficients[2], b = fit$coefficients[1]), chartId = \"ribbonTest\", addLayer = TRUE)\n", + "\n", "lc_hLine(dat(h = seq(1, 9, 1), domainX = c(0, 10), domainY = c(0, 10)), chartId = \"grid\")\n", "lc_vLine(dat(v = seq(1, 9, 1)), chartId = \"grid\", addLayer = TRUE)") ``` -# Visualize a set of points +# `lc_scatter` + +Visualize a set of points + + +## Alias -* `lc_scatter` -* `lc_beeswarm` +`lc_scatter`, `lc_beeswarm` ## Description @@ -849,10 +981,24 @@ These functions plot a set of points with known coordinates that can be either c ## Usage ```r -lc_scatter(data = list(), place = NULL, ..., id = NULL, - layerId = NULL, addLayer = F, pacerStep = 50) -lc_beeswarm(data = list(), place = NULL, ..., id = NULL, - layerId = NULL, addLayer = F, pacerStep = 50) +lc_scatter( + data = list(), + place = NULL, + ..., + chartId = NULL, + layerId = NULL, + addLayer = FALSE, + pacerStep = 50 +) +lc_beeswarm( + data = list(), + place = NULL, + ..., + chartId = NULL, + layerId = NULL, + addLayer = FALSE, + pacerStep = 50 +) ``` @@ -861,12 +1007,12 @@ lc_beeswarm(data = list(), place = NULL, ..., id = NULL, Argument |Description ------------- |---------------- `data` | Name value pairs of properties, passed through the [`dat`](#dat) function. These properties will be reevaluated on each [`updateCharts`](#updatecharts) call. -`place` | An ID of a container, where to place the chart. Will be ignored if the chart already exists. If not defined, the chart will be placed directly in the body of the opened page. -`...` | Name value pairs of properties that can be evaluated only once and then will remain constant. These properties can still be changed later using the [`setProperties`](#setproperties) function -`id` | An ID for the chart. All charts must have unique IDs. If a chart with the same ID already exists, a new layer will be added to it. If you want to replace one chart with another, use [`removeChart`](#removechart) first. If not defined, the ID will be set to `ChartN` , where `N - 1` is the number of currently existing charts. +`place` | ID of a container, where to place new chart. Will be ignored if the chart already exists. If not defined, the chart will be appended to the body of the web pages. +`...` | Name-value pairs of properties that will be evaluated only once and then will remain constant. These properties can still be changed later using the [`setProperties`](#setproperties) function. +`chartId` | ID for the chart. All charts must have unique IDs. If a chart with the same ID already exists, it will be replaced unless `addLayer = TRUE` . If ID is not defined, it will be the same as value of the `place` argument. And if both are not defined, the ID will be set to `ChartN` , where `N - 1` is the number of existing charts. `layerId` | An ID for the new layer. All layers within one chart must have different IDs. If a layer with the same ID already exists, it will be replaced. If not defined, will be set to `LayerN` , where `N - 1` is the number of currently existing layers in this chart. -`addLayer` | whether to add a new layer or to replace the existing one. This argument influences the chart only if it has only one layer and the `layerId` is not defined. -`pacerStep` | Time in ms between to consequentive calls of onmouseover event. Prevents overqueuing in case of cumbersome computations. May be important when the chart works in canvas mode. +`addLayer` | if there is already a chart with the same ID, this argument defines whether to replace it or to add a new layer to it. This argument is ignored if both `place` and `chartId` are `NULL` or if there is no chart with the given ID. +`pacerStep` | Time in ms between two consecutive calls of an `onmouseover` event. Prevents overqueuing in case of cumbersome computations. May be important when the chart works in canvas mode. ## Functions @@ -887,18 +1033,18 @@ You can read more about different properties * `size` - sizes of the points. Default size is 6. -* `opacity` - opacity of the points in the range from 0 to 1. +* `opacity` - opacity of each point in the range from 0 to 1. -* `label` - vector of text labels for each point. +* `label` - vector of text labels for each point (labels by default are shown, when mouse hovers over a point). -* `valueAxis` - (for `lc_beeswarm` only) defines, values along which of the axes should not be changed. Must be `"x"` or `"y"` . +* `valueAxis` - (for `lc_beeswarm` only) defines axis with values that will not be changed. Must be `"x"` or `"y"` (default). Colour and shape settings -* `colour` - colour of the points. Must be a colour name or hexidecimal code. +* `colour` - colour of the points. Must be a colour name or hexadecimal code. -* `colourValue` - grouping values for different colours. Can be numbers or charachters. +* `colourValue` - grouping values for different colours. Can be numbers or characters. * `colourDomain` - vector of all possible values for discrete colour scales or range of all possible colour values for the continuous ones. @@ -910,13 +1056,13 @@ You can read more about different properties * `globalColourScale` - whether or not to use one colour scale for all the layers. -* `symbol` - shape of each point. Must be one of `"Circle", "Cross", "Diamond", ` . +* `symbol` - shape of each point. Must be one of `"Circle"` , `"Cross"` , `"Diamond"` , `"Square"` , `"Star"` , `"Triangle"` , `"Wye"` . * `symbolValue` - grouping values for different symbols. * `symbolLegendTitle` - title for the symbol value. -* `stroke` - stroke colour for each element. Must be a colour name or hexidecimal code. +* `stroke` - stroke colour for each element. Must be a colour name or hexadecimal code. * `strokeWidth` - width of the strokes for each point. @@ -925,21 +1071,23 @@ You can read more about different properties * `logScaleX, logScaleY` - a base of logarithm for logarithmic scale transformation. If 0 or `FALSE` no transformation will be performed. -* `jitterX, jitterY` - amount of random variation to be added to the position of the points along one of the axes. 0 means no variation. 1 stands for distance between `x` and `x + 1` for linear scale, `x` and `b*x` for logarithmic scale ( `b` is a base of the logarithm), and between neighbouring ticks for categorical scale. +* `jitterX, jitterY` - amount of random variation to be added to the position of the points along one of the axes. 0 means no variation. 1 stands for distance between `x` and `x + 1` for linear scale, `x` and `b*x` for logarithmic scale ( `b` is a base of the logarithm), or between neighbouring ticks for categorical scale. -* `shiftX, shiftY` - shift for each poitn from its original position along one of the axes. 0 means no shift. 1 stands for distance between `x` and `x + 1` for linear scale, `x` and `b*x` for logarithmic scale ( `b` is a base of the logarithm), and between neighbouring ticks for categorical scale. +* `shiftX, shiftY` - shift for each point from its original position along one of the axes. 0 means no shift. 1 stands for distance between `x` and `x + 1` for linear scale, `x` and `b*x` for logarithmic scale ( `b` is a base of the logarithm), or between neighbouring ticks for categorical scale. * `layerDomainX, layerDomainY` - default axes ranges for the given layer. * `domainX, domainY` - default axes ranges for the entire chart. If not defined, is automatically set to include all layer domains. -* `contScaleX, consScaleY` - whether or not the axis should be continuous. +* `contScaleX, contScaleY` - whether or not the axis should be continuous. * `aspectRatio` - aspect ratio. * `axisTitleX, axisTitleY` - axes titles. -* `ticksRotateX, ticksRotateY` - degrees of angle to rotate ticks. Must be between 0 (horisontal ticks, default) and 90 (vertical ticks). +* `axisTitlePosX, axisTitlePosY` - position of axes titles. For each axis one can specify title position across or along the corresponding axis. Possible options are `"up"` (for title inside the plotting area) or `"down"` (outside the plottting area, under the axis), and `"start"` , `"middle"` , `"end"` . This property must be a string with one or two of the abovementioned options (e.g. `"middle down"` , `"start"` , etc.). + +* `ticksRotateX, ticksRotateY` - angle by which to rotate ticks (in degrees). Must be between 0 (horizontal ticks, default) and 90 (vertical ticks). * `ticksX, ticksY` - set of ticks for the axes. @@ -952,7 +1100,7 @@ You can read more about different properties * `on_mouseout` - function, to be called, when mouse moves out of one of the points. -* `on_marked` - function, to be called, when any of the points are selected (marked) or deselected. Use [`getMarked`](#getmarked) function to get the IDs of the currently marked points. +* `on_marked` - function, to be called, when any of the points are selected (marked) or deselected. Use [`getMarked`](#getmarked) function to get the IDs of the currently marked points. To mark points, select them with your mouse while holding the Shift key. Global chart settings @@ -965,7 +1113,7 @@ You can read more about different properties * `plotHeight` - height of the plotting area in pixels. -* `paddings` - paddings size in pixels. Must be a list with all the following fields: `"top", "bottom", "left", "right"` . +* `paddings` - padding sizes in pixels. Must be a list with all the following fields: `"top", "bottom", "left", "right"` . * `title` - title of the chart. @@ -975,43 +1123,67 @@ You can read more about different properties * `showLegend` - whether or not to show the legend. -* `showPanel` - whether of not to show the tools panel. +* `showPanel` - whether of not to show the instrument panel (grey triangle in the upper-left corner of the chart). -* `transitionDuration` - duration of the transtions between any two states of the chart. If 0, no animated transition is shown. It can be useful to turn the transition off, when lots of frequent changes happen to the chart. +* `transitionDuration` - duration of the transitions between any two states of the chart. If 0, no animated transition is shown. It can be useful to turn the transition off, when lots of frequent changes happen to the chart. ## Examples ```r -data("iris") -lc_scatter(dat(x = iris$Sepal.Length, -y = iris$Petal.Length, -colourValue = iris$Petal.Width, -symbolValue = iris$Species), -title = "Iris dataset", -axisTitleY = "Petal Length", -axisTitleX = "Sepal Length", -colourLegendTitle = "Petal Width", -symbolLegendTitle = "Species") - -lc_beeswarm(dat(x = iris$Species, -y = iris$Sepal.Length, -colourValue = iris$Sepal.Width), -title = "Iris dataset", -axisTitleY = "Sepal Length", -axisTitleX = "Species", -colourLegendTitle = "Sepal Width") +list("data(\"iris\")\n", "lc_scatter(dat(x = iris$Sepal.Length, \n", " y = iris$Petal.Length,\n", " colourValue = iris$Petal.Width,\n", " symbolValue = iris$Species),\n", " title = \"Iris dataset\",\n", " axisTitleY = \"Petal Length\",\n", " axisTitleX = \"Sepal Length\",\n", " colourLegendTitle = \"Petal Width\",\n", " symbolLegendTitle = \"Species\")\n", "\n", "lc_beeswarm(dat(x = iris$Species,\n", " y = iris$Sepal.Length,\n", + " colourValue = iris$Sepal.Width),\n", " title = \"Iris dataset\",\n", " axisTitleY = \"Sepal Length\",\n", " axisTitleX = \"Species\",\n", " colourLegendTitle = \"Sepal Width\")") ``` -# List all existing charts and layers +# `LCApp` + +LCApp class + + +## Alias + +`LCApp` + + +## Description + +Object of this class represents the entire linked-charts app. It stores all charts, client sessions and + local variables. You can create and manage interactive apps solely by creating new instances of this class and utilizing + their methods. There are no limitations on the number of apps simultaneously running in one R session. + However, it is also possible to create and manage app via the wrapper functions provided in this package. In this case an + instance of [`LCApp`](#lcapp) class is initialized and stored in the package's namespace. Therefore, only one app can be active simultaneously. + You can always retrieve the active app with the [`getPage`](#getpage) function. The `LCApp` class inherits from + the [`App`](#app) class of the `jrc` package. + + +## Methods + +list("\n", list(list(list("removeChart(chartId)")), list("\n", "Removes a chart with the given ID from the app. See also ", list(list("removeChart")), ".\n")), "\n", list(list(list("removeLayer(chartId, layerId)")), list("\n", "Removes a layer from a chart by their IDs. See also ", list(list("removeLayer")), ".\n")), "\n", list(list(list("setProperties(data, chartId, layerId = NULL)")), list("\n", "Changes or sets properties for a given chart and layer. For more information, please, check ", list( + list("setProperties")), ".\n")), "\n", list(list(list("updateCharts(chartId = NULL, layerId = NULL, updateOnly = NULL, sessionId = NULL)")), list("\n", "Updates charts or specific layers for one or multiple users. For more information on the arguments,\n", "please, check ", list(list("updateCharts")), ".\n")), "\n", list(list(list("chartEvent(d, chartId, layerId = \"main\", event, sessionId = NULL)")), list("\n", "Triggers a reaction to mouse event on a web page. Generally, this method is not supposed to be\n", + "called explicitly. It is called internally each time, client clicks or hovers over an interactive chart element.\n", "However, experienced users can use this method to simulate mouse events on the R side. For more information\n", "on the arguments, please, check ", list(list("chartEvent")), ".\n")), "\n", list(list(list("listCharts()")), list("\n", "Prints a list of all existing charts and their layers. See also ", list(list("listCharts")), ".\n")), "\n", list(list(list("getMarked(chartId = NULL, layerId = NULL, sessionId = NULL)")), + list("\n", "Returns a vector of indices of all currently marked elements of a certain chart and layer and from a given client.\n", "For more information, please, check ", list(list("getMarked")), ".\n")), "\n", list(list(list("mark(elements, chartId = NULL, layerId = NULL, preventEvent = TRUE, sessionId = NULL)")), list("\n", "Marks elements of a given chart and layer on one of the currently opened web pages. Please, check\n", list(list("mark")), " for more information on the arguments.\n")), + "\n", list(list(list("setChart(chartType, data, ..., place = NULL, chartId = NULL, layerId = NULL, [...])")), list("\n", "Adds a new chart (or replaces an existing one) to the app. This is the main method of the package, that\n", "allows to define any chart and all its properties. There are multiple wrappers for this method - one for each type of\n", "chart. Here is a full list:\n", list("\n", list(), list(list(list("lc_scatter"))), "\n", list(), list(list(list("lc_beeswarm"))), "\n", list(), + list(list(list("lc_line"))), "\n", list(), list(list(list("lc_path"))), "\n", list(), list(list(list("lc_ribbon"))), "\n", list(), list(list(list("lc_bars"))), "\n", list(), list(list(list("lc_hist"))), "\n", list(), list(list(list("lc_dens"))), "\n", list(), list(list(list("lc_heatmap"))), "\n", list(), list(list(list("lc_colourSlider"))), "\n", list(), list(list(list("lc_abLine"))), "\n", list(), list(list(list("lc_vLine"))), "\n", list(), list(list(list("lc_html"))), "\n", list(), list( + list(list("lc_input"))), "\n"), "\n", "You can check the wrapper functions for information about arguments and available properties. Compared to them, this\n", "method gets additional argument ", list("chartType"), ", which is always the same as the second part of the name of a\n", "corresponding wrapper function (", list("lc_`chartType`"), "). In all other aspects, wrapper functions and the ", list("setChart"), "\n", "method are the same.\n")), "\n", list(list(list("new(layout = NULL, beforeLoad = function(s) {}, afterLoad = function(s) {}, ...)")), + list("\n", "Creates new instance of class ", list("LCApp"), ". Most of its arguments are inherited from method ", list("new"), " of\n", "class ", list(list("App")), " from the ", list("jrc"), " package. There are only three arguments specific for the\n", list("LCApp"), " class. ", list("layout"), " sets a default\n", "layout for each new webpage (currently only tables of arbitrary size are supported).\n", list("beforeLoad"), " and ", list("afterLoad"), " replace ", list("onStart"), " from the ", + list(list("App")), "\n", "class. For more information, please, check ", list(list("openPage")), ".\n")), "\n") -* `listCharts` + +# `listCharts` + +List all existing charts and layers + + +## Alias + +`listCharts` ## Description `listCharts` prints a list of IDs of all existing charts and layers. + This function is wrapper around method `listCharts` of class [`LCApp`](#lcapp) . ## Usage @@ -1024,36 +1196,38 @@ listCharts() ## Examples ```r -noise <- rnorm(30) -x <- seq(-4, 4, length.out = 30) +list("noise <- rnorm(30)\n", "x <- seq(-4, 4, length.out = 30)\n", "\n", "lc_scatter(dat(x = x,\n", " y = sin(x) + noise,\n", " colourValue = noise), \n", " chartId = \"plot\", layerId = \"points\")\n", "lc_line(dat(x = x, y = sin(x)), chartId = \"plot\", addLayer = TRUE)\n", "lc_colourSlider(chart = \"plot\", layer = \"points\")\n", "\n", "listCharts()") +``` -lc_scatter(dat(x = x, -y = sin(x) + noise, -colourValue = noise), -id = "plot", layerId = "points") -lc_line(dat(x = x, y = sin(x)), id = "plot") -lc_colourSlider(chart = "plot", layer = "points") -listCharts() -``` +# `mark` + +Mark elements of a chart -# Mark elements of a chart +## Alias -* `mark` +`mark` ## Description `mark` selects a set of elements in a given chart. It is equivalent to - selecting elemnts interactively by drawing a rectangle with the mouse - while holding the `Shift` key. + selecting elements interactively by drawing a rectangle with the mouse + while holding the `Shift` key. This function is a wrapper of method `mark` of + class [`LCApp`](#lcapp) . ## Usage ```r -mark(elements, chartId = NULL, layerId = NULL, preventEvent = T) +mark( + elements, + chartId = NULL, + layerId = NULL, + preventEvent = TRUE, + sessionId = NULL +) ``` @@ -1064,52 +1238,49 @@ Argument |Description `elements` | numeric vector of indices of the elements to select. `chartId` | ID of the chart where to select elements (can be omitted if there is only one chart). `layerId` | ID of the layer where to select elements (can be omitted if the chart has only one layer). -`preventEvent` | if `TRUE` , `on_marked` function will not be called. +`preventEvent` | if `TRUE` , `on_marked` callback function will not be called. Can be used to prevent endless stacks of calls. +`sessionId` | An ID of the session for which to mark elements. Can be `NULL` if there is only one active session. Otherwise must be a valid session ID. Check [`Session`](#session) for more information on client sessions. If a call to this function was triggered from an opened web page, ID of the corresponding session will be used automatically. ## Examples ```r -data("iris") -openPage(F, layout = "table1x2") - -lc_scatter(dat( -x = iris$Sepal.Length, -y = iris$Petal.Length, -colourValue = iris$Species, -on_marked = function() { -mark(getMarked("A1"), "A2") -} -), "A1") - -lc_scatter(dat( -x = iris$Sepal.Width, -y = iris$Petal.Width, -colourValue = iris$Species, -on_marked = function() { -mark(getMarked("A2"), "A1") -} -), "A2") +list("data(\"iris\")\n", "openPage(FALSE, layout = \"table1x2\")\n", "\n", "#brushing example\n", "#Hold Shift pressed and select a group of point on one of the charts\n", "\n", "lc_scatter(dat(\n", " x = iris$Sepal.Length,\n", " y = iris$Petal.Length,\n", " colourValue = iris$Species,\n", " on_marked = function() {\n", " mark(getMarked(\"A1\"), \"A2\")\n", " }\n", "), \"A1\")\n", "\n", "lc_scatter(dat(\n", " x = iris$Sepal.Width,\n", " y = iris$Petal.Width,\n", " colourValue = iris$Species,\n", + " on_marked = function() {\n", " mark(getMarked(\"A2\"), \"A1\")\n", " }\n", "), \"A2\")") ``` -# Open a new empty page +# `openPage` + +Open a new empty page + + +## Alias -* `openPage` +`openPage` ## Description -`openPage` creates a server, establishes a websocket connection between it and the current - R session and loads linked-charts JS library with all the dependencies. If there is already an - opened page, it will be automatically closed. +`openPage` starts a server, establishes a web socket connection between it and the current + R session and loads linked-charts JS library with all the dependencies. This function initializes + an instance of class [`LCApp`](#lcapp) and stores it in the namespace of the package. If another + instance has already been stored (i.e. another app has been started with this function), the existing + app will be closed. ## Usage ```r -openPage(useViewer = T, rootDirectory = NULL, startPage = NULL, - layout = NULL) +openPage( + useViewer = TRUE, + rootDirectory = NULL, + startPage = NULL, + layout = NULL, + port = NULL, + browser = NULL, + ... +) ``` @@ -1117,35 +1288,100 @@ openPage(useViewer = T, rootDirectory = NULL, startPage = NULL, Argument |Description ------------- |---------------- -`useViewer` | If `TRUE` , the page will be opened in the RStudio Viewer. If `FALSE` a default web browser will be used. -`rootDirectory` | A path to the root directory of the server. If `rootDirectory` is not defined, the `http_root` in the package directory will be used as a root directory. -`startPage` | A path to the HTML file that should be opened, when the server is initialised. This can be an absolute path to a local file, or it can be relative from the `rootDirectory` or to the current R working directory. If `startPage` is not defined, this function opens an empty HTML page. The file must have .html extension. -`layout` | Adds one of the defaults layouts to the page. Currently, only tables of arbitrary size are supported. To add a table set this parameter to `tableNxM` , where `N` is the number of rows and `M` is the number of columns. Each cell will get an ID that consists of a letter (inticating the row) and a number (indicating the column) (e.g. `B3` is an ID of the second row and third column). +`useViewer` | If `TRUE` , a page will be opened in the RStudio Viewer. If `FALSE` , a default web browser will be used. +`rootDirectory` | A path to the root directory for the server. Any file, requested by the server will be searched for in this directory. If `rootDirectory` is not defined, the `http_root` in the package directory will be used as a root directory. +`startPage` | A path to an HTML file that should be used as a starting page of the app. It can be an absolute path to a local file, or it can be relative to the `rootDirectory` or to the current R working directory. If `startPage` is not defined, an empty page will be used. The file must have .html extension. +`layout` | Adds one of the defaults layouts to each new page. Currently, only tables of arbitrary size are supported. To add a table, this parameter must be equal to `"tableNxM"` , where `N` is the number of rows and `M` is the number of columns. Each cell will get an ID that consists of a letter (indicating the row) and a number (indicating the column) (e.g. `B3` is an ID of the second row and third column). +`port` | Defines which TCP port the server will listen to. If not defined, random available port will be used (see [`randomPort`](#randomport) ). +`browser` | A browser in which to open a new web page. If not defined, default browser will be used. For more information check [`browseURL`](#browseurl) . If this argument is specified, `useViewer` will be ignored. +`...` | Further arguments passed to [`openPage`](#openpage) . Check details for more information. + + +## Details + +Argument `onStart` of `jrc` [`openPage`](#openpage) function is replaced in `rlc` + with `beforeLoad` and `afterLoad` . The reason for that is when the page opens, `rlc` + has to put there all the existing charts. Different situations may require some code be loaded before or after + that happens. `beforeLoad` and `afterLoad` provide a way to define two callback functions, each + receiving a [`Session`](#session) object as an argument and is called once for each new page. + `beforeLoad` runs before anything else has happened, while `afterLoad` is called after all the + existing charts have been added to the page. + + This function initializes a new instance of class [`LCApp`](#lcapp) and wraps around methods + `startServer` and `openPage` of its parent class [`App`](#app) . + + +## Value + +A new instance of class [`LCApp`](#lcapp) . ## Examples ```r -openPage() +list("openPage()\n", "\n", "openPage(useViewer = FALSE, layout = \"table2x3\")") +``` + + +# `removeChart` -openPage(useViewer = F, layout = "table2x3") +Remove chart from the page + + +## Alias + +`removeChart` + + +## Description + +Removes an existing chart. Changes will be applied to all currently opened and future pages. + This function is a wrapper around method `removeChart` of + class [`LCApp`](#lcapp) . + + +## Usage + +```r +removeChart(chartId) ``` -# Remove cahrt from the page +## Arguments + +Argument |Description +------------- |---------------- +`chartId` | A vector of IDs of the charts to be removed. + + +## Examples + +```r +list("lc_scatter(dat(x = 1:10, y = 1:10 * 2), chartId = \"scatter\")\n", "removeChart(\"scatter\")") +``` + + +# `removeLayer` -* `removeChart` +Remove a layer from a chart + + +## Alias + +`removeLayer` ## Description -Removes an existing chart. +Removes a layer from an existing chart. Changes will be applied to all currently opened and future pages. + This function is a wrapper around method `removeLayer` of + class [`LCApp`](#lcapp) . ## Usage ```r -removeChart(id) +removeLayer(chartId, layerId) ``` @@ -1153,32 +1389,38 @@ removeChart(id) Argument |Description ------------- |---------------- -`id` | A vector of IDs of the charts to be removed. +`chartId` | ID of the chart from which to remove a layer. +`layerId` | ID of the layer to remove. ## Examples ```r -lc_scatter(dat(x = 1:10, y = 1:10 * 2), id = "scatter") -removeChart("scatter") +list("lc_scatter(dat(x = 1:10, y = 1:10 * 2), chartId = \"scatter\")\n", "lc_abLine(a = 2, b = 0, chartId = \"scatter\", addLayer = TRUE)\n", "removeLayer(\"scatter\", \"Layer1\")") ``` -# Set properties of the chart +# `setProperties` + +Set properties of the chart + + +## Alias -* `setProperties` +`setProperties` ## Description -Changes already defined properties or sets the new ones for an - existing chart. +Sets or resets properties for an + existing chart. Changes will be applied to all currently opened and future pages. + This function is a wrapper around method `setProperties` of class [`LCApp`](#lcapp) . ## Usage ```r -setProperties(data, id, layerId = NULL) +setProperties(data, chartId, layerId = NULL) ``` @@ -1186,40 +1428,38 @@ setProperties(data, id, layerId = NULL) Argument |Description ------------- |---------------- -`data` | Set of properties to be redefined for this layer or chart. Created by [`dat`](#dat) function. -`id` | ID of the chart, whose properties you want to redefine. -`layerId` | ID of the layer, whose properties you want to redefine. If the chart has a single layer or doesn't have layers, default value (which is NULL) can be used. +`data` | List of properties to be redefined for this layer or chart. Created by the [`dat`](#dat) function. +`chartId` | ID of the chart, for which to redefine properties. +`layerId` | ID of the layer, for which to redefine properties. If the chart has a single layer or doesn't have layers, default value (which is NULL) can be used. ## Examples ```r -data("iris") -lc_scatter(dat(x = iris$Sepal.Length, y = iris$Sepal.Width), id = "irisScatter") -setProperties(dat(symbolValue = iris$Species, y = iris$Petal.Length), id = "irisScatter") -updateCharts("irisScatter") - -lc_line(dat(x = iris$Sepal.Length, y = iris$Petal.Length), id = "irisScatter", layerId = "line") -setProperties(dat(colour = "red"), id = "irisScatter", layerId = "line") -updateCharts("irisScatter") +list("data(\"iris\")\n", "lc_scatter(dat(x = iris$Sepal.Length, y = iris$Sepal.Width), chartId = \"irisScatter\")\n", "setProperties(dat(symbolValue = iris$Species, y = iris$Petal.Length), chartId = \"irisScatter\")\n", "updateCharts(\"irisScatter\")\n", "\n", "lc_line(dat(x = iris$Sepal.Length, y = iris$Petal.Length), chartId = \"irisScatter\", layerId = \"line\")\n", "setProperties(dat(colour = \"red\"), chartId = \"irisScatter\", layerId = \"line\")\n", "updateCharts(\"irisScatter\")") ``` -# Update a chart +# `updateCharts` -* `updateCharts` +Update a chart + + +## Alias + +`updateCharts` ## Description -`updateCharts` redraws a chart or a single layer of the chart to make it up - to date with the current state of the environment. +`updateCharts` redraws a chart or a single layer of a chart to make it up + to date with the current state of the environment variables. ## Usage ```r -updateCharts(id = NULL, layerId = NULL, updateOnly = NULL) +updateCharts(chartId = NULL, layerId = NULL, updateOnly = NULL) ``` @@ -1227,34 +1467,40 @@ updateCharts(id = NULL, layerId = NULL, updateOnly = NULL) Argument |Description ------------- |---------------- -`id` | An ID of the chart to be updated (or vector of IDs). If NULL then all the existing charts will be updated. -`layerId` | An ID of the layer to be updated (or vector of IDs). If NULL of the layers of the selected charts will be updated. To update only the selected layers of multiple charts the lengths of `id` and `layerId` must be the same. -`updateOnly` | To improve performance it may be useful to change only certain aspects of the chart (e.g. location of the points, colour of the heatmap cells, etc.). This argument can specify which part of chart to update. Possible options are `Elements` , `ElementPosition` , `ElementStyle` , `Axes` , `Labels` , `Cells` , `Texts` , `LabelPosition` , `CellPosition` , `TextPosition` , `LabelText` , `CellColour` , `TextValues` , `Canvas` , `Size` . See details for more information. +`chartId` | ID of the chart to be updated (or vector of IDs). If `NULL` , all the existing charts will be updated. +`layerId` | ID of the layer to be updated (or vector of IDs). If `NULL` , all the layers of the selected charts will be updated. To update only some layers of multiple charts the lengths of `chartId` and `layerId` must be the same. +`updateOnly` | To improve performance it may be useful to change only certain aspects of a chart (e.g. positions of points, colour of heatmap cells, etc.). This argument can specify which part of chart to update. Possible options are `Elements` , `ElementPosition` , `ElementStyle` , `Axes` , `Labels` , `Cells` , `Texts` , `LabelPosition` , `CellPosition` , `TextPosition` , `LabelText` , `CellColour` , `TextValues` , `Canvas` , `Size` . See details for more information. ## Details -Linked charts of the rlc package are based on the idea that variables - used to define the chart are not constant, but can change as a result of user's - actions. Each time the `updateCharts` is called, all the properties passed - via [`dat`](#dat) function are reevaluated and cahrt is changed in accordance with the +Linked charts of the rlc package are based on the idea that the variables that are + used to define a chart are not constant, but can change as a result of user's + actions. Each time the `updateCharts` function is called, all the properties that were set inside + the [`dat`](#dat) function are reevaluated and the chart is redrawn in accordance with the new state. + + If this function is called from the R session, changes will be applied + to all currently opened pages. If it is used as a part of any `rlc` callback, only the page + that triggered the call will be affected. + + This function is a wrapper around method `updateCharts` of class [`LCApp`](#lcapp) . ## Update Types -To improve performance you can update only a certain part of the chart (e.g. colours, +To improve performance you can update only a certain part of a chart (e.g. colours, size, etc.). This can be done by setting the `updateOnly` argument. Here are all possible values for this argument. These are valid for all the charts: -* `Size` changes the size of the chart (and consequently the location of all its elements). +* `Size` changes the size of the chart (and consequently position of all its elements). * `Title` changes the title of the chart. -* `Canvas` If number of elements is too high the charts switch to the canvas mode and istead of multiple SVG point or cells a single Canvas image is generated. This type of update redraws the Canvas image. It is not recommended to use this function. +* `Canvas` If number of elements is too high the charts switch to the canvas mode and instead of multiple SVG point or cells a single Canvas image is generated. This type of update redraws the Canvas image. It is not recommended to use this option, since it will be used automatically when necessary. These can be updated only in heatmaps ( [`lc_heatmap`](#lcheatmap) ): @@ -1278,7 +1524,7 @@ To improve performance you can update only a certain part of the chart (e.g. col These aspects are present in all the charts with axes. -* `Axes` updates axes of the chart and changes positions of all the elements accordingly. +* `Axes` updates axes of a chart and changes position of its elements (points, lines, etc.) accordingly. * `Elements` updates (add or removes) all the elements of the layer. @@ -1290,29 +1536,8 @@ To improve performance you can update only a certain part of the chart (e.g. col ## Examples ```r -data(iris) - -#store some properties in global variables -width <- 300 -height <- 300 -colour <- iris$Sepal.Width -#create a chart -lc_scatter(dat(x = iris$Sepal.Length, y = iris$Petal.Length, colourValue = colour, -width = width, height = height), id = "iris") - -#change the variables -height <- 400 -colour <- iris$Petal.Width - -#this will change colour of points and chart height -updateCharts("iris") -#this will change only height -updateCharts("iris", updateOnly = "Size") - -#add another property -setProperties(dat(symbolValue = iris$Species), "iris") -#this will change only colour and symbols -updateCharts("iris", updateOnly = "ElementStyle") +list("data(iris)\n", "\n", "#store some properties in global variables\n", "width <- 300\n", "height <- 300\n", "colour <- iris$Sepal.Width\n", "#create a chart\n", "lc_scatter(dat(x = iris$Sepal.Length, y = iris$Petal.Length, colourValue = colour,\n", " width = width, height = height), chartId = \"iris\")\n", "\n", "#change the variables\n", "height <- 400\n", "colour <- iris$Petal.Width\n", "\n", "#this will change colour of points and chart height\n", "updateCharts(\"iris\")\n", + "#this will change only height\n", "updateCharts(\"iris\", updateOnly = \"Size\")\n", "\n", "#add another property\n", "setProperties(dat(symbolValue = iris$Species), \"iris\")\n", "#this will change only colour and symbols\n", "updateCharts(\"iris\", updateOnly = \"ElementStyle\")") ``` diff --git a/cran-comments.md b/cran-comments.md index 9a926ed..a87650b 100644 --- a/cran-comments.md +++ b/cran-comments.md @@ -1,3 +1,22 @@ +## Resubmission + +This is a new version of the package that follows the update of `jrc` package. `rlc` can now utilize new functionality of +`jrc` and produce server app that can be used by multiple clients simultaneously. The package has also been restrunctured +so that the entire app is now contained within a single `R6` object, which inherits from `jrc::App`. + +## Reverse dependencies + +There are none. + +## Test environments +* local ubuntu 18.04 LST, R 3.6.2 +* win-builder: R-devel +* ubuntu 16.04.6 LTS, R-devel, R 3.6.2, R 3.5.3 (travis ci) + +## R CMD check results + +There were no ERRORS, WARNINGS or NOTES + ## Test environments * local ubuntu 18.04 LST, R 3.6.1 * win-builder: R-devel diff --git a/generateMd.R b/generateMd.R index cb72641..69a36ff 100644 --- a/generateMd.R +++ b/generateMd.R @@ -5,7 +5,7 @@ writeLines(c("---", "usePrism: true", "title: 'R/LinkedCharts API'", "hideTOC: 'true'", - "api: true", + "api: 'rlc'", "---"), "api.md") for(file in list.files("man")){ diff --git a/man/lc_bars.Rd b/man/lc_bars.Rd index 7fe77bc..f6621cd 100644 --- a/man/lc_bars.Rd +++ b/man/lc_bars.Rd @@ -78,7 +78,7 @@ is automatically set to include all layer domains. \item \code{axisTitleX, axisTitleY} - axes titles. \item \code{axisTitlePosX, axisTitlePosY} - position of axes titles. For each axis one can specify title position across or along the corresponding axis. Possible options are \code{"up"} (for title inside the plotting area) -or \code{"down"} (outside the plottting area, under the axis), and +or \code{"down"} (outside the plotting area, under the axis), and \code{"start"}, \code{"middle"}, \code{"end"}. This property must be a string with one or two of the abovementioned options (e.g. \code{"middle down"}, \code{"start"}, etc.). \item \code{ticksRotateX, ticksRotateY} - angle by which to rotate ticks (in degrees). Must be between diff --git a/man/lc_line.Rd b/man/lc_line.Rd index 112f110..48bce6c 100644 --- a/man/lc_line.Rd +++ b/man/lc_line.Rd @@ -151,7 +151,7 @@ is automatically set to include all layer domains. \item \code{axisTitleX, axisTitleY} - axes titles. \item \code{axisTitlePosX, axisTitlePosY} - position of axes titles. For each axis one can specify title position across or along the corresponding axis. Possible options are \code{"up"} (for title inside the plotting area) -or \code{"down"} (outside the plottting area, under the axis), and +or \code{"down"} (outside the plotting area, under the axis), and \code{"start"}, \code{"middle"}, \code{"end"}. This property must be a string with one or two of the abovementioned options (e.g. \code{"middle down"}, \code{"start"}, etc.). \item \code{ticksRotateX, ticksRotateY} - angle by which to rotate ticks (in degrees). Must be between @@ -212,7 +212,8 @@ lc_ribbon(dat(ymin = pred$fit - 1.96 * pred$se.fit, x = x, colour = "#555555"), chartId = "ribbonTest") lc_scatter(dat(x = x, y = y), size = 2, chartId = "ribbonTest", addLayer = TRUE) -lc_abLine(dat(a = fit$coefficients[2], b = fit$coefficients[1]), chartId = "ribbonTest", addLayer = TRUE) +lc_abLine(dat(a = fit$coefficients[2], b = fit$coefficients[1]), + chartId = "ribbonTest", addLayer = TRUE) lc_hLine(dat(h = seq(1, 9, 1), domainX = c(0, 10), domainY = c(0, 10)), chartId = "grid") lc_vLine(dat(v = seq(1, 9, 1)), chartId = "grid", addLayer = TRUE)} diff --git a/man/lc_scatter.Rd b/man/lc_scatter.Rd index 71e35c8..539af7b 100644 --- a/man/lc_scatter.Rd +++ b/man/lc_scatter.Rd @@ -114,7 +114,7 @@ is automatically set to include all layer domains. \item \code{axisTitleX, axisTitleY} - axes titles. \item \code{axisTitlePosX, axisTitlePosY} - position of axes titles. For each axis one can specify title position across or along the corresponding axis. Possible options are \code{"up"} (for title inside the plotting area) -or \code{"down"} (outside the plottting area, under the axis), and +or \code{"down"} (outside the plotting area, under the axis), and \code{"start"}, \code{"middle"}, \code{"end"}. This property must be a string with one or two of the abovementioned options (e.g. \code{"middle down"}, \code{"start"}, etc.). \item \code{ticksRotateX, ticksRotateY} - angle by which to rotate ticks (in degrees). Must be between diff --git a/man/setProperties.Rd b/man/setProperties.Rd index 3188a08..e37b361 100644 --- a/man/setProperties.Rd +++ b/man/setProperties.Rd @@ -26,7 +26,8 @@ lc_scatter(dat(x = iris$Sepal.Length, y = iris$Sepal.Width), chartId = "irisScat setProperties(dat(symbolValue = iris$Species, y = iris$Petal.Length), chartId = "irisScatter") updateCharts("irisScatter") -lc_line(dat(x = iris$Sepal.Length, y = iris$Petal.Length), chartId = "irisScatter", layerId = "line") +lc_line(dat(x = iris$Sepal.Length, y = iris$Petal.Length), chartId = "irisScatter", + layerId = "line") setProperties(dat(colour = "red"), chartId = "irisScatter", layerId = "line") updateCharts("irisScatter")}