?PH of mosquito records to predict Zika prevalence in Brazil

e.g. fortify_ripserr() for persistence data output by ripserr

Note: This issue refers to the underway merge of the StatSimplicialComplex and main branches.

I think the simplicial_complex layer should accept any-case spellings of "Cech", "alpha", etc. This can be done using tolower().

I raise it as an issue rather than unilaterally making the change because i don't know whether it makes more sense to apply tolower() in the internal helper function assign_complex_engine or in the ggproto function StatSimplicialComplex$setup_data(). I'd welcome advice.

see convo in #21

The following code creates an equilateral triangle and uses stat_vietoris* and stat_cech* to visualize the faces of the resulting simplicial complex at a diameter of 1, but returns warnings that the computation failed in stat_vietoris2 and stat_cech2 due to argument length of 0. Any thoughts on what's going on, @corybrunson? (using this example in a vignette under cran-prep branch of this repo)

library("ggplot2")
library("ggtda")

# create equilateral triangle point cloud
eq_tri <- data.frame(x = c(0, 1, 0.5),
                     y = c(0, 0, sqrt(3)/2))

# VR complex
ggplot(eq_tri, aes(x = x, y = y)) +
  coord_fixed() +
  stat_vietoris2(diameter = 2, fill = "darkgoldenrod", alpha = 0.1) +
  stat_vietoris1(diameter = 2, alpha = 0.25) +
  stat_vietoris0() +
  theme_minimal()

# Čech complex
ggplot(eq_tri, aes(x = x, y = y)) +
  coord_fixed() +
  stat_cech2(diameter = 2) +
  stat_cech1(diameter = 2, alpha = 0.25) +
  stat_cech0() +
  theme_minimal()

While reviewing the exported objects, i noticed that theme_persist() is a copy of theme_tda(). Since there will eventually be many more plot layers, some of which may be better suited to theme elements different from those of persistence diagrams, i would suggest dropping the generically-named theme_tda() in favor of defining only more precise themes as needed.

If agreed to, it would be good to do this as part of #21, to avoid future deprecation.

could we consider adding the option to shade the bottom-right triangular half of persistence diagrams? (example image above)

add vignettes for new users; tentatively the following ones:

• introduction: basic use of most/all visualizations
• detailed: one detailed vignette for each group of geoms/stats (e.g. 1 for simplicial complex visualizations, 1 for persistence homology, etc.)

Hey @corybrunson, just updated R to 3.6.2 and using stat_disk results in improperly rendered circles (below is example from ggtda GitHub README); possible that this is because of how circles are rendered as polygons instead? (geom_point from ggplot2 seems to be working okay)

Shiny modules seem to provide the most supported solution of encapsulating blocks of R code geared for building shiny apps quicker (another example article).

I was wondering if this package would be interested in incorporating some degree of modularization?

As an example, I forked this repo and added a few example shiny modules. Collectively, they create a set of UI buttons for choosing between persistence data plot types. There's also a buttons for doing things like adding the frontier, filtering by some noise threshold, choosing between H0, H1, etc., automatic reactive callbacks for detecting the nearest feature a user clicked, etc.

An example shiny app, also shown below, demonstrates the simplification modularization enables:

library(shiny)
library(ggtda)
library(TDAstats)

## Example from TDAstats calculate_homology function help page
library(TDAstats)
data("circle2d") # unit circle (Betti-1 number = 1)
circ.phom <- as.data.frame(calculate_homology(circle2d))
circ.phom$dimension <- as.factor(circ.phom$dimension)

## assume persistence data is named 'dgm' 
dgm <- circ.phom

ui <- fluidPage(
  titlePanel("Persistence shiny plot demo"), 
  sidebarLayout(
    sidebarPanel(
      dmg_select_ui(id = "select_pers"), ## selects the type of persistence plot to show
      dgm_var_UI(id = "var_pers")        ## parameters to tweak like e.g. noise threshold 
    ), 
    mainPanel(
      linkedPersistenceOutput("pers_plot"), 
      verbatimTextOutput("text_out")
    )
  )
)

server <- function(input, output, session){
  ## Get the type of plot to interact with  
  dgm_selection <- callModule(dgm_select, "select_pers")
  
  ## Get the selected parameters associated with the UI elements
  dgm_vars <- callModule(dgm_var, "var_pers", dgm)
  
  ## Create the persistence plot
  res <- callModule(linkedPersistence, "pers_plot", dgm, dgm_selection, dgm_vars)
  
  ## Show the index of the selected feature
  output$text_out <- renderText({ res$selected_feature_idx() })
}
shinyApp(ui, server)

The modules aren't entirely meant for the package as-is. I'm sure there's lots of different ways to improve them, just wondering the scope of this package, since I plan to do this otherwise with some of my other packages.

Potentially useful reference here

Note: This issue refers to the underway merge of the StatSimplicialComplex and main branches.

Currently, not only does the simplicial_complex layer not use a default radius or diameter, it fails when either fails to obtain at least one 1-simplex (as in the examples below, which cannot be reprexed because the branch merge is not complete). Instead, this should result in the 0-simplices being plotted, equivalently to using the point layer. Moreover, i suggest that the default be set to 0, perhaps with a warning to the user that a positive radius or diameter must be specified in order for higher-dimensional simplices to be plotted.

# create annulus point cloud
t <- runif(n = 60, min = 0, max = 2*pi)
ann <- data.frame(
  x = cos(t) + rnorm(n = 60L, mean = 0, sd = .1),
  y = sin(t) + rnorm(n = 60L, mean = 0, sd = .1)
)
# plot 0-simplices using the `point` layer
ggplot(ann, aes(x = x, y = y)) +
  coord_fixed() +
  geom_point()
# try to plot 0-simplices using the `simplicial_complex` layer
ggplot(ann, aes(x = x, y = y)) +
  coord_fixed() +
  stat_simplicial_complex(radius = 0)
# try again with a too-small radius
ggplot(ann, aes(x = x, y = y)) +
  coord_fixed() +
  stat_simplicial_complex(radius = 0.01)
# succeed only with a sufficiently large radius
ggplot(ann, aes(x = x, y = y)) +
  coord_fixed() +
  stat_simplicial_complex(radius = 0.1)

While working on the refactor from #55 I discovered what I believe to be a bug in the current implementation of the StatLandscape$compute_group method. When plotting the persistence landscape for a slightly modified version of the toy data used in our examples, one of the frontiers has two incorrect peaks. In the reprex below we see that the third frontier function has peaks at (1, 3) and (4, 5). However, there are no (birth, death) values corresponding to these peaks -- I think it's grabbing these from the previous frontier.

I'm going to fix this in the branch I'm working on, just wanted to bring attention to it in case we end up not merging the refactor to main.

library("ggtda")
#> Loading required package: rlang
#> Loading required package: ggplot2

# toy example
toy.data <- data.frame(
  birth = c(0, 0, 1, 3, 4, 1.5),
  death = c(5, 3, 5, 4, 6, 4),
  dim = factor(c(0, 0, 0, 0, 0, 0))
  # dim = factor(c(0, 0, 1, 1, 2, 2))
)

# persistence diagram with landscape overlaid
ggplot(toy.data,
       aes(start = birth, end = death, shape = dim)) +
  theme_persist() +
  coord_equal() +
  stat_persistence() +
  stat_landscape(aes(color = after_stat(factor(level, 1:4))), n_levels = 4, diagram = "diagonal") +
  lims(x = c(0, 8), y = c(0, NA)) +
  guides(alpha = "none")

^{Created on 2024-05-05 by the reprex package (v2.0.1)}

The geometric construction underpinning persistent homology is usefully illustrated by drawing disks of fixed radius around points in a Euclidean point cloud. Since this illustrative use does not require a variable radius, and since the x0 and y0 aesthetics of ggforce::geom_circle() can create confusion when used in tandem with x and y aesthetics, let's create a new geom_disk() layer for this purpose. By default, it should render disks (interiors) but not circles (boundaries), i.e. its defaults should include fill = <favorite color> and colour = NA.

Introduced in this arXiv article

A major problem with the diagram parameter is that different values can be applied to different layers, which results in nonsense. Instead, new coordinate system ggproto classes should be used, perhaps CoordFlat and CoordLandscape, which would transform the entire plot.

Note: This issue refers to the underway merge of the StatSimplicialComplex and main branches.

The computed variable 'dim' is assigned ordered(...) in several places, which seems to result in them occasionally being combined. This results in a warning, "Combining variables of class and was deprecated
in ggplot2 3.4.0." This suggests to me that the variable should be returned as an unordered factor (which still preserves the order of the values).

Even then, however, there is a possibility of unexpected behavior, since the smallest dimension may not always be 2—whether the combination is being done in base R or in {vctrs} (see example below).

I agree that the stat should output the variable as a factor rather than an integer, but it should be possible to store it as an integer throughout the computations and convert it to a factor just before returning.

c(factor(3:5),factor(1:3))
#> [1] 3 4 5 1 2 3
#> Levels: 3 4 5 1 2
vctrs::vec_c(factor(3:5),factor(1:3))
#> [1] 3 4 5 1 2 3
#> Levels: 3 4 5 1 2

^{Created on 2023-12-30 with reprex v2.0.2}

This issue consolidates #17, #18, and #53 and adds additional layers of interest. They are listed in perceived order of difficulty.

• Betti curve and stabilized Betti curve
• persistence silhouettes
• persistence images
• persistence terraces

The authors of this preprint define the fundamental box for any real value t. Ignoring multiplicities, it is the region of birth–death pairs (b,d) defined by b_≤_t<d; it can be thought of as the space of features whose lifetimes include t. Like the colleague who introduced me to it, i think i've seen it before under a different name.

It would be natural to highlight this region in certain plots, as the authors do in the preprint, using bounding rays and shading within the limits of the plotting window. It should be easy to implement as a new graphical element (e.g. geom_fundamental_box()) with a single additional non-aesthetic parameter t that also requires the same diagram parameter used by stat_persistence().

I think there's an issue with the barcode geom when two given bars are not unique. I have 28 barcodes, however 3 of them have exactly the same birth/death times, so only 25 get rendered.

Here's an example with the embedded toy data I was working with:

## Generated data 
dim <- c(0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,1,1)
birth <- c(0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0.213226,0.213225)
death <- c(0.00718,0.008658,0.00866,0.033702,0.033704,0.041683,0.041683,0.049228,0.049229,0.103626,0.103626,0.108313,0.108314,0.116322,0.116323,0.122399,0.1224,0.145653,0.145654,0.169471,0.169472,0.207892,0.207892,0.208636,0.208637,Inf,Inf,Inf)
bar <- data.frame(birth=birth, death=death, dim=dim)

## Plot barcodes w/ ggtda
library("ggtda")
#> Loading required package: ggplot2
#> Warning: package 'ggplot2' was built under R version 3.5.2
barcodes <- data.frame(appear=bar$birth, disappear=bar$death, dim=as.character(bar$dim))
p1 <- ggplot(barcodes, aes(start = appear, end = disappear, colour = dim, shape = dim)) +
      geom_barcode() +
      theme_tda()

## Working linerange w/ id_ dimension
barcodes_id <- cbind(id_ = seq(length(bar$birth)), barcodes)
p2 <- ggplot(barcodes_id) + geom_linerange(aes(x = id_, ymin = appear, ymax=disappear, colour = dim))

^{Created on 2019-05-16 by the reprex package (v0.3.0)}

If you inspect p1 vs p2, you'll see that p1 plots 25 bars while all 28 get plotted w/ p2.

Introduced in this JMLR article

Note: This issue refers to the underway merge of the StatSimplicialComplex and main branches.

While experimenting with examples in the old vignette using the new simplicial_complex layer, it became clear quickly that unexpectedly long runtimes can result from innocuous-looking code because Vietoris complexes accrue large numbers of high-dimensional simplices. Since (a) i think the vast majority of illustrations only bother using one layer of shading and (b) for quick-and-dirty pictures this should suffice anyway, i suggest that we change max_dimension = 10 to max_dimension = 2L. This will prevent long runtimes while without allowing the user to believe that all dimensions have been layered on (as might be wrongly suggested by setting max_dimension = 3L).

basic feature of persistence landscape (stat_persistence(diagram = "landscape")) has been implemented, following would help complete implementation:

• inclusion of diagonal lines within stat/geom to mimic a landscape?
• example added to README
• use described in more detail in a ggtda vignette

Edit:

• add multiple persistence landscapes (exported function + shortcut stat)

To my knowledge, no {ggplot2} extension provides a statistical transformation layer to compute the nearest neighbors (NN) of (a subset of) the points in a 2-D cloud. For the following reasons, i think this should be added to {ggtda}:

• NN selection is a topological operation, so NN prediction is a topological tool (it is "within scope").
• A primary purpose of this package is to illustrate topological tools on 2-D data (it would fit in with existing functionality).
• NN engines might support future illustrative layers like neighborhood-based disks and witness complexes or even computational layers like witness complex--based persistent homology (it would support additional more obvious extensions).

I think this can wait until after the first CRAN submission, so i raise the issue as a reminder and to invite feedback.

We are close to our first submission to CRAN. I'd like to check with everyone on a few points first:

1. Does the package look complete, with respect to tests, examples, and vignettes?
2. Are there any open issues that you think should be resolved before submission?
3. Do you have any other concerns that should be discussed first?

Thanks! I'll tentatively plan to submit at the end of April, but we can take what time we need to address anything that comes up.

Betti curves are known to be unstable but are still commonly used to summarize patterns.

It might also make sense to provide the stabilized Betti curve of Johnson and Jung.

The vignettes include a great deal of front matter, the vast majority of it bibliographic. To make reading and editing the source code easier, would it make sense to maintain a single BibTeX (.bib) file with all references, which can then be cited in the vignettes? I haven't done this before so it may incur new issues, but i'd be glad to give it a try on a new branch. My point of reference is this chapter in the R Markdown Cookbook.

The persistence stat layers are currently paired by default to basic geom layers whose aesthetics are not ideal. We can create some convenience geom layers that simply use better default aesthetics but otherwise pass to the basic geoms. Start with an illustrative geom_disk() to pair with stat_disk().