Distance Object Manipulation Tools

Provides convenient methods for accessing the data in 'dist' objects with minimal memory and computational overhead. 'disttools' can be used to extract the distance between any pair or combination of points encoded by a 'dist' object using only the indices of those points. This is an improvement over existing functionality, which requires either coercing a 'dist' object into a matrix or calculating the one dimensional index corresponding to a pair of observations. Coercion to a matrix is undesirable because doing so doubles the amount of memory required for storage. In contrast, there is no inherent downside to the latter solution. However, in part due to several edge cases, correctly and efficiently implementing such a solution can be challenging. 'disttools' abstracts away these challenges and provides a simple interface to access the data in a 'dist' object using the latter approach.


Improved methods for handling 'dist' objects in R.

CRAN_Status_Badge Travis-CI Build Status Build status Coverage Status

Overview

Working with 'dist' objects in R can be challenging. What makes it challenging is that retrieving the distance between any two points requires specifying a 1 dimensional index. This is non-intuitive and requires the user to write additional code, which slows development and analysis. To avoid this problem, the function as.matrix has typically been used to convert a 'dist' object into a matrix. Once converted, distances can be accessed in the same way any element of a matrix is accessed, namely using two indices. Unfortunately, as.matrix conversion more than doubles memory usage. For small 'dist' objects this may not be a problem. However, for large 'dist' objects this can be quite problematic. The function get_dists in disttools solves this problem by facilitating rapid retrieval of the distance between any pair of points stored in a 'dist' object.

Installation

disttools can be installed from CRAN or GitHub by executing either of the following:

# Install from CRAN.
install.packages("disttools")
# Install from GitHub.
install.packages("devtools")
devtools::install_github("mamc-dci/disttools")

Usage

The package can be loaded by executing:

# Load the package.
library(disttools)

The help file for the function get_dists can be accessed by executing:

?get_dists

If installed, the package vignette, complete with examples, can be viewed by executing:

browseVignettes("disttools")

Alternatively, the vignette is available on the package's CRAN page: https://CRAN.R-project.org/package=disttools

Disclaimer

The views expressed are those of the author(s) and do not reflect the official policy of the Department of the Army, the Department of Defense or the U.S. Government.

News

disttools 0.1.7

  • Updated DESCRIPTION based on CRAN team comments.

Reference manual

It appears you don't have a PDF plugin for this browser. You can click here to download the reference manual.

install.packages("disttools")

0.1.7 by Zachary Colburn, 9 months ago


Browse source code at https://github.com/cran/disttools


Authors: Zachary Colburn [aut, cre] , Madigan Army Medical Center - Department of Clinical Investigation [cph, fnd]


Documentation:   PDF Manual  


MIT + file LICENSE license


Suggests covr, testthat, knitr, rmarkdown


See at CRAN