Merge pull request #51 from natverse/fix/jdm-cran

preparing for CRAN after archival

.github/.gitignore

@@ -0,0 +1 @@
+*.html

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

@@ -0,0 +1,30 @@
+# Workflow derived from https://github.com/r-lib/actions/tree/v2/examples
+# Need help debugging build failures? Start at https://github.com/r-lib/actions#where-to-find-help
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+    branches: [main, master]
+
+name: R-CMD-check
+
+jobs:
+  R-CMD-check:
+    runs-on: ubuntu-latest
+    env:
+      GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}
+      R_KEEP_PKG_SOURCE: yes
+      RGL_USE_NULL: TRUE
+    steps:
+      - uses: actions/checkout@v3
+
+      - uses: r-lib/actions/setup-r@v2
+        with:
+          use-public-rspm: true
+
+      - uses: r-lib/actions/setup-r-dependencies@v2
+        with:
+          extra-packages: any::rcmdcheck
+          needs: check
+
+      - uses: r-lib/actions/check-r-package@v2

.github/workflows/pkgdown.yaml

@@ -0,0 +1,48 @@
+# Workflow derived from https://github.com/r-lib/actions/tree/v2/examples
+# Need help debugging build failures? Start at https://github.com/r-lib/actions#where-to-find-help
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+    branches: [main, master]
+  release:
+    types: [published]
+  workflow_dispatch:
+
+name: pkgdown
+
+jobs:
+  pkgdown:
+    runs-on: ubuntu-latest
+    # Only restrict concurrency for non-PR jobs
+    concurrency:
+      group: pkgdown-${{ github.event_name != 'pull_request' || github.run_id }}
+    env:
+      GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v3
+
+      - uses: r-lib/actions/setup-pandoc@v2
+
+      - uses: r-lib/actions/setup-r@v2
+        with:
+          use-public-rspm: true
+
+      - uses: r-lib/actions/setup-r-dependencies@v2
+        with:
+          extra-packages: any::pkgdown, local::.
+          needs: website
+
+      - name: Build site
+        run: pkgdown::build_site_github_pages(new_process = FALSE, install = FALSE)
+        shell: Rscript {0}
+
+      - name: Deploy to GitHub pages 🚀
+        if: github.event_name != 'pull_request'
+        uses: JamesIves/github-pages-deploy-action@v4.4.1
+        with:
+          clean: false
+          branch: gh-pages
+          folder: docs

.gitignore

@@ -1,3 +1,4 @@
 .Rproj.user
 .Rhistory
 .RData
+docs

DESCRIPTION

@@ -2,7 +2,7 @@ Type: Package
 Package: nat.templatebrains
 Title: NeuroAnatomy Toolbox ('nat') Extension for Handling
     Template Brains
-Version: 1.0.0.9000
+Version: 1.1
 Authors@R: 
     c(person(given = "Gregory",
              family = "Jefferis",
@@ -36,6 +36,6 @@ Suggests:
     testthat (>= 2.1.0),
     covr
 Encoding: UTF-8
-RoxygenNote: 7.2.1
+RoxygenNote: 7.2.3
 BugReports: https://github.com/natverse/nat.templatebrains/issues
 Language: en-GB

NAMESPACE

@@ -1,56 +1,57 @@
-# Generated by roxygen2: do not edit by hand
-
-S3method(as.character,templatebrain)
-S3method(as.im3d,templatebrain)
-S3method(as.templatebrain,character)
-S3method(as.templatebrain,im3d)
-S3method(as.templatebrain,templatebrain)
-S3method(boundingbox,templatebrain)
-S3method(dim,templatebrain)
-S3method(display_slice,templatebrain)
-S3method(origin,templatebrain)
-S3method(plot3d,templatebrain)
-S3method(print,templatebrain)
-S3method(voxdims,templatebrain)
-export("regtemplate<-")
-export(add_reg_folders)
-export(add_reglist)
-export(all_templatebrains)
-export(allreg_dataframe)
-export(as.templatebrain)
-export(bridging_graph)
-export(bridging_sequence)
-export(display_slice)
-export(download_reg_repo)
-export(extra_reg_folders)
-export(fit_xform)
-export(fit_xform_brain)
-export(guess_templatebrain)
-export(is.templatebrain)
-export(local_reg_dir_for_url)
-export(mirror_brain)
-export(regtemplate)
-export(shortest_bridging_seq)
-export(templatebrain)
-export(update_reg_repos)
-export(xform_brain)
-importFrom(digest,digest)
-importFrom(igraph,"E<-")
-importFrom(igraph,E)
-importFrom(igraph,get.shortest.paths)
-importFrom(igraph,graph.edgelist)
-importFrom(igraph,shortest.paths)
-importFrom(igraph,vertex_attr)
-importFrom(memoise,forget)
-importFrom(nat,as.im3d)
-importFrom(nat,boundingbox)
-importFrom(nat,origin)
-importFrom(nat,pointsinside)
-importFrom(nat,read.im3d)
-importFrom(nat,voxdims)
-importFrom(nat,xform)
-importFrom(nat,xyzmatrix)
-importFrom(rappdirs,user_data_dir)
-importFrom(rgl,as.mesh3d)
-importFrom(rgl,persp3d)
-importFrom(rgl,plot3d)
+# Generated by roxygen2: do not edit by hand
+
+S3method(as.character,templatebrain)
+S3method(as.im3d,templatebrain)
+S3method(as.templatebrain,character)
+S3method(as.templatebrain,im3d)
+S3method(as.templatebrain,templatebrain)
+S3method(boundingbox,templatebrain)
+S3method(dim,templatebrain)
+S3method(display_slice,default)
+S3method(display_slice,templatebrain)
+S3method(origin,templatebrain)
+S3method(plot3d,templatebrain)
+S3method(print,templatebrain)
+S3method(voxdims,templatebrain)
+export("regtemplate<-")
+export(add_reg_folders)
+export(add_reglist)
+export(all_templatebrains)
+export(allreg_dataframe)
+export(as.templatebrain)
+export(bridging_graph)
+export(bridging_sequence)
+export(display_slice)
+export(download_reg_repo)
+export(extra_reg_folders)
+export(fit_xform)
+export(fit_xform_brain)
+export(guess_templatebrain)
+export(is.templatebrain)
+export(local_reg_dir_for_url)
+export(mirror_brain)
+export(regtemplate)
+export(shortest_bridging_seq)
+export(templatebrain)
+export(update_reg_repos)
+export(xform_brain)
+importFrom(digest,digest)
+importFrom(igraph,"E<-")
+importFrom(igraph,E)
+importFrom(igraph,get.shortest.paths)
+importFrom(igraph,graph.edgelist)
+importFrom(igraph,shortest.paths)
+importFrom(igraph,vertex_attr)
+importFrom(memoise,forget)
+importFrom(nat,as.im3d)
+importFrom(nat,boundingbox)
+importFrom(nat,origin)
+importFrom(nat,pointsinside)
+importFrom(nat,read.im3d)
+importFrom(nat,voxdims)
+importFrom(nat,xform)
+importFrom(nat,xyzmatrix)
+importFrom(rappdirs,user_data_dir)
+importFrom(rgl,as.mesh3d)
+importFrom(rgl,persp3d)
+importFrom(rgl,plot3d)

NEWS.md

@@ -1,4 +1,10 @@
-# nat.templatebrains (development version)
+# nat.templatebrains 1.1
+
+* Fixes for CRAN after archival (mostly documentation and links)
+* Feature/fit xform by @jefferis in https://github.com/natverse/nat.templatebrains/pull/50
+* dev: check and pkgdown docs now via github actions
+
+**Full Changelog**: https://github.com/natverse/nat.templatebrains/compare/v1.0...v1.1
 
 # nat.templatebrains 1.0
 

R/display_slice.R

@@ -3,12 +3,16 @@
 #' @param brain template brain (e.g. IS2) of the slice.
 #' @param slice Path to PNG image containing slice to display.
 #' @param ... extra arguments to pass to \code{\link[rgl]{persp3d}}.
+#'
+#' @return This function is principally called for its side effect of adding to
+#'   the plot. A vector of rgl shape IDs is returned invisibly.
 #' @export
 display_slice <- function(brain, slice, ...) {
   UseMethod("display_slice")
 }
 
 #' @method display_slice default
+#' @export
 display_slice.default <- function(brain, slice, ...) {
 }
 

R/fit-xform.R

@@ -19,7 +19,8 @@
 #'   provided points to calculate the new transform.
 #' @param ... Additional arguments passed to \code{\link{computeTransform}}
 #'
-#' @return A homogeneous affine matrix or a \code{\link{tpsreg}} object
+#' @return A homogeneous affine matrix or a \code{nat::tpsreg} object
+#'   n.b. only in development nat (>= 1.10.1)
 #' @export
 #'
 #' @examples
@@ -119,7 +120,8 @@ sample_points_in_surf <- function(x, n){
 #'   bounding box. If not there will be an error and you will have to supply the
 #'   points.
 #'
-#' @return A homogeneous affine matrix or a \code{\link{tpsreg}} object
+#' @return A homogeneous affine matrix or a \code{nat::tpsreg} object
+#'   n.b. only in development nat (>= 1.10.1)
 #' @seealso \code{\link{fit_xform}}
 #' @export
 #'

R/plotting.R

@@ -12,6 +12,8 @@
 #' @param ... extra arguments to pass to \code{\link[rgl]{plot3d}}.
 #' @export
 #' @importFrom rgl plot3d
+#' @return This function is principally called for its side effect of adding to
+#'   the plot. A vector of rgl shape IDs is returned invisibly.?
 plot3d.templatebrain <- function(x, col='grey', alpha=0.3, ...) {
   plot3d(get(paste0(as.character(x), ".surf")), col=col, alpha=alpha, ...)
 }

R/reg_repos.R

@@ -13,6 +13,8 @@
 #'   credentials for private repo.
 #' @seealso \code{\link{add_reg_folders}}, \code{\link{local_reg_dir_for_url}},
 #'   \code{git2r::\link[git2r]{clone}}
+#' @return This function is principally called for its side effect. A path to
+#'   the location on disk containing added registrations is returned invisibly.
 #' @examples
 #' ## find the root location of all registration directories
 #' local_reg_dir_for_url()
@@ -75,6 +77,8 @@ download_reg_repo<-function(url, localdir=NULL, ...) {
 #' @param first Whether the new folder should be added to the start (default) or
 #'   end of the search list.
 #' @export
+#' @return This function is principally called for its side effect. A path to
+#'   the location on disk containing added registrations is returned invisibly.
 #' @examples
 #'
 #' \dontrun{
@@ -126,6 +130,7 @@ add_reg_folders<-function(dir=extra_reg_folders(), first=TRUE) {
 #'   \code{TRUE}.
 #' @param ... Additional arguments passed to \code{\link{saveRDS}} e.g. to
 #'   control compression when the reglist object is saved to disk.
+#' @return This function is called for its side effect and has no return value.
 #' @export
 #' @seealso add_reg_folders
 #' @examples
@@ -173,6 +178,9 @@ add_reglist <- function(x, reference=NULL, sample=NULL, mirror=NULL, temp=TRUE,
 #'
 #' @param x Path to local checkout of a registration git repository. See details
 #'   for meaning of default.
+#' @return This function is principally called for its side effect, but does
+#'   return a \code{git2r::repository} object containing the path on disk to the
+#'   location of the git repository with registration.
 #' @export
 #' @seealso \code{\link{download_reg_repo}}
 update_reg_repos<-function(x=NULL) {
@@ -226,6 +234,7 @@ make_reg_url<-function(url) {
 #'
 #' @param url Character vector containing a url. When \code{url=NULL} defaults
 #'   to giving the base path.
+#' @return path(s) containing registrations on disk.
 #' @export
 #' @seealso \code{\link{download_reg_repo}},
 #'   \code{rappdirs::\link{user_data_dir}}

R/templatebrain.R

@@ -15,7 +15,7 @@
 #' when the \code{BoundingBox} is specified to define the physical extent of the
 #' volume. We use the definition of the Amira 3D visualisation and analysis
 #' software. This corresponds to the \strong{node} centers option in the
-#' \href{http://teem.sourceforge.net/nrrd/format.html}{NRRD format}. The
+#' \href{https://teem.sourceforge.net/nrrd/format.html}{NRRD format}. The
 #' bounding box can be obtained from NRRD or AmiraMesh format files. See
 #' \code{\link[nat]{boundingbox}} for details.
 #'
@@ -118,8 +118,9 @@ as.templatebrain.templatebrain <- function(x, ...) x
 #' @description \code{is.templatebrain} tests if object is of class
 #'   templatebrain
 #' @param x an object (usually a \code{templatebrain}).
-#' @return A logical indicating whether or not the object is a
-#'   \code{templatebrain}.
+#' @return Return values are documented in the generic methods.
+#'   \code{is.templatebrain} returns a logical indicating whether or not the
+#'   object is a \code{templatebrain}.
 #' @export
 #' @name templatebrain-meths
 #' @aliases is.templatebrain
@@ -140,7 +141,8 @@ is.templatebrain<-function(x) inherits(x, 'templatebrain')
 #'
 #' @param field which field to use (defaults to \code{'regName'}).
 #' @param ... additional arguments for methods.
-#' @return Character vector.
+#' @return \code{as.character.templatebrain} returns a character vector with the
+#'   name of the template brain.
 #' @export
 #' @rdname templatebrain-meths
 as.character.templatebrain<-function(x, field=c('regName','name'), ...){
@@ -203,6 +205,7 @@ origin.templatebrain <- function(x, ...) {
 #' @export
 #' @method dim templatebrain
 #' @rdname templatebrain-meths
+#' @return \code{dim.templatebrain} returns a 3-value integer vector.
 dim.templatebrain <- function(x, ...) {
   dim(nat::as.im3d(x))
 }

R/transformation.R

@@ -39,8 +39,8 @@ mirror_reg<-function(brain, ...) {
 #' @export
 #' @examples
 #' \dontrun{
-#' bridging_sequence(sample=JFRC2, ref=FCWB, checkboth = T)
-#' bridging_sequence(sample=JFRC2, via=IS2, ref=FCWB, checkboth = T)
+#' bridging_sequence(sample=JFRC2, ref=FCWB, checkboth = TRUE)
+#' bridging_sequence(sample=JFRC2, via=IS2, ref=FCWB, checkboth = TRUE)
 #' }
 bridging_sequence<-function(sample, reference, via=NULL, imagedata=FALSE,
                             checkboth=!imagedata, mustWork=FALSE) {
@@ -338,7 +338,7 @@ find_bridging_path <- function(g, sample, reference) {
 #'
 #'   You can control whether you want to allow inverse registrations manually by
 #'   setting \code{checkboth} explicitly. Otherwise when \code{checkboth=NULL}
-#'   the default is to act as if \code{checkboth=T} but issue a warning if an
+#'   the default is to act as if \code{checkboth=TRUE} but issue a warning if an
 #'   inversion must be used.
 #'
 #' @param x the 3D object to be transformed
@@ -358,7 +358,7 @@ find_bridging_path <- function(g, sample, reference) {
 #' @param ... extra arguments to pass to \code{\link[nat]{xform}} and then on to
 #'   \code{\link[nat]{xformpoints}} or \code{\link[nat]{xformimage}} which will
 #'   eventually hand off to \code{\link{cmtk.reformatx}} when using CMTK.
-#'
+#' @return A transformed version of \code{x}
 #' @export
 #' @seealso \code{\link{mirror_brain}}, \code{\link{shortest_bridging_seq}}
 #'   \code{\link{bridging_graph}}, \code{\link{regtemplate}},
@@ -457,6 +457,7 @@ xform_brain <- function(x, sample=regtemplate(x), reference, via=NULL,
 #' @param transform whether to use warp (default) or affine component of
 #'   registration, or simply flip about midplane of axis.
 #' @param ... extra arguments to pass to \code{\link[nat]{mirror}}.
+#' @return A transformed version of \code{x}
 #' @seealso \code{\link{xform_brain}}, \code{\link{regtemplate}}
 #' @export
 #' @examples