Skip to content

Latest commit

 

History

History
300 lines (176 loc) · 12.9 KB

README.md

File metadata and controls

300 lines (176 loc) · 12.9 KB
Raw

manaakiwhenua-standards

compGeometeR

compGeometeR aims to implement commonly used computational geometry algorithms in R. We believed that by implementing these algorithms within a single unified framework an R user could easily apply these algorithms in solving spatial problems in a variety of different domains, and we are building a compGeometeR cookbook that illustrates various use cases and provides advice for plotting and efficient computation.

You can read more about the design of compGeometeR, what algorithms are available, and some simple examples of use in the compGeometeR preprint software paper.

compGeometeR is distributed under the GNU General Public License (GPLv3).

Dependencies

Installation Options

Citation

Community Guidelines

Dependencies

compGeometeR has no package dependencies and was developed using R version 3.5.1.

It is built upon and depends on the Qhull library, however, and includes some C sources from that project.

Back to Top

Installation Options

compGeometeR is currently verified to build, install and run on Windows only. Depending on what you intend to use the package for, you may need different levels of control over how - and how often - you build, rebuild and install the package.

compGeometeR is not available on CRAN. You'll need to choose one of the options below in order to use it.

You will need RTools to be installed if your option includes building the C sources from scratch.

Installing the binary package zip for Windows from inside RStudio or R

Installing the source package tarball from inside RStudio or R

Installing the source package from the GitHub repository inside RStudio or R

Checking and building the package locally in RStudio or R

Reinstalling a local build from RStudio or R after making changes

Installing the binary package zip for Windows from inside RStudio or R

Choose this option if you simply want to use the R functions from the package.

  • Clone the repository from https://github.com/manaakiwhenua/compGeometeR if you haven't done that already

  • Open the compGeometeR project folder

  • Check that it contains a file called compGeometeR_<version>.zip, where <version> is the current release number

  • Open compGeometeR.Rproj in RStudio, or start R in that folder

  • Verify your working directory on the R console using getwd()

    • Set your working directory to compGeometeR using setwd("<path to parent folder>/compGeometeR") if you're in the wrong place

  • Install the binary package on Windows:

    install.packages("compGeometeR_<version>.zip")

    where <version> is again the current release number

You should be able to verify that the installation succeeded by loading the package using library(compGeometeR).

Installation Options

Back to Top

Installing the source package tarball from inside RStudio or R

Choose this option if any code that you add to the package is also in R and you have an up-to-date tarball to install from.

  • Clone the repository from https://github.com/manaakiwhenua/compGeometeR if you haven't done that already

  • Open the compGeometeR project folder

  • Check that it contains a file called compGeometeR_<version>.tar.gz, where <version> is the current release number

  • Open compGeometeR.Rproj in RStudio, or start R in that folder

  • Verify your working directory on the R console using getwd()

    • Set your working directory to compGeometeR using setwd("<path to parent folder>/compGeometeR") if you're in the wrong place

  • Build and install the source package:

    install.packages("compGeometeR_<version>.tar.gz", repos = NULL, type = "source")

    where <version> is again the current release number

You should be able to verify that the installation succeeded by loading the package using library(compGeometeR).

Installation Options

Back to Top

Installing the source package from the GitHub repository inside RStudio or R

Choose this option if you want to use the most recent, in-development version of the package, or if you want to build and install a version that comes from a git branch other than the main one.

  • Open RStudio or start R

  • Install devtools if you haven't done that already:

    • Inside RStudio: Tools -> Install Packages... -> select devtools package

    • From the R console:

      install.packages("devtools")

  • Load devtools if it's not in the workspace from a previous session:

    • Inside RStudio: Packages tab -> find devtools in the list of packages -> tick box next to package name

    • From the R console:

      library(devtools)

  • To install the master branch from GitHub:

    devtools::install_github("https://github.com/manaakiwhenua/compGeometeR", subdir = "package")

  • To install a different branch of compGeometeR from GitHub:

    devtools::install_github("https://github.com/manaakiwhenua/compGeometeR", subdir = "package", ref = "<your branch name>")

    where <your branch name> is the git branch that you want to check out from the repository.

As with installing from the tarball, you'll be able to verify that the installation succeeded by calling library(compGeometeR) to load it.

Installation Options

Back to Top

Checking and building the package locally in RStudio or R

Choose this option if you think you'll be making changes to any part of the C code. You'll end up with a new source package tarball or binary zip file that replaces the one you got from the git repository.

  • Clone the repository from https://github.com/manaakiwhenua/compGeometeR if you haven't done that already

  • Switch to the branch you want to be on if it's not master

  • Open compGeometeR.Rproj in RStudio, or start R in folder compGeometeR

  • Install devtools if you haven't done that already:

    • Inside RStudio: Tools -> Install Packages... -> select devtools package

    • From the R console:

      install.packages("devtools")

  • Load devtools if it's not in the workspace from a previous session:

    • Inside RStudio: Packages tab -> find devtools in the list of packages -> tick box next to package name

    • From the R console:

      library(devtools)

  • Verify your working directory on the R console using getwd()

  • Set the working directory to the package folder using setwd("./package")

  • Check if the package is in a state where it can be build and installed:

    devtools::check()

    This will:

    • Let you know any errors, warnings and notes that you might want to fix before proceeding

    • Rebuild the package documentation

    • Compile and link the C code in folder src for testing purposes

    • Run the tests

  • Build the package once you're happy with it:

    • Source package:

      devtools::build()

      This will:

      • Produce a tarball in folder compGeometeR that replaces the old one if you've made no changes to the version number

      • Produce a new tarball alongside the old one in folder compGeometeR if you've changed the version number in the DESCRIPTION file

    • Binary package for Windows:

      devtools::build(binary = TRUE)

      This will:

      • Produce a zip file in folder compGeometeR that replaces the old one if you've made no changes to the version number

      • Produce a new zip file alongside the old one in folder compGeometeR if you've changed the version number in the DESCRIPTION file

You'll be able load the newly built package using library(compGeometeR) if there were no errors.

Installation Options

Back to Top

Reinstalling a local build from RStudio or R after making changes

You'll be able to install a newly built local package in the exact same way as installing the tarball that came with the repo. The only thing you may have to change is the path to your .tar.gz file if it's different from the default.

  • Calling devtools::install() on the console from inside the package folder will work as well.

You may find that you get permission errors on Windows when reinstalling the package on top of an existing version after making changes to the code. Trying the following might help:

  • Unload the package if it's loaded

    • Untick the compGeometeR entry in the Packages tab if using RStudio

    • Detach it from the console if using plain R

      detach("package:compGeometeR", unload=TRUE)
      • You may have to do that in RStudio as well if you try to reinstall and get an error stating that the package is in use

  • Remove the package from your system:

    • Click the Remove icon for the compGeometeR entry in the Packages tab if using RStudio

    • Remove it from the console if using plain R:

    remove.packages("compGeometeR")

  • If that doesn't help for some reason:

    • Open the installation folder for R packages in Explorer (or in a file manager of your choice if not using Windows)

      • The error message will tell you what it is (typically something like C:\Users\<your_user_name>\AppData\Local\R\win-library\<r_version>\)

      • You can also find out by calling .libPaths() on the R console (the first entry on the list is the default location)

    • Check if the package folder is still there - it'll have the same name as the package

    • If the package folder's still hanging around:

      • Close RStudio and save the workspace

      • Delete the compGeometeR folder manually

      • Reopen RStudio

  • Rerun install.packages("<path to tarball>/compGeometeR_<version>.tar.gz", repos=NULL, type="source") or devtools::install() to reinstall the package after a successful devtools::build()

As always, loading the package with library(compGeometeR) afterwards will tell you if your installation succeeded.

Installation Options

Back to Top

Citation

If you make use of compGeometeR, we would really appreciate it if you could cite the compGeometeR preprint software paper:

Etherington TR, Omondiagbe OP (2021) compGeometeR: an R package for computational geometry. OSF Preprints, doi:10.31219/osf.io/b4zvr.

However, as compGeometeR is built upon and is dependant on the Qhull library that has also been published:

Barber CB, Dobkin DP, Huhdanpaa H (1996) The Quickhull algorithm for convex hulls. ACM Transactions on Mathematical Software 22: 469-483, doi:10.1145/235815.235821.

we think it is only fair that this work is cited too, so we would suggest including a statement such as the following in any published work:

"[we did some computational geometry analysis ...] using the R package compGeometeR (Barber et al. 1996, Etherington and Omondiagbe 2021)"

Back to Top

Community Guidelines

To report bugs or request extra functionality please use log an issue to get in touch.

We would also welcome contributions to compGeometeR from people who would like to join the development team. We would ask that you first open an issue to suggest an enhancement to be sure it is within scope of the project before forking the repository and issuing a pull request.

Our intention is that as people help to refine, fix, or add functionality to compGeometeR we will include these people as co-authors on the project, and will release a new version of the software paper preprint that includes these people as co-authors so that they too can get credit for their efforts.

Back to Top

Maintainer

Pascal Omondiagbe [email protected]