feat: implement citation mechanism (#110)

DESCRIPTION

@@ -88,6 +88,7 @@ RdMacros: Rdpack
 VignetteBuilder: knitr
 Collate: 
     'assert.R'
+    'citation.R'
     'compute.R'
     'data.R'
     'formula.R'

NAMESPACE

@@ -94,6 +94,7 @@ export(fittedTrajectories)
 export(generateLongData)
 export(getArgumentDefaults)
 export(getArgumentExclusions)
+export(getCitation)
 export(getExternalMetricDefinition)
 export(getExternalMetricNames)
 export(getInternalMetricDefinition)
@@ -205,6 +206,7 @@ exportMethods(fit)
 exportMethods(fittedTrajectories)
 exportMethods(getArgumentDefaults)
 exportMethods(getArgumentExclusions)
+exportMethods(getCitation)
 exportMethods(getLabel)
 exportMethods(getLcMethod)
 exportMethods(getName)

R/citation.R

@@ -0,0 +1,36 @@
+tmpCiteEnv = new.env(parent = emptyenv())
+
+.suggestCiteMethod = function(x, optional = TRUE) {
+  assert_that(
+    is.lcMethod(x) || is.lcModel(x),
+    is.flag(optional)
+  )
+
+  cite = getCitation(x)
+  citeName = paste0('latrend.cited.', class(x))
+  skip = getOption(citeName, default = FALSE)
+  assert_that(
+    is.flag(skip),
+    msg = sprintf('Invalid value for option "%s": should be a flag (T/F)', citeName)
+  )
+
+  if (length(cite) == 0 || exists(citeName, envir = tmpCiteEnv) || optional && skip) {
+    return()
+  }
+
+  message(
+    sprintf(
+      'Attribution notice: %1$s makes use of external R package(s):
+  - Run `getCitation(model)` to view how to cite the external package(s) when reporting results.
+  - To disable this notice, run `options(%2$s = TRUE)`.',
+      class(x),
+      citeName
+    )
+  )
+
+  assign(citeName, value = TRUE, envir = tmpCiteEnv)
+}
+
+.clearCited = function() {
+  tmpCiteEnv = new.env(parent = emptyenv())
+}

R/generics.R

@@ -288,6 +288,25 @@ setGeneric('getArgumentExclusions', function(object, ...) {
   out
 })
 
+
+# getCitation ####
+#' @export
+#' @name latrend-generics
+setGeneric('getCitation', function(object, ...) {
+  out <- standardGeneric('getCitation')
+
+  assert_that(
+    inherits(out, 'citation'),
+    msg = sprintf(
+      'Implementation error for %1$s: getCitation(%1$s) must return an object of class "citation"',
+      class(object)[1]
+    )
+  )
+
+  out
+})
+
+
 # getLabel ####
 #' @export
 #' @name latrend-generics

R/method.R

@@ -633,6 +633,19 @@ setMethod('getArgumentDefaults', 'lcMethod', function(object) {
   set_names(list(), character(0))
 })
 
+
+#. getCitation ####
+#' @name getCitation
+#' @rdname getCitation
+#' @title Get citation info
+#' @description Get a citation object indicating how to cite the underlying R packages used for estimating or representing the given method or model.
+#' @param object The object
+#' @return A [citation] object
+setMethod('getCitation', 'lcMethod', function(object, ...) {
+  utils::citation(package = 'base')[0]
+})
+
+
 #. getArgumentExclusions ####
 #' @export
 #' @name getArgumentExclusions

R/methodKML.R

@@ -58,6 +58,13 @@ setMethod('getArgumentExclusions', 'lcMethodKML', function(object) {
   )
 })
 
+
+#' @rdname interface-kml
+setMethod('getCitation', 'lcMethodKML', function(object, ...) {
+  citation('kml')
+})
+
+
 #' @rdname interface-kml
 setMethod('getName', 'lcMethodKML', function(object) 'longitudinal k-means (KML)')
 

R/model.R

@@ -644,6 +644,13 @@ setMethod('getLabel', 'lcModel', function(object, ...) {
   }
 })
 
+
+# . getCitation ####
+#' @export
+#' @rdname getCitation
+setMethod('getCitation', 'lcModel', function(object, ...) getCitation(getLcMethod(object)))
+
+
 # . getLcMethod ####
 #' @export
 #' @name getLcMethod

tests/testthat/test-citation.R

@@ -0,0 +1,34 @@
+test_that('nothing to cite', {
+  .clearCited()
+  expect_silent({
+    .suggestCiteMethod(testModel1)
+  })
+
+  expect_silent({
+    .suggestCiteMethod(testModel3)
+  })
+})
+
+
+test_that('method citation', {
+  skip_if_not_installed('kml')
+  method = lcMethodKML('Y', id = 'Id', time = 'Time', nClusters = 3)
+  .clearCited()
+
+  options(latrend.cited.lcMethodKML = FALSE)
+  expect_message({
+    .suggestCiteMethod(method)
+  }, 'lcMethodKML')
+
+  # should not print on the second run
+  expect_silent({
+    .suggestCiteMethod(method)
+  })
+
+  # should not print when option is set
+  .clearCited()
+  options(latrend.cited.lcMethodKML = TRUE)
+  expect_silent({
+    .suggestCiteMethod(method)
+  })
+})