Package: ashapesampler 1.0.0
Emily Winn-Nunez
ashapesampler: Generating Alpha Shapes
Understanding morphological variation is an important task in many applications. Recent studies in computational biology have focused on developing computational tools for the task of sub-image selection which aims at identifying structural features that best describe the variation between classes of shapes. A major part in assessing the utility of these approaches is to demonstrate their performance on both simulated and real datasets. However, when creating a model for shape statistics, real data can be difficult to access and the sample sizes for these data are often small due to them being expensive to collect. Meanwhile, the landscape of current shape simulation methods has been mostly limited to approaches that use black-box inference---making it difficult to systematically assess the power and calibration of sub-image models. In this R package, we introduce the alpha-shape sampler: a probabilistic framework for simulating realistic 2D and 3D shapes based on probability distributions which can be learned from real data or explicitly stated by the user. The 'ashapesampler' package supports two mechanisms for sampling shapes in two and three dimensions. The first, empirically sampling based on an existing data set, was highlighted in the original main text of the paper. The second, probabilistic sampling from a known distribution, is the computational implementation of the theory derived in that paper. Work based on Winn-Nunez et al. (2024) <doi:10.1101/2024.01.09.574919>.
Authors:
ashapesampler_1.0.0.tar.gz
ashapesampler_1.0.0.tar.gz(r-4.5-noble)ashapesampler_1.0.0.tar.gz(r-4.4-noble)
ashapesampler_1.0.0.tgz(r-4.4-emscripten)ashapesampler_1.0.0.tgz(r-4.3-emscripten)
ashapesampler.pdf |ashapesampler.html✨
ashapesampler/json (API)
NEWS
| # Install 'ashapesampler' in R: |
| install.packages('ashapesampler', repos = 'https://cloud.r-project.org') |
This package does not link to any Github/Gitlab/R-forge repository. No issue tracker or development information is available.
Last updated 1 years agofrom:1c423b30ed. Checks:3 OK. Indexed: yes.
| Target | Result | Latest binary |
|---|---|---|
| Doc / Vignettes | OK | Mar 26 2025 |
| R-4.5-linux | OK | Mar 26 2025 |
| R-4.4-linux | OK | Mar 26 2025 |
Exports:calc_overlap_2Dcalc_overlap_3Dcount_neighborseuclid_dists_point_cloud_2Deuclid_dists_point_cloud_3Dextract_complex_edgesextract_complex_facesextract_complex_tetextreme_ptsgenerate_ashape2dgenerate_ashape3dget_alpha_complexn_bound_connect_2Dn_bound_connect_3Dn_bound_homology_2Dn_bound_homology_3Dread_alpha_txtreadOFFrunif_annulusrunif_ball_3Drunif_cuberunif_diskrunif_shell_3Drunif_squaresampling2Dashapesampling3Dashapetau_boundwrite_alpha_txt
Dependencies:abindalphahullalphashape3dbase64encBHbslibcachemclicodetoolscolorspacecpp11deldirdigestdoParalleldplyrevaluatefansifarverfastmapFNNfontawesomeforeachfsgenericsgeometryggplot2gluegtablehighrhtmltoolshtmlwidgetsigraphinterpisobanditeratorsjquerylibjsonliteknitrlabelinglatticelifecyclelinproglpSolvemagicmagrittrMASSMatrixmemoisemgcvmimemunsellnlmepillarpkgconfigpolyclippracmaR.methodsS3R.ooR.utilsR6RANNrappdirsRColorBrewerRcppRcppArmadilloRcppEigenRcppProgressrglrlangrmarkdownRvcgsassscalessgeostatspspatstat.dataspatstat.geomspatstat.randomspatstat.univarspatstat.utilssplancsTDAtibbletidyselecttinytextruncnormutf8vctrsviridisLitewithrxfunyaml
annulus_demo
Rendered fromannulus_demo.Rmdusingknitr::rmarkdownon Mar 26 2025.Last update: 2024-01-31
Started: 2024-01-31
probability_demo_2D
Rendered fromprobability_demo_2D.Rmdusingknitr::rmarkdownon Mar 26 2025.Last update: 2024-01-31
Started: 2024-01-31
probability_demo_3D
Rendered fromprobability_demo_3D.Rmdusingknitr::rmarkdownon Mar 26 2025.Last update: 2024-01-31
Started: 2024-01-31
torus_demo
Rendered fromtorus_demo.Rmdusingknitr::rmarkdownon Mar 26 2025.Last update: 2024-01-31
Started: 2024-01-31
Citation
To cite package ‘ashapesampler’ in publications use:
Winn-Nunez E, Crawford L (2024). ashapesampler: Generating Alpha Shapes. R package version 1.0.0, https://CRAN.R-project.org/package=ashapesampler.
Corresponding BibTeX entry:
@Manual{,
title = {ashapesampler: Generating Alpha Shapes},
author = {Emily Winn-Nunez and Lorin Crawford},
year = {2024},
note = {R package version 1.0.0},
url = {https://CRAN.R-project.org/package=ashapesampler},
}
Readme and manuals
ashapesampler
This repository contains an R package for generating synthetic alpha shapes by either (i) empirical sampling based on an existing dataset with reference shapes, or (ii) probabilistic sampling from a known distribution function on shapes.
Introduction
Understanding morphological variation is an important task in many applications. Recent studies in computational biology have focused on developing computational tools for the task of sub-image selection which aims at identifying structural features that best describe the variation between classes of shapes. A major part in assessing the utility of these approaches is to demonstrate their performance on both simulated and real datasets. However, when creating a model for shape statistics, real data can be difficult to access and the sample sizes for these data are often small due to them being expensive to collect. Meanwhile, the landscape of current shape simulation methods has been mostly limited to approaches that use black-box inference---making it difficult to systematically assess the power and calibration of sub-image models.
In this R package, we introduce the $\alpha$-shape sampler: a probabilistic framework for simulating realistic 2D and 3D biological shapes and images based on probability distributions which can be learned from real data or explicitly stated by the user.
The Method
The ashapesampler package supports two mechanisms for sampling shapes in two and three-dimensions, which we outline below. The first strategy empirically samples new shapes based on an existing dataset --- this was highlighted in the main text of Winn-Nuñez et al. The second strategy probabalistically samples new shapes from a known distrubtion --- this approach is also implementated in this software package with the corresponding theory being derived in the Supporting Information of Winn-Nuñez et al.
Generating New Shapes from an Existing Dataset
The $\alpha$-shape sampler consists of four key steps:
- Input aligned reference shapes as simplicial complexes. A simplicial complex object in this case is a list containing (a) the Euclidean coordinates of the vertices and (b) a list of all vertices, edges, faces, and tetrahedra. Functions are available to read OFF files into R in the correct format and to extract the simplical complex information from a generated alpha complex. A method to convert a binary mask to a 2D simplicial complex for use in the algorithm can be found in the vignettes.
- Calculate the reach for each shape in the dataset. The reach is estimated based on boundary points of the simplicial complex. Users can choose the summary statistic used for the estimated reach for a reference shape to be either the mean, median, or minimum across points. Default is mean. Once we have the reach for each shape, users can take some summary statistic (usually the minimum) over a
Jsubset of randomly selected reference shapes to produce new shapes. - Sample new points, using the combined point cloud of the randomly selected
Jshapes and the estimated reachtauderived from theJreference shapes. Parameters for rejection sampling can be adjusted by the users and are discussed further in the vignettes. Note that this step is generally the longest computationally---if the user reaches a computational bottleneck, check to the value oftaurelative to the area/volume of the combined point cloud. Parallelizing also speeds up the algorithm. - Output newly generated shape as an alpha shape object.
Users should note that it is critical to align shapes to maximize the pipeline's success and that there may be some manual parameter tuning for the best results.
Demonstrations for pipeline implementation are in the vignettes. Functions are broken into parts instead of integrated altogether so that users can troubleshoot the pipeline at different stages.
Generating New Shapes from Probability Distributions
Users an also use the ashapesampler package to generate shapes in two and three dimensions from probability distributions. This approach can prove particularly useful for simulating shapes and benchmarking the performance of different statistical methods. Here, we list the parameters for generating new shapes in two and three dimensions. Options for user-adjusted parameters and defaults can be found in the vignettes. Users should keep a few key points in mind when generating shapes this way:
- The
boundparameter is the manifold from which points are sampled. At this time, the package only supports a square, a circle (i.e., a disk where the function assumes it is filled in), and an annulus in two dimensions. In three-dimensions, it supports a cube, sphere (i.e., a ball where the function assumes it is filled in), and torus. The size of these manifolds can be specified using thermaxandrminparameters, where applicable. Adjusting the size may affect computational time if the reachtauis not adjusted with it. - The reach
tauneeds to be specified as a finite value in advance, as this hyperparameter affects the choice ofalpha. Default oftauis 1, but it can be any finite value. Keep in mind that the smaller thattauis relative to the area or volume of the manifold, the more detail in the shapes produced and the more time it will take to produce a new generate opbject shape. - By default,
alphawill be as large as theoretically allowed. The smalleralphais relative totau, the more points will need to be sampled and the more time it will take to produce a new generate shape. This is particularly true when the goal is to have shapes to have both full connectivity/no isolated points as well as preserve the homology. - At this time, the package only supports the truncated normal distribution for randomly selecting
alpha. Bounds of this truncated normal can be adjusted by the user up to what is theoretically allowed. Keep in mind that the general bounds of this distribution should keepalphaas large as possible for best computational performance.
R Packages for ashapesampler and Tutorials
The ashapesampler software requires the installation of the following R libraries:
Unless stated otherwise, the easiest way to install many of these packages is with the following example command entered in an R shell:
install.packages("alphahull", dependecies = TRUE)
Alternatively, one can also install R packages from the command line.
C++ Packages for ashapesampler and Tutorials
The code in this repository assumes that basic C++ functions and applications are already set up on the running personal computer or cluster. If not, some of the packages (e.g., TDA and alphashape3d) needed to build alpha complexes and alpha shapes in three dimensions will not work properly. A simple option is to use gcc. macOS users may use this collection by installing the Homebrew package manager and then typing the following into the terminal:
brew install gcc
For macOS users, the Xcode Command Line Tools include a GCC compiler. Instructions on how to install Xcode may be found here. Additional installs for macOS users are automake, curl, glfw3, glew, xquartz, and qpdf. For extra tips on how to run C++ on macOS, please visit here. For tips on how to avoid errors dealing with "-lgfortran" or "-lquadmath", please visit here.
R Package Installation
Package will eventually appear on CRAN, at which time one can download the package there.
To install the package from GitHub, we recommend using the remotes package by running the command:
remotes::install_github('lcrawlab/ashapesampler')
To then load the package in R, use the command
library(ashapesampler)
Other common installation procedures may apply.
Code Usage
Vignettes
The vignettes folder contains the following demonstrations for running and analyzing results in the ashapesampler:
- Sampling alpha shapes from a probability distribution in two-dimensions.
- Sampling alpha shapes from a probability distribution in three-dimensions.
- Generating new 2D annuli from a simulated set of annuli.
- Generating new 3D tori from a simulated set of tori.
Additional vignettes and source code can be found in the corresponding results repository.
The auto3dgm paradigm for assigning landmarks via unsupervised learning can be found here.
Data
Primate manibular molar data and neutrophil binary masks can be accessed and downloaded here.
Relevant Citations
E.T. Winn-Nuñez, H. Witt, D. Bhaskar, R.Y. Huang, I.Y. Wong, J.S. Reichner, and L. Crawford. Generative modeling of biological shapes and images using a probabilistic $\alpha$-shape sampler. bioRxiv.
Questions and Feedback
Please send any questions or feedback to the corresponding authors Emily Winn-Nuñez or Lorin Crawford.
We appreciate any feedback you may have with our repository and instructions.