From b74d2cb4880821d9a3841a48e86f4ae2200458c9 Mon Sep 17 00:00:00 2001 From: Jan Meis Date: Tue, 26 Sep 2023 13:21:17 +0200 Subject: [PATCH] Fix CRAN issues. --- DESCRIPTION | 17 +- LICENSE | 2 - LICENSE.md | 357 ++++++++++++++++++-- NAMESPACE | 3 - R/analyze.R | 2 +- R/estimators.R | 15 +- R/evaluate_estimator.R | 11 +- R/fastmonoHFC.R | 1 + R/helper_functions.R | 38 ++- R/plot.R | 4 +- R/print.R | 4 +- R/priors.R | 8 +- R/reference_implementation.R | 22 +- R/twostagedesign_with_cache.R | 29 ++ man/EstimatorScore-class.Rd | 3 +- man/IntervalEstimator-class.Rd | 4 +- man/Normal.Rd | 18 + man/NormalPrior.Rd | 4 +- man/PValue-class.Rd | 3 +- man/PointEstimator-class.Rd | 4 +- man/Statistic-class.Rd | 4 + man/Student.Rd | 17 + man/UniformPrior.Rd | 4 +- man/adestr.Rd | 5 + man/evaluate_estimator-methods.Rd | 5 +- man/evaluate_estimator.Rd | 5 +- man/evaluate_scenarios_parallel.Rd | 2 +- man/get_example_design.Rd | 5 +- man/get_example_statistics.Rd | 37 +- man/get_statistics_from_paper.Rd | 7 +- man/plot-EstimatorScoreResult-method.Rd | 2 +- man/plot-EstimatorScoreResultList-method.Rd | 2 +- man/plot-list-method.Rd | 2 +- man/plot_p.Rd | 2 +- 34 files changed, 563 insertions(+), 85 deletions(-) delete mode 100644 LICENSE diff --git a/DESCRIPTION b/DESCRIPTION index 2454af9..4aec065 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,17 +1,24 @@ Package: adestr Type: Package -Title: Adaptive Design Estimation in R +Title: Estimation in optimal adaptive two-stage designs Version: 0.5.0 -Authors@R: c(person("Jan", "Meis", role = c("aut", "cre"), email="meis@imbi.uni-heidelberg.de", comment = c(ORCID = "0000-0001-5407-7220"))) +Authors@R:c(person("Jan", "Meis", role = c("aut", "cre"), email = "meis@imbi.uni-heidelberg.de", comment = c(ORCID = "0000-0001-5407-7220")), + person("Martin", "Maechler", role = c("cph"), email = "maechler@stat.math.ethz.ch", comment = c(ORCID = "0000-0002-8685-9910", "Original author of monoSpl.c (from the 'stats' package)."))) Description: Methods to evaluate the performance characteristics of various point and interval estimators for optimal adaptive two-stage designs. - Specifically, this package is written to work with trial designs created by the adoptr package + Specifically, this package is written to work with trial designs created by the 'adoptr' package (Kunzmann et al. (2021) ; Pilz et al. (2021) )). Apart from the a priori evaluation of performance characteristics, this package also allows for the evaluation of the implemented estimators on real datasets, and it implements methods to calculate p-values. -License: MIT + file LICENSE +License: GPL (>= 2) +Copyright: + This package contains a modified version of the monotonic spline functions from the + 'stats' package. Specifically, the code is containted in the files R/fastmonoHFC.R, + src/fastmonoHFC.c, modreg.h and monoSpl.c. The R Core team and Martin Maechler + are the copyright holders of the original code. + Jan Meis is the copyright holder of everything else. Encoding: UTF-8 LazyData: true VignetteBuilder: knitr @@ -60,5 +67,3 @@ Collate: 'print.R' URL: https://jan-imbi.github.io/adestr/ RdMacros: Rdpack - - diff --git a/LICENSE b/LICENSE deleted file mode 100644 index 8d4f133..0000000 --- a/LICENSE +++ /dev/null @@ -1,2 +0,0 @@ -YEAR: 2022 -COPYRIGHT HOLDER: Jan Meis diff --git a/LICENSE.md b/LICENSE.md index 7f0ede8..0daa041 100644 --- a/LICENSE.md +++ b/LICENSE.md @@ -1,21 +1,336 @@ -# MIT License - -Copyright (c) 2021 Jan Meis - -Permission is hereby granted, free of charge, to any person obtaining a copy -of this software and associated documentation files (the "Software"), to deal -in the Software without restriction, including without limitation the rights -to use, copy, modify, merge, publish, distribute, sublicense, and/or sell -copies of the Software, and to permit persons to whom the Software is -furnished to do so, subject to the following conditions: - -The above copyright notice and this permission notice shall be included in all -copies or substantial portions of the Software. - -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE -SOFTWARE. +GNU General Public License +========================== + +_Version 2, June 1991_ +_Copyright © 1989, 1991 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. + +### Preamble + +The licenses for most software are designed to take away your +freedom to share and change it. By contrast, the GNU General Public +License is intended to guarantee your freedom to share and change free +software--to make sure the software is free for all its users. This +General Public License applies to most of the Free Software +Foundation's software and to any other program whose authors commit to +using it. (Some other Free Software Foundation software is covered by +the GNU Lesser General Public License instead.) You can apply it to +your programs, too. + +When we speak of free software, we are referring to freedom, 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 or use pieces of it +in new free programs; and that you know you can do these things. + +To protect your rights, we need to make restrictions that forbid +anyone to deny you these rights or to ask you to surrender the rights. +These restrictions translate to certain responsibilities for you if you +distribute copies of the software, or if you modify it. + +For example, if you distribute copies of such a program, whether +gratis or for a fee, you must give the recipients all the rights that +you have. You must make sure that they, too, receive or can get the +source code. And you must show them these terms so they know their +rights. + +We protect your rights with two steps: **(1)** copyright the software, and +**(2)** offer you this license which gives you legal permission to copy, +distribute and/or modify the software. + +Also, for each author's protection and ours, we want to make certain +that everyone understands that there is no warranty for this free +software. If the software is modified by someone else and passed on, we +want its recipients to know that what they have is not the original, so +that any problems introduced by others will not reflect on the original +authors' reputations. + +Finally, any free program is threatened constantly by software +patents. We wish to avoid the danger that redistributors of a free +program will individually obtain patent licenses, in effect making the +program proprietary. To prevent this, we have made it clear that any +patent must be licensed for everyone's free use or not licensed at all. + +The precise terms and conditions for copying, distribution and +modification follow. + +### TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION + +**0.** This License applies to any program or other work which contains +a notice placed by the copyright holder saying it may be distributed +under the terms of this General Public License. The “Program”, below, +refers to any such program or work, and a “work based on the Program” +means either the Program or any derivative work under copyright law: +that is to say, a work containing the Program or a portion of it, +either verbatim or with modifications and/or translated into another +language. (Hereinafter, translation is included without limitation in +the term “modification”.) Each licensee is addressed as “you”. + +Activities other than copying, distribution and modification are not +covered by this License; they are outside its scope. The act of +running the Program is not restricted, and the output from the Program +is covered only if its contents constitute a work based on the +Program (independent of having been made by running the Program). +Whether that is true depends on what the Program does. + +**1.** You may copy and distribute verbatim copies of the Program's +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 give any other recipients of the Program a copy of this License +along with the Program. + +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 Program or any portion +of it, thus forming a work based on the Program, 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)** You must cause the modified files to carry prominent notices +stating that you changed the files and the date of any change. +* **b)** You must cause any work that you distribute or publish, that in +whole or in part contains or is derived from the Program or any +part thereof, to be licensed as a whole at no charge to all third +parties under the terms of this License. +* **c)** If the modified program normally reads commands interactively +when run, you must cause it, when started running for such +interactive use in the most ordinary way, to print or display an +announcement including an appropriate copyright notice and a +notice that there is no warranty (or else, saying that you provide +a warranty) and that users may redistribute the program under +these conditions, and telling the user how to view a copy of this +License. (Exception: if the Program itself is interactive but +does not normally print such an announcement, your work based on +the Program is not required to print an announcement.) + +These requirements apply to the modified work as a whole. If +identifiable sections of that work are not derived from the Program, +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 Program, 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 Program. + +In addition, mere aggregation of another work not based on the Program +with the Program (or with a work based on the Program) on a volume of +a storage or distribution medium does not bring the other work under +the scope of this License. + +**3.** You may copy and distribute the Program (or a work based on it, +under Section 2) in object code or executable form under the terms of +Sections 1 and 2 above provided that you also do one of the following: + +* **a)** Accompany it with the complete corresponding machine-readable +source code, which must be distributed under the terms of Sections +1 and 2 above on a medium customarily used for software interchange; or, +* **b)** Accompany it with a written offer, valid for at least three +years, to give any third party, for a charge no more than your +cost of physically performing source distribution, a complete +machine-readable copy of the corresponding source code, to be +distributed under the terms of Sections 1 and 2 above on a medium +customarily used for software interchange; or, +* **c)** Accompany it with the information you received as to the offer +to distribute corresponding source code. (This alternative is +allowed only for noncommercial distribution and only if you +received the program in object code or executable form with such +an offer, in accord with Subsection b above.) + +The source code for a work means the preferred form of the work for +making modifications to it. For an executable work, complete source +code means all the source code for all modules it contains, plus any +associated interface definition files, plus the scripts used to +control compilation and installation of the executable. However, as a +special exception, the source code 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. + +If distribution of executable or object code is made by offering +access to copy from a designated place, then offering equivalent +access to copy the source code from the same place counts as +distribution of the source code, even though third parties are not +compelled to copy the source along with the object code. + +**4.** You may not copy, modify, sublicense, or distribute the Program +except as expressly provided under this License. Any attempt +otherwise to copy, modify, sublicense or distribute the Program 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. + +**5.** 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 Program or its derivative works. These actions are +prohibited by law if you do not accept this License. Therefore, by +modifying or distributing the Program (or any work based on the +Program), you indicate your acceptance of this License to do so, and +all its terms and conditions for copying, distributing or modifying +the Program or works based on it. + +**6.** Each time you redistribute the Program (or any work based on the +Program), the recipient automatically receives a license from the +original licensor to copy, distribute or modify the Program 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 to +this License. + +**7.** 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 Program at all. For example, if a patent +license would not permit royalty-free redistribution of the Program 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 Program. + +If any portion of this section is held invalid or unenforceable under +any particular circumstance, the balance of the section is intended to +apply and the section as a whole is intended to apply in other +circumstances. + +It is not the purpose of this section to induce you to infringe any +patents or other property right claims or to contest validity of any +such claims; this section has the sole purpose of protecting the +integrity of the free software distribution system, which is +implemented by public license practices. Many people have made +generous contributions to the wide range of software distributed +through that system in reliance on consistent application of that +system; it is up to the author/donor to decide if he or she is willing +to distribute software through any other system and a licensee cannot +impose that choice. + +This section is intended to make thoroughly clear what is believed to +be a consequence of the rest of this License. + +**8.** If the distribution and/or use of the Program is restricted in +certain countries either by patents or by copyrighted interfaces, the +original copyright holder who places the Program under this License +may add an explicit geographical distribution limitation excluding +those countries, so that distribution is permitted only in or among +countries not thus excluded. In such case, this License incorporates +the limitation as if written in the body of this License. + +**9.** The Free Software Foundation may publish revised and/or new versions +of the General Public License from time to time. Such new versions will +be similar in spirit to the present version, but may differ in detail to +address new problems or concerns. + +Each version is given a distinguishing version number. If the Program +specifies a version number of this License which applies to it and “any +later version”, you have the option of following the terms and conditions +either of that version or of any later version published by the Free +Software Foundation. If the Program does not specify a version number of +this License, you may choose any version ever published by the Free Software +Foundation. + +**10.** If you wish to incorporate parts of the Program into other free +programs whose distribution conditions are different, write to the author +to ask for permission. For software which is copyrighted by the Free +Software Foundation, write to the Free Software Foundation; we sometimes +make exceptions for this. Our decision will be guided by the two goals +of preserving the free status of all derivatives of our free software and +of promoting the sharing and reuse of software generally. + +### NO WARRANTY + +**11.** BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY +FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN +OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES +PROVIDE THE PROGRAM “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 PROGRAM IS WITH YOU. SHOULD THE +PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, +REPAIR OR CORRECTION. + +**12.** 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 PROGRAM 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 PROGRAM (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 PROGRAM TO OPERATE WITH ANY OTHER +PROGRAMS), 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 Programs + +If you develop a new program, and you want it to be of the greatest +possible use to the public, the best way to achieve this is to make it +free software which everyone can redistribute and change under these terms. + +To do so, attach the following notices to the program. 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. + + + Copyright (C) + + This program is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 2 of the License, or + (at your option) any later version. + + This program 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 General Public License for more details. + + You should have received a copy of the GNU General Public License along + with this program; if not, write to the Free Software Foundation, Inc., + 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. + +Also add information on how to contact you by electronic and paper mail. + +If the program is interactive, make it output a short notice like this +when it starts in an interactive mode: + + Gnomovision version 69, Copyright (C) year name of author + Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'. + This is free software, and you are welcome to redistribute it + under certain conditions; type `show c' for details. + +The hypothetical commands `show w` and `show c` should show the appropriate +parts of the General Public License. Of course, the commands you use may +be called something other than `show w` and `show c`; they could even be +mouse-clicks or menu items--whatever suits your program. + +You should also get your employer (if you work as a programmer) or your +school, if any, to sign a “copyright disclaimer” for the program, if +necessary. Here is a sample; alter the names: + + Yoyodyne, Inc., hereby disclaims all copyright interest in the program + `Gnomovision' (which makes passes at compilers) written by James Hacker. + + , 1 April 1989 + Ty Coon, President of Vice + +This General Public License does not permit incorporating your program into +proprietary programs. If your program is a subroutine library, you may +consider it more useful to permit linking proprietary applications with the +library. If this is what you want to do, use the GNU Lesser General +Public License instead of this License. diff --git a/NAMESPACE b/NAMESPACE index 45a5145..cf52e38 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -1,7 +1,5 @@ # Generated by roxygen2: do not edit by hand -S3method("[",EstimatorScoreResultList) -S3method(format,EstimatorScoreResultList) export(AdaptivelyWeightedSampleMean) export(Bias) export(BiasReduced) @@ -56,7 +54,6 @@ export(evaluate_scenarios_parallel) export(get_example_design) export(get_example_statistics) export(get_stagewise_estimators) -export(get_statistics_from_paper) export(plot_p) exportClasses(EstimatorScore) exportClasses(IntervalEstimator) diff --git a/R/analyze.R b/R/analyze.R index 6c24f52..1f754b1 100644 --- a/R/analyze.R +++ b/R/analyze.R @@ -26,7 +26,7 @@ Results <- setClass("Results", slots = c(data ="data.frame", #' \code{\link{PValue}}. #' @inheritParams evaluate_estimator #' -#' @return \code{Results} object containing the values of the statistics +#' @returns \code{Results} object containing the values of the statistics #' when applied to data. #' @export #' diff --git a/R/estimators.R b/R/estimators.R index 230ef42..57fc129 100644 --- a/R/estimators.R +++ b/R/estimators.R @@ -14,6 +14,8 @@ #' #' #' @param label name of the statistic. Used in printing methods. +#' @returns An object of class \code{Statistic}. This class signals that +#' an object can be supplied to the \code{\link{analyze}} function. #' #' @export #' @rdname Statistic-class @@ -74,7 +76,9 @@ setClass("Estimator", contains = "Statistic") #' @param label name of the estimator. Used in printing methods. #' @seealso \code{\link{evaluate_estimator}} #' -#' @return an object of class \code{PointEstimator}. +#' @returns an object of class \code{PointEstimator}. This class signals that an +#' object can be supplied to the \code{\link{evaluate_estimator}} and the +#' \code{\link{analyze}} functions. #' #' @references #' \insertAllCited{} @@ -101,7 +105,8 @@ VirtualPointEstimator <- function() stop("Cannot create instance of class Virtua #' @param label name of the p-value. Used in printing methods. #' @seealso [plot_p] #' -#' @return An object of class \code{PValue}. +#' @returns an object of class \code{PValue}. This class signals that an +#' object can be supplied to the \code{\link{analyze}} function. #' @details #' The implemented p-values are: #' * \code{MLEOrderingPValue()} @@ -152,7 +157,9 @@ VirtualPValue <- function() stop("Cannot create instance of class VirtualPValue. #' @param label name of the estimator. Used in printing methods. #' @seealso \code{\link{evaluate_estimator}} #' -#' @return an object of class \code{IntervalEstimator}. +#' @return an object of class \code{IntervalEstimator}. This class signals that an +#' object can be supplied to the \code{\link{evaluate_estimator}} and the +#' \code{\link{analyze}} functions. #' #' @export #' @aliases ConfidenceInterval ConfidenceInterval-class @@ -206,7 +213,7 @@ VirtualIntervalEstimator <- function() stop("Cannot create instance of class Vir #' #' @inheritParams evaluate_estimator #' -#' @return a list with the conditional functional representations +#' @returns a list with the conditional functional representations #' (one for each stage where the trial might end) of the estimator or p-value. #' @export #' diff --git a/R/evaluate_estimator.R b/R/evaluate_estimator.R index 410eb97..34b6a96 100644 --- a/R/evaluate_estimator.R +++ b/R/evaluate_estimator.R @@ -32,7 +32,8 @@ #' @md #' @slot label name of the performance score. Used in printing methods. #' -#' @return an \code{EstimatorScore} object. +#' @returns an object of class \code{EstimatorScore}. This class signals that +#' an object can be used with the \code{\link{evaluate_estimator}} function. #' @export #' @aliases EstimatorScore #' @seealso \code{\link{evaluate_estimator}} @@ -132,7 +133,11 @@ setMethod("c", signature("EstimatorScoreResultList"), definition = #' @param early_efficacy_part include early efficacy part of integral. #' @param conditional_integral treat integral as a conditional integral. #' -#' @return \code{EstimatorScoreResult} object containing the performance characteristics of the estimator. +#' @return an object of class \code{EstimatorScoreResult} +#' containing the values of the evaluated \code{\link{EstimatorScore}} and +#' information about the setting for which they were calculated +#' (e.g. the \code{estimator}, \code{data_distribution}, \code{design}, \code{mu}, and \code{sigma}). +#' #' @seealso [EstimatorScore] #' @seealso [PointEstimator] [IntervalEstimator] #' @seealso \link[adestr:plot,EstimatorScoreResultList-method]{plot} @@ -1021,7 +1026,7 @@ setMethod("evaluate_estimator", signature("Centrality", "PointEstimator"), #' @param early_efficacy_part_lists a list of lists of `early_efficacy_part_lists` parameters. #' @param conditional_integral_lists a list of lists of `conditional_integral_lists` parameters. #' -#' @return list of data.frames containing the results for the respective scenarios. +#' @returns a list of data.frames containing the results for the respective scenarios. #' @export #' #' @examples diff --git a/R/fastmonoHFC.R b/R/fastmonoHFC.R index 72489ad..b219505 100644 --- a/R/fastmonoHFC.R +++ b/R/fastmonoHFC.R @@ -62,6 +62,7 @@ fastmonoH.FC_function <- function(x, y=NULL, ties = mean, extrapol = c("linear", dx <- x[-1L] - x[-nx] Sx <- dy/dx m <- c(Sx[1L], (Sx[-1L] + Sx[-n1])/2, Sx[n1]) + browser() m <- .Call(MymonoFC_m, m, Sx, PACKAGE = "adestr") p0 <- y[-length(y)] p1 <- y[-1L] diff --git a/R/helper_functions.R b/R/helper_functions.R index 50517c9..10abbc8 100644 --- a/R/helper_functions.R +++ b/R/helper_functions.R @@ -106,7 +106,11 @@ get_overall_svar_twoarm <- function(smean1, smean1T, svar1, smean2, smean2T, sva #' two-armed trials. #' @param label (optional) label to be assigned to the design. #' -#' @return an exmplary design of class \code{TwoStageDesign}. +#' @returns an exemplary design of class \code{TwoStageDesign}. This object +#' contains information about the sample size recalculation rule \code{n2}, the +#' futility and efficacy boundaries \code{c1f} and \code{c1e} and the +#' second-stage rejection boundary \code{c2}. +#' #' @export #' #' @examples @@ -170,11 +174,35 @@ get_example_design <- function(two_armed = FALSE, label = NULL) { } #' Generate a list of estimators and p-values to use in examples #' +#' This function generates a list of objects of class \code{\link{PointEstimator}}, +#' \code{\link{IntervalEstimator}}s, and \code{\link{PValue}}s to use in +#' examples of the \code{\link{analyze}} function. +#' +#' @details +#' ## Point estimators +#' The following \code{\link{PointEstimator}}s are included: +#' * \code{\link{SampleMean}} +#' * \code{\link{PseudoRaoBlackwell}} +#' * \code{\link{MedianUnbiasedLikelihoodRatioOrdering}} +#' * \code{\link{BiasReduced}} +#' +#' ## Confidence intervals +#' The following \code{\link{IntervalEstimator}}s are included: +#' * \code{\link{StagewiseCombinationFunctionOrderingCI}} +#' * \code{\link{LikelihoodRatioOrderingCI}} +#' +#' ## P-Values +#' The following \code{\link{PValue}}s are included: +#' * \code{\link{StagewiseCombinationFunctionOrderingPValue}} +#' * \code{\link{LikelihoodRatioOrderingPValue}} +#' @md +#' #' @param point_estimators logical indicating whether point estimators should be included in output list #' @param interval_estimators logical indicating whether interval estimators should be included in output list #' @param p_values logical indicating whether p-values should be included in output list #' -#' @return a list of estimators and pvalues. +#' @returns a list of \code{\link{PointEstimator}}s, \code{\link{IntervalEstimator}}s and +#' \code{\link{PValue}}. #' @export #' #' @inherit analyze examples @@ -194,14 +222,14 @@ get_example_statistics <- function(point_estimators = TRUE, return(ret) } -#' Generate a list of estimators and p-values to use in examples +#' Generate the list of estimators and p-values that were used in the paper #' #' @param point_estimators logical indicating whether point estimators should be included in output list #' @param interval_estimators logical indicating whether interval estimators should be included in output list #' @param p_values logical indicating whether p-values should be included in output list #' -#' @return a list of estimators and pvalues. -#' @export +#' @returns a list of \code{\link{PointEstimator}}s, \code{\link{IntervalEstimator}}s and +#' \code{\link{PValue}}. #' #' @inherit analyze examples get_statistics_from_paper <- function(point_estimators = TRUE, diff --git a/R/plot.R b/R/plot.R index 1ffee4d..215b1ab 100644 --- a/R/plot.R +++ b/R/plot.R @@ -11,7 +11,7 @@ #' @export #' @importFrom ggplot2 ggplot scale_x_continuous geom_line facet_wrap #' @importFrom latex2exp TeX -#' @return a ggplot2 object visualizing the score values. +#' @returns a \code{\link{ggplot2}} object visualizing the score values. #' @examples #' score_result1 <- evaluate_estimator( #' MSE(), @@ -89,7 +89,7 @@ setMethod("plot", signature = "list", definition = #' @param subdivisions number of subdivisions per axis for the grid of test statistic values. #' @param ... additional arguments handed down to ggplot #' -#' @return a ggplot2 object visualizing the p-values on a grid of possible test-statistic values. +#' @returns a \code{\link{ggplot2}} object visualizing the p-values on a grid of possible test-statistic values. #' #' @export #' @importFrom ggplot2 ggplot geom_tile geom_line geom_segment scale_color_manual scale_fill_gradient scale_x_continuous diff --git a/R/print.R b/R/print.R index dc846d2..30d6a6d 100644 --- a/R/print.R +++ b/R/print.R @@ -250,10 +250,8 @@ setMethod("toTeX", signature("NeymanPearsonOrderingPValue"), str }) -#' @export -format.EstimatorScoreResultList <- function(x, ...) rep("", length(x)) -#' @export +format.EstimatorScoreResultList <- function(x, ...) rep("", length(x)) `[.EstimatorScoreResultList` <- function(x, i){ class(x) <- class(x)[class(x)!="EstimatorScoreResultList"] x <- x[i] diff --git a/R/priors.R b/R/priors.R index 337c397..071a684 100644 --- a/R/priors.R +++ b/R/priors.R @@ -11,7 +11,9 @@ setClass("NormalPrior", contains = "Prior", slots = c(mu = "numeric", sigma = "n #' @param mu mean of prior distribution. #' @param sigma standard deviation of the prior distribution. #' -#' @return An object of class \code{NormalPrior}. +#' @returns an object of class \code{NormalPrior}. This object can be supplied +#' as the argument \code{mu} of the \code{\link{evaluate_estimator}} function +#' to calculate performance scores weighted by a prior. #' #' @export #' @@ -29,7 +31,9 @@ setClass("UniformPrior", contains = "Prior", slots = c(min = "numeric", max = "n #' @param min minimum of support interval. #' @param max maximum of support interval. #' -#' @return An object of class \code{UniformPrior}. +#' @returns an object of class \code{UniformPrior}. This object can be supplied +#' as the argument \code{mu} of the \code{\link{evaluate_estimator}} function +#' to calculate performance scores weighted by a prior. #' #' @export #' diff --git a/R/reference_implementation.R b/R/reference_implementation.R index ff255e1..ce1f545 100644 --- a/R/reference_implementation.R +++ b/R/reference_implementation.R @@ -19,25 +19,19 @@ x2 <- .z_to_x(z = z2, n = n2, mu0 = mu0, sigma = sigma) (n1 * x1 + n2 * x2) / (n1 + n2) } -.n2_extrapol <- function(design, x1) { +.n2_extrapol <- function(design, z1) { if (length(design@n2_pivots)>1){ - h <- (design@c1e - design@c1f) / 2 - return(stats::splinefun( - h * design@x1_norm_pivots + (h + design@c1f), - design@n2_pivots, - method = "monoH.FC" - )(x1)) + z_interval_length <- design@c1e - design@c1f + z_trafo <- design@c1f + z_interval_length/2 * (1 + design@x1_norm_pivots) + return(stats::splinefun(z_trafo, design@n2_pivots, method = "monoH.FC")(z1)) } else{ return(design@n2_pivots) } } -.c2_extrapol <- function(design, x1) { - h <- (design@c1e - design@c1f) / 2 - return(stats::splinefun( - h * design@x1_norm_pivots + (h + design@c1f), - design@c2_pivots, - method = "monoH.FC" - )(x1)) +.c2_extrapol <- function(design, z1) { + z_interval_length <- design@c1e - design@c1f + z_trafo <- design@c1f + z_interval_length/2 * (1 + design@x1_norm_pivots) + return(stats::splinefun(z_trafo, design@c2_pivots, method = "monoH.FC")(z1)) } ## The densities for integration. diff --git a/R/twostagedesign_with_cache.R b/R/twostagedesign_with_cache.R index 0b25aad..6101120 100644 --- a/R/twostagedesign_with_cache.R +++ b/R/twostagedesign_with_cache.R @@ -65,6 +65,21 @@ setClass("Normal", contains = "DataDistribution") #' @param two_armed (logical) determines whether one or two-armed trials are assumed. #' #' @export +#' @returns an object of class \code{Normal}. This object encodes the distributional +#' assumptions of the data for usage in the functions +#' \code{\link{evaluate_estimator}} and \code{\link{analyze}}. +#' @examples +#' evaluate_estimator( +#' score = MSE(), +#' estimator = SampleMean(), +#' data_distribution = Normal(FALSE), +#' design = get_example_design(), +#' mu = c(0, 0.3, 0.6), +#' sigma = 1, +#' exact = FALSE +#' ) +#' +#' Normal <- function(two_armed = TRUE) new("Normal", two_armed = two_armed) setClass("Student", contains = "DataDistribution") @@ -76,8 +91,22 @@ setClass("Student", contains = "DataDistribution") #' under the assumption of known variance. #' #' @param two_armed (logical) determines whether one or two-armed trials are assumed. +#' @returns an object of class \code{Student}. This object encodes the distributional +#' assumptions of the data for usage in the functions +#' \code{\link{evaluate_estimator}} and \code{\link{analyze}}. #' #' @export +#' @examples +#' evaluate_estimator( +#' score = MSE(), +#' estimator = SampleMean(), +#' data_distribution = Student(FALSE), +#' design = get_example_design(), +#' mu = c(0, 0.3, 0.6), +#' sigma = 1, +#' exact = FALSE +#' ) +#' Student <- function(two_armed = TRUE) new("Student", two_armed = two_armed) n1 <- function(design, round = FALSE) if (round) round(design@n1) else design@n1 ### end of remove ### diff --git a/man/EstimatorScore-class.Rd b/man/EstimatorScore-class.Rd index a861dea..f02ab0b 100644 --- a/man/EstimatorScore-class.Rd +++ b/man/EstimatorScore-class.Rd @@ -43,7 +43,8 @@ Centrality(interval = NULL) estimator should be evaluated.} } \value{ -an \code{EstimatorScore} object. +an object of class \code{EstimatorScore}. This class signals that +an object can be used with the \code{\link{evaluate_estimator}} function. } \description{ These classes encode various metrics which can be used to evaluate diff --git a/man/IntervalEstimator-class.Rd b/man/IntervalEstimator-class.Rd index b8cc217..3f4d8f4 100644 --- a/man/IntervalEstimator-class.Rd +++ b/man/IntervalEstimator-class.Rd @@ -49,7 +49,9 @@ NaiveCI(two_sided = TRUE) \item{mu1}{expected value of the normal distribution under the null hypothesis.} } \value{ -an object of class \code{IntervalEstimator}. +an object of class \code{IntervalEstimator}. This class signals that an +object can be supplied to the \code{\link{evaluate_estimator}} and the +\code{\link{analyze}} functions. } \description{ This is the parent class for all confidence intervals implemented in this package. diff --git a/man/Normal.Rd b/man/Normal.Rd index 677e10d..f80f3f3 100644 --- a/man/Normal.Rd +++ b/man/Normal.Rd @@ -9,9 +9,27 @@ Normal(two_armed = TRUE) \arguments{ \item{two_armed}{(logical) determines whether one or two-armed trials are assumed.} } +\value{ +an object of class \code{Normal}. This object encodes the distributional +assumptions of the data for usage in the functions +\code{\link{evaluate_estimator}} and \code{\link{analyze}}. +} \description{ This function creates an object representing the distributional assumptions of the data: normally distributed outcomes sample from a trial with one or two arms (depending on the value of the parameter \code{two_armed}), under the assumption of known variance. } +\examples{ +evaluate_estimator( + score = MSE(), + estimator = SampleMean(), + data_distribution = Normal(FALSE), + design = get_example_design(), + mu = c(0, 0.3, 0.6), + sigma = 1, + exact = FALSE +) + + +} diff --git a/man/NormalPrior.Rd b/man/NormalPrior.Rd index 56b2e87..5648ff6 100644 --- a/man/NormalPrior.Rd +++ b/man/NormalPrior.Rd @@ -12,7 +12,9 @@ NormalPrior(mu = 0, sigma = 1) \item{sigma}{standard deviation of the prior distribution.} } \value{ -An object of class \code{NormalPrior}. +an object of class \code{NormalPrior}. This object can be supplied +as the argument \code{mu} of the \code{\link{evaluate_estimator}} function +to calculate performance scores weighted by a prior. } \description{ Normal prior distribution for the parameter mu diff --git a/man/PValue-class.Rd b/man/PValue-class.Rd index 6b6f739..8b96dd2 100644 --- a/man/PValue-class.Rd +++ b/man/PValue-class.Rd @@ -44,7 +44,8 @@ NeymanPearsonOrderingPValue(mu0 = 0, mu1 = 0.4) \item{mu1}{expected value of the normal distribution under the null hypothesis.} } \value{ -An object of class \code{PValue}. +an object of class \code{PValue}. This class signals that an +object can be supplied to the \code{\link{analyze}} function. } \description{ This is the parent class for all p-values implemented in this package. diff --git a/man/PointEstimator-class.Rd b/man/PointEstimator-class.Rd index 093c5d5..f9fdd76 100644 --- a/man/PointEstimator-class.Rd +++ b/man/PointEstimator-class.Rd @@ -78,7 +78,9 @@ MedianUnbiasedNeymanPearsonOrdering(mu0 = 0, mu1 = 0.4) \item{mu1}{expected value of the normal distribution under the null hypothesis.} } \value{ -an object of class \code{PointEstimator}. +an object of class \code{PointEstimator}. This class signals that an +object can be supplied to the \code{\link{evaluate_estimator}} and the +\code{\link{analyze}} functions. } \description{ This is the parent class for all point estimators implemented in this package. diff --git a/man/Statistic-class.Rd b/man/Statistic-class.Rd index fe7ed16..7bd116b 100644 --- a/man/Statistic-class.Rd +++ b/man/Statistic-class.Rd @@ -10,6 +10,10 @@ \arguments{ \item{label}{name of the statistic. Used in printing methods.} } +\value{ +An object of class \code{Statistic}. This class signals that +an object can be supplied to the \code{\link{analyze}} function. +} \description{ The \code{\link{Statistic}} class is a parent class for the classes \code{\link{Estimator}} and \code{\link{PValue}}. The \code{\link{Estimator}} class is a parent diff --git a/man/Student.Rd b/man/Student.Rd index e35f8ae..d59fcd9 100644 --- a/man/Student.Rd +++ b/man/Student.Rd @@ -9,9 +9,26 @@ Student(two_armed = TRUE) \arguments{ \item{two_armed}{(logical) determines whether one or two-armed trials are assumed.} } +\value{ +an object of class \code{Student}. This object encodes the distributional +assumptions of the data for usage in the functions +\code{\link{evaluate_estimator}} and \code{\link{analyze}}. +} \description{ This function creates an object representing the distributional assumptions of the data: normally distributed outcomes sample from a trial with one or two arms (depending on the value of the parameter \code{two_armed}), under the assumption of known variance. } +\examples{ +evaluate_estimator( + score = MSE(), + estimator = SampleMean(), + data_distribution = Student(FALSE), + design = get_example_design(), + mu = c(0, 0.3, 0.6), + sigma = 1, + exact = FALSE +) + +} diff --git a/man/UniformPrior.Rd b/man/UniformPrior.Rd index 9da4575..069c004 100644 --- a/man/UniformPrior.Rd +++ b/man/UniformPrior.Rd @@ -12,7 +12,9 @@ UniformPrior(min = -1, max = 1) \item{max}{maximum of support interval.} } \value{ -An object of class \code{UniformPrior}. +an object of class \code{UniformPrior}. This object can be supplied +as the argument \code{mu} of the \code{\link{evaluate_estimator}} function +to calculate performance scores weighted by a prior. } \description{ Uniform prior distribution for the parameter mu diff --git a/man/adestr.Rd b/man/adestr.Rd index f5e13ea..11e09c2 100644 --- a/man/adestr.Rd +++ b/man/adestr.Rd @@ -34,4 +34,9 @@ to calculate \link[adestr:PValue]{p-values}. \author{ \strong{Maintainer}: Jan Meis \email{meis@imbi.uni-heidelberg.de} (\href{https://orcid.org/0000-0001-5407-7220}{ORCID}) +Other contributors: +\itemize{ + \item Martin Maechler \email{maechler@stat.math.ethz.ch} (\href{https://orcid.org/0000-0002-8685-9910}{ORCID}) (Original author of monoSpl.c (from the 'stats' package).) [copyright holder] +} + } diff --git a/man/evaluate_estimator-methods.Rd b/man/evaluate_estimator-methods.Rd index db368b7..a7a842e 100644 --- a/man/evaluate_estimator-methods.Rd +++ b/man/evaluate_estimator-methods.Rd @@ -325,7 +325,10 @@ with the full sampling distribution in a two-armed trial.} \item{conditional_integral}{treat integral as a conditional integral.} } \value{ -\code{EstimatorScoreResult} object containing the performance characteristics of the estimator. +an object of class \code{EstimatorScoreResult} +containing the values of the evaluated \code{\link{EstimatorScore}} and +information about the setting for which they were calculated +(e.g. the \code{estimator}, \code{data_distribution}, \code{design}, \code{mu}, and \code{sigma}). } \description{ This function evaluates an \code{\link{EstimatorScore}} for a \code{\link{PointEstimator}} diff --git a/man/evaluate_estimator.Rd b/man/evaluate_estimator.Rd index 08ca873..014b567 100644 --- a/man/evaluate_estimator.Rd +++ b/man/evaluate_estimator.Rd @@ -60,7 +60,10 @@ with the full sampling distribution in a two-armed trial.} \item{conditional_integral}{treat integral as a conditional integral.} } \value{ -\code{EstimatorScoreResult} object containing the performance characteristics of the estimator. +an object of class \code{EstimatorScoreResult} +containing the values of the evaluated \code{\link{EstimatorScore}} and +information about the setting for which they were calculated +(e.g. the \code{estimator}, \code{data_distribution}, \code{design}, \code{mu}, and \code{sigma}). } \description{ This function evaluates an \code{\link{EstimatorScore}} for a \code{\link{PointEstimator}} diff --git a/man/evaluate_scenarios_parallel.Rd b/man/evaluate_scenarios_parallel.Rd index 8b30e9b..85334c3 100644 --- a/man/evaluate_scenarios_parallel.Rd +++ b/man/evaluate_scenarios_parallel.Rd @@ -57,7 +57,7 @@ evaluate_scenarios_parallel( \item{conditional_integral_lists}{a list of lists of `conditional_integral_lists` parameters.} } \value{ -list of data.frames containing the results for the respective scenarios. +a list of data.frames containing the results for the respective scenarios. } \description{ This function takes a list of lists of scores, a list of lists of estimators, diff --git a/man/get_example_design.Rd b/man/get_example_design.Rd index 88e68f7..a7a48a6 100644 --- a/man/get_example_design.Rd +++ b/man/get_example_design.Rd @@ -13,7 +13,10 @@ two-armed trials.} \item{label}{(optional) label to be assigned to the design.} } \value{ -an exmplary design of class \code{TwoStageDesign}. +an exemplary design of class \code{TwoStageDesign}. This object +contains information about the sample size recalculation rule \code{n2}, the +futility and efficacy boundaries \code{c1f} and \code{c1e} and the +second-stage rejection boundary \code{c2}. } \description{ The design was optimized to minimize the expected sample size diff --git a/man/get_example_statistics.Rd b/man/get_example_statistics.Rd index 9ac35df..2b63e1a 100644 --- a/man/get_example_statistics.Rd +++ b/man/get_example_statistics.Rd @@ -18,10 +18,43 @@ get_example_statistics( \item{p_values}{logical indicating whether p-values should be included in output list} } \value{ -a list of estimators and pvalues. +a list of \code{\link{PointEstimator}}s, \code{\link{IntervalEstimator}}s and +\code{\link{PValue}}. } \description{ -Generate a list of estimators and p-values to use in examples +This function generates a list of objects of class \code{\link{PointEstimator}}, +\code{\link{IntervalEstimator}}s, and \code{\link{PValue}}s to use in +examples of the \code{\link{analyze}} function. +} +\details{ +\subsection{Point estimators}{ + +The following \code{\link{PointEstimator}}s are included: +\itemize{ +\item \code{\link{SampleMean}} +\item \code{\link{PseudoRaoBlackwell}} +\item \code{\link{MedianUnbiasedLikelihoodRatioOrdering}} +\item \code{\link{BiasReduced}} +} +} + +\subsection{Confidence intervals}{ + +The following \code{\link{IntervalEstimator}}s are included: +\itemize{ +\item \code{\link{StagewiseCombinationFunctionOrderingCI}} +\item \code{\link{LikelihoodRatioOrderingCI}} +} +} + +\subsection{P-Values}{ + +The following \code{\link{PValue}}s are included: +\itemize{ +\item \code{\link{StagewiseCombinationFunctionOrderingPValue}} +\item \code{\link{LikelihoodRatioOrderingPValue}} +} +} } \examples{ set.seed(123) diff --git a/man/get_statistics_from_paper.Rd b/man/get_statistics_from_paper.Rd index e9751c1..ba4dfc1 100644 --- a/man/get_statistics_from_paper.Rd +++ b/man/get_statistics_from_paper.Rd @@ -2,7 +2,7 @@ % Please edit documentation in R/helper_functions.R \name{get_statistics_from_paper} \alias{get_statistics_from_paper} -\title{Generate a list of estimators and p-values to use in examples} +\title{Generate the list of estimators and p-values that were used in the paper} \usage{ get_statistics_from_paper( point_estimators = TRUE, @@ -18,10 +18,11 @@ get_statistics_from_paper( \item{p_values}{logical indicating whether p-values should be included in output list} } \value{ -a list of estimators and pvalues. +a list of \code{\link{PointEstimator}}s, \code{\link{IntervalEstimator}}s and +\code{\link{PValue}}. } \description{ -Generate a list of estimators and p-values to use in examples +Generate the list of estimators and p-values that were used in the paper } \examples{ set.seed(123) diff --git a/man/plot-EstimatorScoreResult-method.Rd b/man/plot-EstimatorScoreResult-method.Rd index 4ed5517..2b0230d 100644 --- a/man/plot-EstimatorScoreResult-method.Rd +++ b/man/plot-EstimatorScoreResult-method.Rd @@ -15,7 +15,7 @@ of such objects (\code{EstimatorScoreResultList}).} \item{...}{additional arguments handed down to ggplot.} } \value{ -a ggplot2 object visualizing the score values. +a \code{\link{ggplot2}} object visualizing the score values. } \description{ This function extract the values of mu and the score values and a facet plot with diff --git a/man/plot-EstimatorScoreResultList-method.Rd b/man/plot-EstimatorScoreResultList-method.Rd index 00d830b..8617358 100644 --- a/man/plot-EstimatorScoreResultList-method.Rd +++ b/man/plot-EstimatorScoreResultList-method.Rd @@ -15,7 +15,7 @@ of such objects (\code{EstimatorScoreResultList}).} \item{...}{additional arguments handed down to ggplot.} } \value{ -a ggplot2 object visualizing the score values. +a \code{\link{ggplot2}} object visualizing the score values. } \description{ This function extract the values of mu and the score values and a facet plot with diff --git a/man/plot-list-method.Rd b/man/plot-list-method.Rd index 5606a11..d1c2125 100644 --- a/man/plot-list-method.Rd +++ b/man/plot-list-method.Rd @@ -15,7 +15,7 @@ of such objects (\code{EstimatorScoreResultList}).} \item{...}{additional arguments handed down to ggplot.} } \value{ -a ggplot2 object visualizing the score values. +a \code{\link{ggplot2}} object visualizing the score values. } \description{ This function extract the values of mu and the score values and a facet plot with diff --git a/man/plot_p.Rd b/man/plot_p.Rd index e145dac..9263800 100644 --- a/man/plot_p.Rd +++ b/man/plot_p.Rd @@ -33,7 +33,7 @@ plot_p( \item{...}{additional arguments handed down to ggplot} } \value{ -a ggplot2 object visualizing the p-values on a grid of possible test-statistic values. +a \code{\link{ggplot2}} object visualizing the p-values on a grid of possible test-statistic values. } \description{ Creates a plot of the p-values and implied rejection boundaries on a grid