NA
-GNU LESSER GENERAL PUBLIC LICENSE
+GNU LESSER GENERAL PUBLIC LICENSE
Version 2.1, February 1999
-Copyright (C) 1991, 1999 Free Software Foundation, Inc.
-51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
-
-Everyone is permitted to copy and distribute verbatim copies
-of this license document, but changing it is not allowed.
-
-[This is the first released version of the Lesser GPL. It also counts
- as the successor of the GNU Library Public License, version 2, hence
- the version number 2.1.]Copyright (C) 1991, 1999 Free Software Foundation, Inc.
+51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
+
+Everyone is permitted to copy and distribute verbatim copies
+of this license document, but changing it is not allowed.
+
+[This is the first released version of the Lesser GPL. It also counts
+ as the successor of the GNU Library Public License, version 2, hence
+ the version number 2.1.]-Preamble
+Preamble
The licenses for most software are designed to take away your freedom to share and change it. By contrast, the GNU General Public Licenses are intended to guarantee your freedom to share and change free software–to make sure the software is free for all its users.
This license, the Lesser General Public License, applies to some specially designated software packages–typically libraries–of the Free Software Foundation and other authors who decide to use it. You can use it too, but we suggest you first think carefully about whether this license or the ordinary General Public License is the better strategy to use in any particular case, based on the explanations below.
When we speak of free software, we are referring to freedom of use, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for this service if you wish); that you receive source code or can get it if you want it; that you can change the software and use pieces of it in new free programs; and that you are informed that you can do these things.
@@ -156,9 +85,8 @@Although the Lesser General Public License is Less protective of the users’ freedom, it does ensure that the user of a program that is linked with the Library has the freedom and the wherewithal to run that program using a modified version of the Library.
The precise terms and conditions for copying, distribution and modification follow. Pay close attention to the difference between a “work based on the library” and a “work that uses the library”. The former contains code derived from the library, whereas the latter must be combined with the library in order to run.
-TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
+TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
0. This License Agreement applies to any software library or other program which contains a notice placed by the copyright holder or other authorized party saying it may be distributed under the terms of this Lesser General Public License (also called “this License”). Each licensee is addressed as “you”.
A “library” means a collection of software functions and/or data prepared so as to be conveniently linked with application programs (which use some of those functions and data) to form executables.
The “Library”, below, refers to any such software library or work which has been distributed under these terms. A “work based on the Library” means either the Library or any derivative work under copyright law: that is to say, a work containing the Library or a portion of it, either verbatim or with modifications and/or translated straightforwardly into another language. (Hereinafter, translation is included without limitation in the term “modification”.)
@@ -167,16 +95,14 @@1. You may copy and distribute verbatim copies of the Library’s complete source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice and disclaimer of warranty; keep intact all the notices that refer to this License and to the absence of any warranty; and distribute a copy of this License along with the Library.
You may charge a fee for the physical act of transferring a copy, and you may at your option offer warranty protection in exchange for a fee.
2. You may modify your copy or copies of the Library or any portion of it, thus forming a work based on the Library, and copy and distribute such modifications or work under the terms of Section 1 above, provided that you also meet all of these conditions:
--
-
a) The modified work must itself be a software library.
+a) The modified work must itself be a software library.
b) You must cause the files modified to carry prominent notices stating that you changed the files and the date of any change.
c) You must cause the whole of the work to be licensed at no charge to all third parties under the terms of this License.
-
d) If a facility in the modified Library refers to a function or a table of data to be supplied by an application program that uses the facility, other than as an argument passed when the facility is invoked, then you must make a good faith effort to ensure that, in the event an application does not supply such function or table, the facility still operates, and performs whatever part of its purpose remains meaningful.
(For example, a function in a library to compute square roots has a purpose that is entirely well-defined independent of the application. Therefore, Subsection 2d requires that any application-supplied function or table used by this function must be optional: if the application does not supply it, the square root function must still compute square roots.)
-
These requirements apply to the modified work as a whole. If identifiable sections of that work are not derived from the Library, and can be reasonably considered independent and separate works in themselves, then this License, and its terms, do not apply to those sections when you distribute them as separate works. But when you distribute the same sections as part of a whole which is a work based on the Library, the distribution of the whole must be on the terms of this License, whose permissions for other licensees extend to the entire whole, and thus to each and every part regardless of who wrote it.
+These requirements apply to the modified work as a whole. If identifiable sections of that work are not derived from the Library, and can be reasonably considered independent and separate works in themselves, then this License, and its terms, do not apply to those sections when you distribute them as separate works. But when you distribute the same sections as part of a whole which is a work based on the Library, the distribution of the whole must be on the terms of this License, whose permissions for other licensees extend to the entire whole, and thus to each and every part regardless of who wrote it.
Thus, it is not the intent of this section to claim rights or contest your rights to work written entirely by you; rather, the intent is to exercise the right to control the distribution of derivative or collective works based on the Library.
In addition, mere aggregation of another work not based on the Library with the Library (or with a work based on the Library) on a volume of a storage or distribution medium does not bring the other work under the scope of this License.
3. You may opt to apply the terms of the ordinary GNU General Public License instead of this License to a given copy of the Library. To do this, you must alter all the notices that refer to this License, so that they refer to the ordinary GNU General Public License, version 2, instead of to this License. (If a newer version than version 2 of the ordinary GNU General Public License has appeared, then you can specify that version instead if you wish.) Do not make any other change in these notices.
@@ -191,8 +117,7 @@Otherwise, if the work is a derivative of the Library, you may distribute the object code for the work under the terms of Section 6. Any executables containing that work also fall under Section 6, whether or not they are linked directly with the Library itself.
6. As an exception to the Sections above, you may also combine or link a “work that uses the Library” with the Library to produce a work containing portions of the Library, and distribute that work under terms of your choice, provided that the terms permit modification of the work for the customer’s own use and reverse engineering for debugging such modifications.
You must give prominent notice with each copy of the work that the Library is used in it and that the Library and its use are covered by this License. You must supply a copy of this License. If the work during execution displays copyright notices, you must include the copyright notice for the Library among them, as well as a reference directing the user to the copy of this License. Also, you must do one of these things:
--
-
-
+
- a) Accompany the work with the complete corresponding machine-readable source code for the Library including whatever changes were used in the work (which must be distributed under Sections 1 and 2 above); and, if the work is an executable linked with the Library, with the complete machine-readable “work that uses the Library”, as object code and/or source code, so that the user can modify the Library and then relink to produce a modified executable containing the modified Library. (It is understood that the user who changes the contents of definitions files in the Library will not necessarily be able to recompile the application to use the modified definitions.)
- b) Use a suitable shared library mechanism for linking with the Library. A suitable mechanism is one that (1) uses at run time a copy of the library already present on the user’s computer system, rather than copying library functions into the executable, and (2) will operate properly with a modified version of the library, if the user installs one, as long as the modified version is interface-compatible with the version that the work was made with. @@ -202,17 +127,14 @@
d) If distribution of the work is made by offering access to copy from a designated place, offer equivalent access to copy the above specified materials from the same place.
- e) Verify that the user has already received a copy of these materials or that you have already sent this user a copy. -
For an executable, the required form of the “work that uses the Library” must include any data and utility programs needed for reproducing the executable from it. However, as a special exception, the materials to be distributed need not include anything that is normally distributed (in either source or binary form) with the major components (compiler, kernel, and so on) of the operating system on which the executable runs, unless that component itself accompanies the executable.
+For an executable, the required form of the “work that uses the Library” must include any data and utility programs needed for reproducing the executable from it. However, as a special exception, the materials to be distributed need not include anything that is normally distributed (in either source or binary form) with the major components (compiler, kernel, and so on) of the operating system on which the executable runs, unless that component itself accompanies the executable.
It may happen that this requirement contradicts the license restrictions of other proprietary libraries that do not normally accompany the operating system. Such a contradiction means you cannot use both them and the Library together in an executable that you distribute.
7. You may place library facilities that are a work based on the Library side-by-side in a single library together with other library facilities not covered by this License, and distribute such a combined library, provided that the separate distribution of the work based on the Library and of the other library facilities is otherwise permitted, and provided that you do these two things:
--
-
-
+
- a) Accompany the combined library with a copy of the same work based on the Library, uncombined with any other library facilities. This must be distributed under the terms of the Sections above.
- b) Give prominent notice with the combined library of the fact that part of it is a work based on the Library, and explaining where to find the accompanying uncombined form of the same work. -
8. You may not copy, modify, sublicense, link with, or distribute the Library except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense, link with, or distribute the Library is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance.
+
8. You may not copy, modify, sublicense, link with, or distribute the Library except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense, link with, or distribute the Library is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance.
9. You are not required to accept this License, since you have not signed it. However, nothing else grants you permission to modify or distribute the Library or its derivative works. These actions are prohibited by law if you do not accept this License. Therefore, by modifying or distributing the Library (or any work based on the Library), you indicate your acceptance of this License to do so, and all its terms and conditions for copying, distributing or modifying the Library or works based on it.
10. Each time you redistribute the Library (or any work based on the Library), the recipient automatically receives a license from the original licensor to copy, distribute, link with or modify the Library subject to these terms and conditions. You may not impose any further restrictions on the recipients’ exercise of the rights granted herein. You are not responsible for enforcing compliance by third parties with this License.
11. If, as a consequence of a court judgment or allegation of patent infringement or for any other reason (not limited to patent issues), conditions are imposed on you (whether by court order, agreement or otherwise) that contradict the conditions of this License, they do not excuse you from the conditions of this License. If you cannot distribute so as to satisfy simultaneously your obligations under this License and any other pertinent obligations, then as a consequence you may not distribute the Library at all. For example, if a patent license would not permit royalty-free redistribution of the Library by all those who receive copies directly or indirectly through you, then the only way you could satisfy both it and this License would be to refrain entirely from distribution of the Library.
@@ -227,39 +149,37 @@15. BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE LIBRARY “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE LIBRARY IS WITH YOU. SHOULD THE LIBRARY PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
16. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
-END OF TERMS AND CONDITIONS
+ --How to Apply These Terms to Your New Libraries
+How to Apply These Terms to Your New Libraries
If you develop a new library, and you want it to be of the greatest possible use to the public, we recommend making it free software that everyone can redistribute and change. You can do so by permitting redistribution under these terms (or, alternatively, under the terms of the ordinary General Public License).
To apply these terms, attach the following notices to the library. It is safest to attach them to the start of each source file to most effectively convey the exclusion of warranty; and each file should have at least the “copyright” line and a pointer to where the full notice is found.
-one line to give the library's name and an idea of what it does.
-Copyright (C) year name of author
-
-This library is free software; you can redistribute it and/or
-modify it under the terms of the GNU Lesser General Public
-License as published by the Free Software Foundation; either
-version 2.1 of the License, or (at your option) any later version.
-
-This library is distributed in the hope that it will be useful,
-but WITHOUT ANY WARRANTY; without even the implied warranty of
-MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
-Lesser General Public License for more details.
-
-You should have received a copy of the GNU Lesser General Public
-License along with this library; if not, write to the Free Software
-Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USAone line to give the library's name and an idea of what it does.
+Copyright (C) year name of author
+
+This library is free software; you can redistribute it and/or
+modify it under the terms of the GNU Lesser General Public
+License as published by the Free Software Foundation; either
+version 2.1 of the License, or (at your option) any later version.
+
+This library is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+Lesser General Public License for more details.
+
+You should have received a copy of the GNU Lesser General Public
+License along with this library; if not, write to the Free Software
+Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USAAlso add information on how to contact you by electronic and paper mail.
You should also get your employer (if you work as a programmer) or your school, if any, to sign a “copyright disclaimer” for the library, if necessary. Here is a sample; alter the names:
-Yoyodyne, Inc., hereby disclaims all copyright interest in
-the library `Frob' (a library for tweaking knobs) written
-by James Random Hacker.
-
-signature of Ty Coon, 1 April 1990
-Ty Coon, President of ViceYoyodyne, Inc., hereby disclaims all copyright interest in
+the library `Frob' (a library for tweaking knobs) written
+by James Random Hacker.
+
+signature of Ty Coon, 1 April 1990
+Ty Coon, President of ViceThat’s all there is to it!
-
-
+
@@ -76,105 +72,135 @@
- +-
DataSHIELD Development with DSLite
- Source:vignettes/developing-with-dslite.Rmd+ Source:vignettes/developing-with-dslite.Rmddeveloping-with-dslite.Rmd--Introduction
-DSLite is a serverless DataSHIELD Interface (DSI) implementation which purpose is to mimic the behavior of a distant (virtualized or barebone) data repository server (see DSOpal for instance). The datasets that are being analyzed must be fully accessible in the local environment and then the non-disclosive constraint of the analysis is not relevant for DSLite: some DSLite functionalities allows to inspect what is under the hood of the DataSHIELD computation nodes, making it a perfect tool for DataSHIELD analysis package developers.
++-Introduction +
+DSLite is a serverless DataSHIELD Interface (DSI) +implementation which purpose is to mimic the behavior of a distant +(virtualized or barebone) data repository server (see DSOpal for instance). +The datasets that are being analyzed must be fully accessible in the +local environment and then the non-disclosive constraint of the analysis +is not relevant for DSLite: some DSLite functionalities allows to +inspect what is under the hood of the DataSHIELD computation nodes, +making it a perfect tool for DataSHIELD analysis package developers.
--Development Environment Setup
---DataSHIELD Packages
-Both client and server side packages must be installed in your local R session. The entry point is still the client side package and DSLite will automatically load the corresponding server side package on DataSHIELD aggregate and assignment functions call, based on the DataSHIELD configuration.
++Development Environment Setup +
++-DataSHIELD Packages +
+Both client and server side packages must be installed in your local +R session. The entry point is still the client side package and DSLite +will automatically load the corresponding server side package on +DataSHIELD aggregate and assignment functions call, based on the +DataSHIELD configuration.
--Test Datasets
-DSLite comes with a set of datasets that can be easily loaded. You can also provide your own to illustrate a specific data analysis function.
++-Test Datasets +
+DSLite comes with a set of datasets that can be easily loaded. You +can also provide your own to illustrate a specific data analysis +function.
---R Package Development Tools
-We recommend using the following tools to facilitate R package development:
++R Package Development Tools +
+We recommend using the following tools to facilitate R package +development:
- -devtools, the collection of package development tools, +devtools, +the collection of package development tools,
- -usethis, automate package and project setup tasks that are otherwise performed manually, +usethis, +automate package and project setup tasks that are otherwise performed +manually,
- -testthat, for unit testing, +testthat, +for unit testing,
- -roxygen2, for writing documentation in-line with code, +roxygen2, +for writing documentation in-line with code,
- -Rstudio, the R editor that integrates the tools mentioned above and more. +Rstudio, the R editor that +integrates the tools mentioned above and more.
--DataSHIELD Development Flow
++DataSHIELD Development Flow +
The typical development flow, using DSLite, is:
-
-
- Build and install your client and/or server side DataSHIELD packages. -
- Create a new DSLiteServer object instance, refering test datasets. Use or alter the default DataSHIELD configuration. +
- Build and install your client and/or server side DataSHIELD +packages. +
- Create a new DSLiteServer object instance, refering test datasets. +Use or alter the default DataSHIELD configuration.
- Test your DataSHIELD client/server functions.
- Debug DataSHIELD server nodes using DSLiteServer methods.
--DSLiteServer
-After your client and/or server side DataSHIELD packages have been built and installed, a new DSLiteServer object instance must be created.
-Some DSLiteServer methods can be used to verify or modify the DSLiteServer behaviour:
++-DSLiteServer +
+After your client and/or server side DataSHIELD packages have been +built and installed, a new DSLiteServer object instance must be +created.
+Some DSLiteServer methods can be used to verify or modify the +DSLiteServer behaviour:
DSLiteServer$strict()DSLiteServer$home()
See the R documentation of the DSLiteServer class for details.
As an example:
--library(DSLite) +
-+
library(DSLite) # prepare test data in a light DS server -data("CNSIM1") -data("CNSIM2") -data("CNSIM3") -dslite.server <- newDSLiteServer(tables=list(CNSIM1=CNSIM1, CNSIM2=CNSIM2, CNSIM3=CNSIM3)) +data("CNSIM1") +data("CNSIM2") +data("CNSIM3") +dslite.server <- newDSLiteServer(tables=list(CNSIM1=CNSIM1, CNSIM2=CNSIM2, CNSIM3=CNSIM3)) # load corresponding DataSHIELD login data -data("logindata.dslite.cnsim") -The previous example can be simplified using the set-up functions based on the provided test datasets:
- +The previous example can be simplified using the set-up functions +based on the provided test datasets:
++logindata.dslite.cnsim <- setupCNSIMTest()+
library(DSLite) # load CNSIM test data -logindata.dslite.cnsim <- setupCNSIMTest() ---DataSHIELD Configuration
-The DataSHIELD configuration (aggregate and assign functions, R options) is automatically discovered by inspecting the R packages installed and having some DataSHIELD settings defined, either in their
+DESCRIPTIONfile or in aDATASHIELDfile.+-DataSHIELD Configuration +
+The DataSHIELD configuration (aggregate and assign functions, R +options) is automatically discovered by inspecting the R packages +installed and having some DataSHIELD settings defined, either in their +
DESCRIPTIONfile or in aDATASHIELDfile.This default configuration extracting function is:
---DSLite::defaultDSConfiguration() -
The list of the DataSHIELD R packages to be inspected (or excluded) when building the default configuration can be specified as parameters of
-defaultDSConfiguration().The DataSHIELD configuration can be specified at DSLiteServer creation time or afterwards with some DSLiteServer methods that can be used to verify or modify the DSLiteServer configuration:
+++
DSLite::defaultDSConfiguration()The list of the DataSHIELD R packages to be inspected (or excluded) +when building the default configuration can be specified as parameters +of
+defaultDSConfiguration().The DataSHIELD configuration can be specified at DSLiteServer +creation time or afterwards with some DSLiteServer methods that can be +used to verify or modify the DSLiteServer configuration:
DSLiteServer$config()DSLiteServer$aggregateMethods()
@@ -186,71 +212,95 @@
See the R documentation of the DSLiteServer class for details.
As an example:
-+-# verify configuration -dslite.server$config() -
+
# verify configuration +dslite.server$config()--DataSHIELD Sessions
-The following figure illustrates a setup where a single DSLiteServer holds several data frames and is used by two different DataSHIELD Connection (DSConnection) objects. All these objects live in the same R environment (usually the Global Environment). The “server” is responsible for managing DataSHIELD sessions that are implemented as distinct R environments inside of which R symbols are assigned and R functions are evaluated. Using the R environment paradigm ensures that the different DataSHIELD execution context (client and servers) are contained and exclusive from each other.
++-DataSHIELD Sessions +
+The following figure illustrates a setup where a single DSLiteServer +holds several data frames and is used by two different DataSHIELD +Connection (DSConnection) objects. All +these objects live in the same R environment (usually the Global +Environment). The “server” is responsible for managing DataSHIELD +sessions that are implemented as distinct R environments inside of which +R symbols are assigned and R functions are evaluated. Using the R environment +paradigm ensures that the different DataSHIELD execution context (client +and servers) are contained and exclusive from each other.
-
DSLite architecture
After performing the login DataSHIELD phase, the DSLiteServer holds the different DataSHIELD server side sessions, i.e. R environments identified by an ID. These IDs are also stored within the DataSHIELD connection objects that are the result of the
-datashield.login()call. The folllowing example shows how to access these session IDs:-# datashield logins and assignments -conns <- datashield.login(logindata.dslite.cnsim, assign=TRUE) +
After performing the login DataSHIELD phase, the DSLiteServer holds +the different DataSHIELD server side sessions, i.e. R environments +identified by an ID. These IDs are also stored within the DataSHIELD +connection objects that are the result of the +
+datashield.login()call. The folllowing example shows how +to access these session IDs:+dslite.server$hasSession(conns$sim1@sid)+
# datashield logins and assignments +conns <- datashield.login(logindata.dslite.cnsim, assign=TRUE) # get the session ID of "sim1" node connection object -conns$sim1@sid +conns$sim1@sid # the same ID is in the DSLiteServer -dslite.server$hasSession(conns$sim1@sid) ---Debugging
-Thanks to the DSLiteServer capability to have its configuration modified at any time, it is possible to add some debugging functions without polluting in the DataSHIELD package you are developping.
-For instance, this code adds an aggregate function
-print():-# add a print method to configuration -dslite.server$aggregateMethod("print", function(x){ print(x) }) +
+-Debugging +
+Thanks to the DSLiteServer capability to have its configuration +modified at any time, it is possible to add some debugging functions +without polluting in the DataSHIELD package you are developping.
+For instance, this code adds an aggregate function +
+print():-+
# add a print method to configuration +dslite.server$aggregateMethod("print", function(x){ print(x) }) # and use it to print the D symbol -datashield.aggregate(conns, quote(print(D))) -Another option is to get a symbol value from the server into the client environment. This can be very helpful for complex data structures. The following example illustrates usage of a shortcut function that iterates over all the connection objects and get the corresponding symbol value:
-+-# get data represented by symbol D for each DataSHIELD connection -data <- getDSLiteData(conns, "D") +datashield.aggregate(conns, quote(print(D)))
Another option is to get a symbol value from the server into the +client environment. This can be very helpful for complex data +structures. The following example illustrates usage of a shortcut +function that iterates over all the connection objects and get the +corresponding symbol value:
+-+
# get data represented by symbol D for each DataSHIELD connection +data <- getDSLiteData(conns, "D") # get data represented by symbol D from a specific DataSHIELD connection -data1 <- getDSLiteData(conns$sim1, "D") ----Limitations
---Function Parameters Parser
-The main difference with a regular DSI implementation (such as the one of DSOpal) is that the arguments of the DataSHIELD functional calls are not parsed in DSLite. The only R language element that is inspected and handled is the name of the functions, that are replaced by the ones defined in the DataSHIELD configuration.
-For instance the following expression, which includes a function call in the formula, is valid for the DSLiteServer but not for Opal:
---someregression(D$height ~ D$diameter + poly(D$length,3,raw=TRUE)) -
As a consequence, DataSHIELD R package development can take advantage of DSLite flexibility for speeding development but will never replace testing on a regular DataSHIELD infrastructure using DSOpal.
+data1 <- getDSLiteData(conns$sim1, "D")-@@ -267,11 +317,13 @@-Server Side Environments
-For each of the DataSHIELD node, the server side code is evaluated within an environment that has no parent, i.e. detached from the global environment where the client code is executed. Some R functions have a parameter that allows to specify to which environment they apply, for instance
-assign(),get(),eval(),as.formula(), etc. Theirenv(orenvir) parameter default value isparent.frame()which is the global environment when executed in Opal’s R server, because it is the parent frame of the package’s namespace where the function is defined. In DSLiteServer, the parent frame must be the environment where the server code is evaluated. In order to be consistent between these two execution contexts (Opal R server and DSLiteServer), you must specify theenv(orenvir) value explicitly to beparent.frame(), which is the parent frame of the block being executed (either the global environment in Opal context, or the environment defined in DSLiteServer).Example of a valid server side piece of code that assigns a value to a symbol in the DataSHIELD server’s environment (being the Opal R server’s global environment or a DSLiteServer’s environment):
---base::assign(x = "D", value = someValue, envir = parent.frame()) -
See also the Advanced R - Environments documentation to learn more about environments.
++Limitations +
++Server Side Environments +
+For each of the DataSHIELD node, the server side code is evaluated +within an environment that has no parent, i.e. detached from the global +environment where the client code is executed. Some R functions have a +parameter that allows to specify to which environment they apply, for +instance
+assign(),get(),eval(), +as.formula(), etc. Theirenv(or +envir) parameter default value is +parent.frame()which is the global environment when +executed in Opal’s R server, because it is the parent frame of the +package’s namespace where the function is defined. In DSLiteServer, the +parent frame must be the environment where the server code is evaluated. +In order to be consistent between these two execution contexts (Opal R +server and DSLiteServer), you must specify theenv(or +envir) value explicitly to beparent.frame(), +which is the parent frame of the block being executed (either the global +environment in Opal context, or the environment defined in +DSLiteServer).Example of a valid server side piece of code that assigns a value to +a symbol in the DataSHIELD server’s environment (being the Opal R +server’s global environment or a DSLiteServer’s environment):
+++
base::assign(x = "D", value = someValue, envir = parent.frame())See also the Advanced R - +Environments documentation to learn more about environments.
@@ -280,5 +332,7 @@
+ + diff --git a/docs/articles/index.html b/docs/articles/index.html index e95ec1a..e867a5b 100644 --- a/docs/articles/index.html +++ b/docs/articles/index.html @@ -1,66 +1,12 @@ - - - - - - - -
Articles • DSLite - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Articles • DSLite + + - - - - --- - + + diff --git a/docs/authors.html b/docs/authors.html index 0149d3f..d330da8 100644 --- a/docs/authors.html +++ b/docs/authors.html @@ -1,66 +1,12 @@ - - - - - - - -- - - -+-+Authors • DSLite - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Authors and Citation • DSLite - - + + - - - --- + - - -+-- - + + diff --git a/docs/index.html b/docs/index.html index 0dff62e..0630456 100644 --- a/docs/index.html +++ b/docs/index.html @@ -23,6 +23,8 @@ + +-@@ -135,22 +91,20 @@Authors
+ ++- + ++Citation
+ Source:DESCRIPTION+Marcon Y (2022). +DSLite: 'DataSHIELD' Implementation on Local Datasets. +https://github.com/datashield/DSLite/, +https://datashield.github.io/DSLite/, +https://www.datashield.org/, +https://doi.org/10.1093/ije/dyu188. +
+@Manual{, + title = {DSLite: 'DataSHIELD' Implementation on Local Datasets}, + author = {Yannick Marcon}, + year = {2022}, + note = {https://github.com/datashield/DSLite/, +https://datashield.github.io/DSLite/, +https://www.datashield.org/, +https://doi.org/10.1093/ije/dyu188}, +}Authors
-@@ -35,23 +37,17 @@-
-
+
@@ -82,19 +78,21 @@
-- ++ -
Serverless DataSHIELD Interface (DSI) implementation which purpose is to mimic the behavior of a distant (virtualized or barebone) data repository server (see DSOpal for instance). The datasets that are being analyzed are fully accessible in the local environment. The DataSHIELD configuration (set of allowed aggregation and assignment functions) is discovered at runtime by inspecting the DataSHIELD server-side R packages installed locally. This configuration can also be amended or provided explicitly.
-The DSLite “server” (see DSLiteServer) is a R6 class. An instance of this class will host the datasets to be analyzed and the DataSHIELD configuration and will perform the DataSHIELD operations in the context of a session (a contained R environment).
+Serverless DataSHIELD Interface (DSI) implementation which purpose is to mimic the behavior of a distant (virtualized or barebone) data repository server (see DSOpal for instance). The datasets that are being analyzed are fully accessible in the local environment. The DataSHIELD configuration (set of allowed aggregation and assignment functions) is discovered at runtime by inspecting the DataSHIELD server-side R packages installed locally. This configuration can also be amended or provided explicitly.
+The DSLite “server” (see DSLiteServer) is a R6 class. An instance of this class will host the datasets to be analyzed and the DataSHIELD configuration and will perform the DataSHIELD operations in the context of a session (a contained R environment).
DSLitecan be used to:- speed up development and testing cycle when developping new DataSHIELD functions (both at server and client side): no need to deploy a data repository infrastructure.
- allow DataSHIELD analysis with combined datasets, some of them being accessible remotely in secure data repositories, others being privatly accessible (in a governmental institution for instance).
The following figure illustrates a setup where a single DSLiteServer holds several data frames and is used by two different DataSHIELD Connection (DSConnection) objects. All these objects live in the same R environment (usually the Global Environment). The “server” is responsible for managing DataSHIELD sessions that are implemented as distinct R environments inside of which R symbols are assigned and R functions are evaluated. Using the R environment paradigm ensures that the different DataSHIELD execution context (client and servers) are contained and exclusive from each other.
-
+The following figure illustrates a setup where a single DSLiteServer holds several data frames and is used by two different DataSHIELD Connection (DSConnection) objects. All these objects live in the same R environment (usually the Global Environment). The “server” is responsible for managing DataSHIELD sessions that are implemented as distinct R environments inside of which R symbols are assigned and R functions are evaluated. Using the R environment paradigm ensures that the different DataSHIELD execution context (client and servers) are contained and exclusive from each other.
++DSLite architecture
+The minimum steps to follow for this kind of setup:
- make sure that both DataSHIELD client-side and server-side R packages are installed in your local R session, @@ -103,57 +101,64 @@
- prepare DataSHIELD logindata object where the
tableto assign is the name of one the data frames and theurlis the symbol that refers to theDSLiteServerobject, - perform DataSHIELD login and do analysis.
See usage examples.
-Article about DataSHIELD:
- +See usage examples.
+Article about DataSHIELD: * DataSHIELD: taking the analysis to the data, not the data to the analysis
