Address CRAN review: documentation, examples and function side effects

.github/workflows/R-CMD-check.yaml

@@ -59,7 +59,9 @@ jobs:
       - uses: r-lib/actions/setup-tinytex@v2
 
       - name: Install the Courier font used in the PDF manual
-        run: tlmgr install courier makeindex
+        run: |
+          tlmgr update --self
+          tlmgr install courier makeindex
 
       - uses: r-lib/actions/setup-r-dependencies@v2
         with:

DESCRIPTION

@@ -16,10 +16,15 @@ Authors@R: c(person("Daniel", "Fryer",
                      comment = c(ORCID = "0000-0002-1218-2804")),             
              person("Yuguang", "Wang", 
                      role = "aut"))
-Description: Handling and Analysing Spherical, 
-      HEALPix and Cosmic Microwave Background data on a HEALPix grid.
+Description: Tools for handling and analysing spherical data on a HEALPix grid,
+    with applications to cosmic microwave background maps. Supports reading FITS
+    files, converting between spherical and Cartesian coordinates and HEALPix
+    ordering schemes, selecting sky regions, sampling pixels, and visualising
+    maps. Implements empirical covariance, correlation and variogram estimation,
+    covariance model fitting, angular power spectrum estimation, and
+    distributional and entropy-based comparisons of spherical data.
 Depends: R (>= 4.5.0)
-License: GPL-3 | file LICENSE
+License: GPL-3
 Encoding: UTF-8
 LazyData: true
 Imports:

R/CMBDat.R

@@ -19,24 +19,13 @@
 #'If \code{mmap = TRUE} then a \code{\link[mmap:mmap]{mmap}} object is returned
 #'that points to the CMB map data table in the FITS file.
 #'
-#'@examples
-#'
-#' ## Ensure you have a FITS file with the correct path
-#' ## before running the example:
-#' ## download a FITS file and use real data
-#' # downloadCMBMap()
-#' # cmbdat <- CMBDat("CMB_map_smica1024.fits", mmap = TRUE)
-#' # class(cmbdat)
-#' # str(cmbdat)
-#'
-#'## View metadata
-#'# cmbdat$header1
-#'# cmbdat$header2
-#'# cmbdat$resoln
-#'# cmbdat$method
-#'# cmbdat$coordsys
-#'# cmbdat$nside
-#'# cmbdat$hdr
+#' @examples
+#' filename <- system.file("extdata", "CMB_testmap.fits", package = "rcosmo")
+#' cmbdat <- CMBDat(filename, spix = 1:10)
+#' class(cmbdat)
+#' cmbdat$nside
+#' cmbdat$ordering
+#' head(cmbdat$data)
 #'
 #'@export
 CMBDat <- function(filename, mmap = FALSE, spix) {
@@ -211,16 +200,12 @@ CTypeExpression <- function(TTYPEn, btype) {
 #' A CMBDataFrame containing the data in \code{x} restricted to the
 #' CMBWindow \code{new.window}
 #'
-#'@examples
-#'
-#'win1 <- CMBWindow(theta = c(0,pi/2,pi/2), phi = c(0,0,pi/2))
-#'
-#'## Ensure you have a FITS file with correct path
-#'## before uncommenting and running the rest of the example:
-#'# cmbdat <- CMBDat("CMB_map_smica1024.fits", mmap = TRUE)
-#'# class(cmbdat)
-#'# cmbdat.win <- window(cmbdat, new.window = win1)
-#'# class(cmbdat.win)
+#' @examples
+#' filename <- system.file("extdata", "CMB_testmap.fits", package = "rcosmo")
+#' cmbdat <- CMBDat(filename)
+#' win <- CMBWindow(x = 0, y = 0, z = 1, r = pi/2)
+#' cmbdat.win <- window(cmbdat, new.window = win)
+#' class(cmbdat.win)
 #'
 #'@export
 window.CMBDat <- function(x, new.window, intersect = TRUE, ...) {
@@ -237,12 +222,10 @@ window.CMBDat <- function(x, new.window, intersect = TRUE, ...) {
 #'
 #' @return TRUE if \code{cmbdf} is a CMBDat object, otherwise FALSE
 #'
-#'@examples
-#' ## First download the map
-#' # downloadCMBMap(foreground = "smica", nside = 1024)
-#' # cmbdat <- CMBDat("CMB_map_smica1024.fits", mmap = TRUE)
-#' # class(cmbdat)
-#' # is.CMBDat(cmbdat)
+#' @examples
+#' filename <- system.file("extdata", "CMB_testmap.fits", package = "rcosmo")
+#' cmbdat <- CMBDat(filename, spix = 1:10)
+#' is.CMBDat(cmbdat)
 #'
 #' @export
 is.CMBDat <- function(cmbdf)

R/CMBDataFrame.R

@@ -40,25 +40,20 @@
 #'HEALPix indices.
 #'
 #'@examples
-#' ## Method 1: Read the data while constructing the CMBDataFrame
-#' ## download a FITS file and use real data
-#' # downloadCMBMap()
-#' # df <- CMBDataFrame("CMB_map_smica1024.fits")
+#' ## Construct a small synthetic sky map.
 #' df <- CMBDataFrame(nside = 16, I = rnorm(12 * 16 ^ 2),
 #'                    ordering = "nested")
 #'
-#' # Specify a sample size for a random sample
+#' ## Take a random sample.
 #' df.sample <- CMBDataFrame(df, sample.size = 80)
 #' plot(df.sample)
 #'
-#' # Specify a vector of pixel indices using spix
+#' ## Select pixels by index.
 #' df.subset <- CMBDataFrame(df, spix = c(2,4,6))
 #'
-#' # Take a look at the summary
+#' ## Inspect the map and the selected pixel indices.
 #' summary(df)
 #'
-#' # Access HEALPix pixel indices using pix function
-#' # (these are stored in the row.names attribute)
 #' pix(df.subset)
 #'
 #'

R/CMBDataFrameGenerics.R

@@ -208,6 +208,11 @@ window.CMBDataFrame <- function(x, new.window, intersect = TRUE,
 #'
 #'@export
 #'
+#'
+#' @return A \code{CMBDataFrame} restricted to the window specified by \code{value}.
+#' @param x The object to update.
+#' @param ... Extra arguments passed to the corresponding method.
+#' @param value The replacement value; see the corresponding accessor method.
 `window<-.CMBDataFrame` <- function(x, ..., value)
 {
   return(rcosmo::window(x, new.window = value))
@@ -295,6 +300,11 @@ ordering.CMBDataFrame <- function( x, new.ordering, ... )
 #' ordering(cmbdf)
 #'
 #' @export
+#'
+#' @return A \code{CMBDataFrame} with rows and pixel indices reordered according to \code{value}.
+#' @param x The object to update.
+#' @param ... Extra arguments passed to the corresponding method.
+#' @param value The replacement value; see the corresponding accessor method.
 `ordering<-.CMBDataFrame` <- function(x,...,value) {
   rcosmo::ordering(x, new.ordering = value)
 }
@@ -343,10 +353,6 @@ nside.CMBDataFrame <- function( x )
 #' a new CMBDataFrame.
 #'
 #'@examples
-#' ## First download the map
-#' # downloadCMBMap(foreground = "smica", nside = 1024)
-#' # df <- CMBDataFrame("CMB_map_smica1024.fits", sample.size = 800000)
-#' # pix(df)
 #'
 #' df <- CMBDataFrame(nside = 16, sample.size = 10, ordering = "nested")
 #' pix(df)
@@ -370,6 +376,11 @@ pix.CMBDataFrame <- function(x, new.pix, ...)
 #' @keywords internal
 #'
 #' @export
+#'
+#' @return A \code{CMBDataFrame} with its HEALPix pixel indices replaced by \code{value}.
+#' @param x The object to update.
+#' @param ... Extra arguments passed to the corresponding method.
+#' @param value The replacement value; see the corresponding accessor method.
 `pix<-.CMBDataFrame` <- function(x,...,value) {
   row.names(x) <- value
   x
@@ -425,6 +436,8 @@ pix.CMBDataFrame <- function(x, new.pix, ...)
 #'
 #'
 #'@export
+#'
+#' @return A \code{CMBDataFrame} containing the combined columns, with HEALPix metadata and pixel indices retained from the single CMBDataFrame input.
 cbind.CMBDataFrame <- function(..., deparse.level = 1)
 {
   args <- list(...)
@@ -502,6 +515,8 @@ cbind.CMBDataFrame <- function(..., deparse.level = 1)
 #' pix(df.123234)
 #'
 #'@export
+#'
+#' @return A \code{CMBDataFrame} containing the combined rows and windows, with overlapping pixel indices deduplicated. If \code{unsafe = TRUE}, returns an \code{HPDataFrame} retaining duplicate pixels instead. All inputs must have matching nside and ordering.
 rbind.CMBDataFrame <- function(..., deparse.level = 1, unsafe = FALSE)
 {
   args <- list(...)
@@ -600,6 +615,8 @@ rbind.CMBDataFrame <- function(..., deparse.level = 1, unsafe = FALSE)
 #' suppressMessages(areCompatibleCMBDFs(a,b))
 #'
 #' @export
+#'
+#' @return A single logical value, \code{TRUE} if both objects have the same nside and ordering, and also the same pixel indices when \code{compare.pix = TRUE}; otherwise \code{FALSE}. Incompatibilities are reported with a suppressible message.
 areCompatibleCMBDFs <- function(cmbdf1, cmbdf2, compare.pix = FALSE)
 {
   if ( !is.CMBDataFrame(cmbdf1) || !is.CMBDataFrame(cmbdf1) )
@@ -1074,6 +1091,11 @@ coords.CMBDataFrame <- function( x, new.coords, ... )
 #' df
 #'
 #' @export
+#'
+#' @return A \code{CMBDataFrame} with coordinates converted to the system specified by \code{value}.
+#' @param x The object to update.
+#' @param ... Extra arguments passed to the corresponding method.
+#' @param value The replacement value; see the corresponding accessor method.
 `coords<-.CMBDataFrame` <- function(x, ..., value) {
   return(coords(x, new.coords = value))
 }
@@ -1127,11 +1149,10 @@ coords.CMBDataFrame <- function( x, new.coords, ... )
 #'@return
 #'A plot of the CMB data
 #'
-#'@examples
-#' ## First download the map
-#' # downloadCMBMap(foreground = "smica", nside = 1024)
-#' # sky <- CMBDataFrame("CMB_map_smica1024.fits")
-#' # plot(sky, sample.size = 800000)
+#' @examples
+#' set.seed(1)
+#' cmbdf <- CMBDataFrame(nside = 8, I = rnorm(12 * 8^2), ordering = "nested")
+#' plot(cmbdf)
 #'
 #'@export
 plot.CMBDataFrame <- function(x, intensities = "I",
@@ -1233,11 +1254,6 @@ colscheme <- function(I, breaks, colmap) {
 #'
 #'
 #'@examples
-#' ## First download the map
-#' # downloadCMBMap(foreground = "smica", nside = 1024)
-#' # df <- CMBDataFrame("CMB_map_smica1024.fits")
-#' # df.sample <- CMBDataFrame(df, sample.size = 800000)
-#' # summary(df.sample)
 #'
 #' ns <- 16
 #' df <- CMBDataFrame(I = rnorm(12*ns^2), nside = ns,
@@ -1304,6 +1320,9 @@ summary.CMBDataFrame <- function(object, intensities = "I", ...)
 #'@export
 #'
 #'
+#'
+#' @return The input \code{summary.CMBDataFrame} object, returned invisibly. Called for its side effect of printing the summary.
+#' @param ... Unused arguments.
 print.summary.CMBDataFrame <- function(x, ...)
 {
   cat(
@@ -1344,6 +1363,7 @@ print.summary.CMBDataFrame <- function(x, ...)
     cli::rule(line = "="),
     sep = ""
   )
+  invisible(x)
 }
 
 
@@ -1357,11 +1377,10 @@ print.summary.CMBDataFrame <- function(x, ...)
 #'@return
 #'Prints contents of the CMB data frame to the console.
 #'
-#'@examples
-#' ## First download the map
-#' # downloadCMBMap(foreground = "smica", nside = 1024)
-#' # df <- CMBDataFrame("CMB_map_smica1024.fits")
-#' # print(df)
+#' @examples
+#' set.seed(1)
+#' cmbdf <- CMBDataFrame(nside = 8, I = rnorm(12 * 8^2), ordering = "nested")
+#' print(cmbdf)
 #'
 #'@export
 print.CMBDataFrame <- function(x, ...)

R/CMBDataFrameHelpers.R

@@ -10,10 +10,6 @@
 #' at the \code{nside} resolution of \code{nsideObject}
 #'
 #' @examples
-#' ## First download the map
-#' # downloadCMBMap(foreground = "smica", nside = 1024)
-#' # df <- CMBDataFrame("CMB_map_smica1024.fits")
-#' # pixelArea(df)
 #'
 #' df1 <- CMBDataFrame(nside = 64,
 #'                     coords = "cartesian",
@@ -58,12 +54,10 @@ pixelArea <- function(nsideObject)
 #' data was imported
 #'
 #'
-#'@examples
-#' ## First download the map
-#' # downloadCMBMap(foreground = "smica", nside = 1024)
-#' # df <- CMBDataFrame("CMB_map_smica1024.fits")
-#' # df.sample <- CMBDataFrame(df, sample.size = 10000)
-#' # header(df.sample)
+#' @examples
+#' set.seed(1)
+#' cmbdf <- CMBDataFrame(nside = 8, I = rnorm(12 * 8^2), ordering = "nested")
+#' header(cmbdf)
 #'
 #'@export
 header <- function( cmbdf )
@@ -89,11 +83,9 @@ header <- function( cmbdf )
 #' data was sourced
 #'
 #' @examples
-#'
-#' ## First download the map
-#' # downloadCMBMap(foreground = "smica", nside = 1024)
-#' # df <- CMBDataFrame("CMB_map_smica1024.fits")
-#' # resolution(df)
+#' set.seed(1)
+#' cmbdf <- CMBDataFrame(nside = 8, I = rnorm(12 * 8^2), ordering = "nested")
+#' resolution(cmbdf)
 #'
 #'@export
 resolution <- function( cmbdf )

R/CMBWindow.R

@@ -42,6 +42,8 @@
 #' window(cmbdf) <- CMBWindow(x=0,y=3/5,z=4/5,r=0.8, set.minus =TRUE)
 #' plot(cmbdf)
 #'@export
+#'
+#' @return A data frame of class \code{CMBWindow} containing vertex coordinates for a polygon, or centre coordinates and radius \code{r} for a disc. Attributes record the coordinate system, window type and convexity assumption.
 CMBWindow <- function(..., r, set.minus = FALSE, assume.convex = FALSE) {
 
   args <- list(...)

R/CMBWindowGenerics.R

@@ -65,6 +65,9 @@ summary.CMBWindow <- function(object, ...)
 #'@keywords internal
 #'
 #'@export
+#'
+#' @return The input \code{summary.CMBWindow} object, returned invisibly. Called for its side effect of printing the summary.
+#' @param ... Unused arguments.
 print.summary.CMBWindow <- function(x, ...)
 {
   cat(
@@ -73,6 +76,7 @@ print.summary.CMBWindow <- function(x, ...)
     ),
     sep = ""
   )
+  invisible(x)
 }
 
 
@@ -130,6 +134,8 @@ is.CMBWindow <- function(win)
 #' plot(win2)
 #'
 #'@export
+#'
+#' @return No meaningful return value; called for its side effect of drawing the window in the current rgl scene.
 plot.CMBWindow <- function(x, add = TRUE, type = "l",
                            col = "red",
                            size = 2, box = FALSE,
@@ -438,6 +444,11 @@ coords.CMBWindow <- function( x, new.coords, ... )
 #'@keywords internal
 #'
 #'@export
+#'
+#' @return A \code{CMBWindow} with coordinates converted to the system specified by \code{value}.
+#' @param x The object to update.
+#' @param ... Extra arguments passed to the corresponding method.
+#' @param value The replacement value; see the corresponding accessor method.
 `coords<-.CMBWindow` <- function(x,...,value) {
   value <- tolower(value)
   if (rcosmo::coords(x) == value)