ggmagnify

https://hughjonesd.github.io/ggmagnify/
Admin
ggmagnify creates a magnified inset of part of a ggplot object. The magnified area can be a...
Tokens:12,096
Snippets:107
Trust Score:9.7
Update:3 months ago
Show doc for...
Tokens:
Raw
### Install ggmagnify from GitHub

Source: https://hughjonesd.github.io/ggmagnify/index.html

Installs the development version of the ggmagnify package directly from its GitHub repository. Requires the 'remotes' package.

```r
# install.packages("remotes")
remotes::install_github("hughjonesd/ggmagnify")
```

--------------------------------

### Install ggmagnify from r-universe

Source: https://hughjonesd.github.io/ggmagnify/index.html

Installs the latest stable version of the ggmagnify package from the r-universe repository.

```r
install.packages("ggmagnify", repos = c("https://hughjonesd.r-universe.dev", 
                 "https://cloud.r-project.org"))
```

--------------------------------

### Create Inset with Custom Plot and Theme

Source: https://hughjonesd.github.io/ggmagnify/index.html

This example demonstrates creating a complex inset by explicitly defining the inset plot using the `plot` argument and customizing its theme with `inset_theme()`.

```r
booms <- ggplot(faithfuld, aes(waiting, eruptions)) + 
         geom_contour_filled(aes(z = density), bins = 50) + 
         scale_fill_viridis_d(option = "B") + 
         theme(legend.position = "none")

booms_inset <- booms + 
  geom_point(data = faithful, color = "red", fill = "white", alpha = 0.7, 
             size = 2, shape = "circle filled") + 
  coord_cartesian(expand = FALSE) + 
  inset_theme()

shadow.args <- list(
  colour = alpha("grey80", 0.8),
  x_offset = 0,
  y_offset = 0,
  sigma = 10
)

booms + geom_magnify(from = c(78, 90, 4.0, 4.8), to = c(70, 90, 1.7, 3.3),
                     colour = "white", shape = "ellipse",
                     shadow = TRUE, shadow.args = shadow.args,
                     plot = booms_inset)
```

--------------------------------

### Basic Magnification

Source: https://hughjonesd.github.io/ggmagnify/index.html

A simple example of magnifying a region with a shadow effect.

```r
ggp + geom_magnify(from = from, to = to, 
                   shadow = TRUE)
```

--------------------------------

### Apply inset theme to a ggplot with geom_magnify

Source: https://hughjonesd.github.io/ggmagnify/reference/inset_theme.html

This example demonstrates creating an inset plot using `geom_magnify` and applying a custom theme with blanked elements using `inset_theme` and `inset_blanks`.

```R
library(ggplot2)
ggp <- ggplot(iris, aes(Sepal.Width, Sepal.Length, colour = Species)) +
         geom_point() + xlim(c(2, 6))
from <- list(2.5, 3.5, 6, 7)
to <- list(4, 6, 5, 7)

blanks <- inset_blanks("panel.grid")
inset <- ggp + geom_density2d() + inset_theme(axes = "", blank = blanks)
ggp + geom_magnify(from = from, to = to, plot = inset)
```

--------------------------------

### Dual Magnification with Custom Styling

Source: https://hughjonesd.github.io/ggmagnify/index.html

This example shows how to apply two separate magnified regions to a single plot, each with distinct 'from' and 'to' coordinates and styling (color, line width).

```R
data <- data.frame(
  x = runif(4000), 
  y = runif(4000)
)
ggm_unif <- ggplot(data, aes(x, y)) +
            coord_cartesian(expand = FALSE) +
            geom_density2d_filled(bins = 50, linewidth = 0, n = 200) +
            geom_point(color='white', alpha = .5, size = .5) + 
            theme(legend.position = "none")


ggm_unif + 
  geom_magnify(from = c(0.05, 0.15, 0.05, 0.15), to = c(0.2, 0.4, 0.2, 0.4), 
               colour = "white", proj.linetype = 1, linewidth = 0.6) + 
  geom_magnify(from = c(0.25, 0.35, 0.25, 0.35), to = c(0.45, 0.85, 0.45, 0.85), 
               expand = 0, colour ="white", proj.linetype = 1)
```

--------------------------------

### Maintain Grid Lines in Inset

Source: https://hughjonesd.github.io/ggmagnify/index.html

This example demonstrates how to ensure the inset uses the same grid lines as the main plot by setting the `breaks` argument in `scale_x` and `scale_y`.

```r
ggp2 <- ggplot(iris, aes(Sepal.Width, Sepal.Length, color = Species)) + 
        geom_point() + 
        theme_classic() + 
        theme(panel.grid.major = element_line("grey80"),
              panel.grid.minor = element_line("grey90"))

# different grid lines:
ggp2 + 
  geom_magnify(from = c(2.45, 3.05, 5.9, 6.6), to = c(3.4, 4.4, 5.5, 6.6),
               shadow = TRUE)
```

--------------------------------

### Create a grob from a subset of sf data

Source: https://hughjonesd.github.io/ggmagnify/reference/grob_where.html

This example demonstrates how to use grob_where to create a grob for a specific state (Texas) from a larger sf object (USA map data). The grob is then used with geom_magnify to highlight and zoom into that region within a ggplot visualization.

```r
library(ggplot2)
if (requireNamespace("sf", quietly = TRUE) &&
  requireNamespace("maps", quietly = TRUE)) {
  usa <- sf::st_as_sf(maps::map("state", fill=TRUE, plot = FALSE))
  texas <- grob_where(ID == "texas", usa, crs = sf::st_crs(4326))
  ggplot(usa) + coord_sf(crs = sf::st_crs(4326)) + geom_sf() +
    geom_magnify(from = texas, to = c(-90, -70, 25, 35), colour = "red",
    aspect = "fixed", expand = 0)
}
#> Coordinate system already present.
#> ℹ Adding new coordinate system, which will replace the existing one.



```

--------------------------------

### Nested Magnification with Black Background Theme

Source: https://hughjonesd.github.io/ggmagnify/index.html

Illustrates creating an inset within an inset by passing a pre-defined magnified plot object to the 'plot' argument of geom_magnify. This example uses a custom theme with a black background.

```R
ggp <- data.frame(x = rnorm(1e5), y = rnorm(1e5), 
                  colour = sample(8L, 1e5, replace = TRUE)) |> 
  ggplot(aes(x = x, y = y, colour = factor(colour))) + 
  scale_color_brewer(type = "qual", palette = 2) + 
  geom_point(alpha = 0.12, size = 0.7) + 
  lims(x = c(-3,3), y = c(-3,3)) + 
  theme_classic() + theme(panel.grid = element_blank(), 
                          axis.line = element_blank(), 
                          plot.background = element_rect(fill = "black"),
                          panel.background = element_rect(fill = "black"),
                          title = element_text(colour = "white"),
                          legend.position = "none")

ggpm <- ggp + 
  lims(x = c(-0.3, 0.3), y = c(-0.3, 0.3)) + 
  geom_magnify(from = c(-0.03, 0.03, -0.03, 0.03),
               to = c(-0.3, -0.1, -0.3, -0.1),
               expand = FALSE, colour = "white")

```

```R
ggp + 
  geom_magnify(plot = ggpm, 
               from = c(-0.3, 0.3, -0.3, 0.3),
               to = c(-3, -1, -3, -1),
               expand = FALSE, colour = "white") +
  labs(title = "Normal data", 
       subtitle = "The distribution gets more uniform as you zoom in")

```

--------------------------------

### Draw Inset Outside Plot Region

Source: https://hughjonesd.github.io/ggmagnify/index.html

This example shows how to draw an inset plot outside the main plot area by setting `coord_cartesian(clip = "off")` and adjusting `plot.margin`.

```r
ggp + 
  coord_cartesian(clip = "off") + 
  theme(plot.margin = ggplot2::margin(10, 60, 10, 10)) + 
  geom_magnify(from = from, to = to + c(0.5e8, 0.5e8, 0, 0), 
               shadow = TRUE)
```

--------------------------------

### grob_where

Source: https://hughjonesd.github.io/ggmagnify/reference/index.html

Creates a grob (graphical object) from a subset of sf (simple features) data.

```APIDOC
## grob_where

### Description
Creates a grob from a subset of sf data.

### Method
Not applicable (R function)

### Endpoint
Not applicable (R function)

### Parameters
None explicitly documented for direct user invocation in this context.

### Request Example
Not applicable (R function)

### Response
Not applicable (R function)
```

--------------------------------

### Basic Inset Creation

Source: https://hughjonesd.github.io/ggmagnify/index.html

Creates a basic magnified inset using geom_magnify. Specify the 'from' area (xmin, xmax, ymin, ymax) and the 'to' destination for the inset. The names for 'from' and 'to' components are optional.

```r
library(ggplot2)
library(ggmagnify)

ggp <- ggplot(dv, aes(Position, NegLogP)) +
  geom_point(color = "darkblue", alpha = 0.8, size = 0.8) +
  labs(title = "GWAS p-values for cognitive function",
       subtitle = "Davies et al. (2018).", y = "-log(p)")

from <- c(xmin = 9.75e7, xmax = 9.95e7, ymin = 16, ymax = 28)
# Names xmin, xmax, ymin, ymax are optional:
to <- c(2e8 - 2e7, 2e8 + 2e7,10, 26)

ggp + geom_magnify(from = from, to = to)
```

--------------------------------

### inset_blanks

Source: https://hughjonesd.github.io/ggmagnify/reference/index.html

Creates blank theme elements, likely used in conjunction with inset_theme.

```APIDOC
## inset_blanks

### Description
Creates blank theme elements.

### Method
Not applicable (R function)

### Endpoint
Not applicable (R function)

### Parameters
None explicitly documented for direct user invocation in this context.

### Request Example
Not applicable (R function)

### Response
Not applicable (R function)
```

--------------------------------

### Magnification with Data Recomputation

Source: https://hughjonesd.github.io/ggmagnify/index.html

Demonstrates using the 'recompute = TRUE' argument to recalculate smoothers or densities within the magnified inset. This is useful when the inset should reflect a different data aggregation than the main plot.

```R
df <- data.frame(x = seq(-5, 5, length = 500), y = 0)
df$y[abs(df$x) < 1] <- sin(df$x[abs(df$x) < 1])
df$y <- df$y + rnorm(500, mean = 0, sd = 0.25)

ggp2 <- ggplot(df, aes(x, y)) + 
  geom_point() + 
  geom_smooth(method = "loess", formula = y ~ x) + 
  ylim(-5, 5)

# The default:
ggp2 + geom_magnify(from = c(-1.25, 1.25, -1, 1),
                    to = c(2, 5, 1, 5))

```

```R
# Recomputing recalculates the smooth for the inset:
ggp2 + geom_magnify(from = c(-1.25, 1.25, -1, 1),
                    to = c(2, 5, 1, 5),
                    recompute = TRUE)
```

--------------------------------

### Basic Magnification with geom_magnify

Source: https://hughjonesd.github.io/ggmagnify/reference/geom_magnify.html

Demonstrates basic usage of geom_magnify to create an inset plot. Requires ggplot2 and ggmagnify libraries.

```R
library(ggplot2)
ggp <- ggplot(iris, aes(Sepal.Width, Sepal.Length, colour = Species)) +
         geom_point() + xlim(c(2, 6))
from <- list(2.5, 3.5, 6, 7)
to <- list(4, 6, 5, 7)

# Basic magnification
ggp + geom_magnify(from = from, to = to)
```

--------------------------------

### inset_theme

Source: https://hughjonesd.github.io/ggmagnify/reference/index.html

Creates a theme suitable for an inset ggplot.

```APIDOC
## inset_theme

### Description
Creates a theme suitable for an inset ggplot.

### Method
Not applicable (R function)

### Endpoint
Not applicable (R function)

### Parameters
None explicitly documented for direct user invocation in this context.

### Request Example
Not applicable (R function)

### Response
Not applicable (R function)
```

--------------------------------

### Magnify Specific Points using Aesthetics

Source: https://hughjonesd.github.io/ggmagnify/index.html

Magnifies regions based on aesthetic mappings, allowing conditional selection of points to magnify.

```r
ggpi <- ggplot(iris, aes(Sepal.Width, Sepal.Length, colour = Species)) +
              geom_point() + xlim(c(1.5, 6))

gwpi + geom_magnify(aes(from = Species == "setosa" & Sepal.Length < 5), 
                    to = c(4, 6, 6, 7.5))
```

--------------------------------

### Create Inset Theme

Source: https://hughjonesd.github.io/ggmagnify/reference/index.html

Functions to create a theme suitable for an inset ggplot.

```r
inset_theme()
inset_blanks()
```

--------------------------------

### Apply Projection Fill with geom_magnify

Source: https://hughjonesd.github.io/ggmagnify/index.html

Use proj.fill to add a fill color between projection lines. Alpha transparency can be applied.

```r
ggpi + 
  geom_magnify(from = from2, to = to2,
               proj.fill = alpha("yellow", 0.2)) # fill between the lines
```

--------------------------------

### Create Grob from Subset

Source: https://hughjonesd.github.io/ggmagnify/reference/index.html

Function to create a graphical object (grob) from a subset of sf data.

```r
grob_where()
```

--------------------------------

### rect_around and hull_around

Source: https://hughjonesd.github.io/ggmagnify/reference/rect_around.html

These functions calculate the bounding rectangle or convex hull for a given set of x and y coordinates, optionally expanding the result. `rect_around` returns a list of min/max x and y values, while `hull_around` returns a data frame of points defining the convex hull.

```APIDOC
## rect_around and hull_around

### Description
Calculates the bounding rectangle or convex hull for a given set of x and y coordinates, optionally expanding the result. `rect_around` returns a list of min/max x and y values, while `hull_around` returns a data frame of points defining the convex hull.

### Usage
```
rect_around(x, y, data = NULL, expand = 0)
hull_around(x, y, data = NULL, expand = 0)
```

### Arguments

*   **x, y**: Unquoted names or expressions for the x and y coordinates.
*   **data**: A data frame containing the x and y variables.
*   **expand**: Amount to expand the data around its midpoint. Default is 10 per cent.

### Value
*   `rect_around()`: Returns a list with names `xmin`, `xmax`, `ymin`, and `ymax`.
*   `hull_around()`: Returns a data frame with columns `x` and `y`.

### Examples
```R
library(ggplot2)
to <- c(2, 4.5, 6, 8)
setosas <- iris[iris$Species == "setosa", ]
rect_around(Sepal.Width, Sepal.Length, data = setosas)
hull_around(Sepal.Width, Sepal.Length, data = setosas)
```
```

--------------------------------

### grob_where

Source: https://hughjonesd.github.io/ggmagnify/reference/grob_where.html

Creates a grob from a subset of sf data based on a logical condition. This function is useful for preparing specific spatial regions to be used with plotting functions like `geom_magnify`.

```APIDOC
## grob_where

### Description
Creates a grob from a subset of sf data.

### Usage
```R
grob_where(where, sf, crs = NULL)
```

### Arguments

*   `where` (Logical condition): A logical condition to be evaluated in `sf`.
*   `sf` (sf object): An object of class sf.
*   `crs` (Optional): Optional coordinate reference system.

### Value
A `grid::grob()` which can be passed to `from`.

### Examples
```R
library(ggplot2)
if (requireNamespace("sf", quietly = TRUE) &&
  requireNamespace("maps", quietly = TRUE)) {
  usa <- sf::st_as_sf(maps::map("state", fill=TRUE, plot = FALSE))
  texas <- grob_where(ID == "texas", usa, crs = sf::st_crs(4326))
  ggplot(usa) + coord_sf(crs = sf::st_crs(4326)) + geom_sf() + 
    geom_magnify(from = texas, to = c(-90, -70, 25, 35), colour = "red",
    aspect = "fixed", expand = 0)
}
```
```

--------------------------------

### Magnify Arbitrary Region with Outline Shape

Source: https://hughjonesd.github.io/ggmagnify/index.html

Magnifies the convex hull of a set of points using `shape = "outline"`. Includes custom shadow arguments and styling.

```r
library(dplyr)

starwars_plot <- starwars |> 
  mutate(Human = species == "Human") |> 
  select(mass, height, Human) |> 
  na.omit() |> 
  ggplot(aes(mass, height, color = Human)) + 
    geom_point() + xlim(0, 220) + ylim(0, 250) + 
    theme_dark() +
    theme(panel.grid = element_line(linetype = 2, colour = "yellow"), 
          axis.line = element_blank(), 
          panel.background = element_rect(fill = "black"),
          legend.key = element_rect(fill= "black"),
          rect = element_rect(fill = "black"),
          text = element_text(colour = "white")) +
    scale_colour_manual(values = c("TRUE" = "red", "FALSE" = "lightblue")) +
    ggtitle("Mass and height of Star Wars characters",
            subtitle = "Humans magnified")

starwars_plot +
  geom_magnify(aes(from = Human), to = c(30, 200, 0, 120), shadow = TRUE,
               shadow.args = list(colour = "yellow", sigma = 10,
                                  x_offset = 2, y_offset = 5),
               alpha = 0.8, colour = "yellow", linewidth = 0.6, 
               shape = "outline", expand = 0.2)
#> Warning: Removed 1 row containing missing values or values outside the scale range
#> (`geom_point()`).
```

--------------------------------

### GeomMagnify.Rd Internals

Source: https://hughjonesd.github.io/ggmagnify/reference/GeomMagnify.html

Internal documentation for the GeomMagnify R function.

```R
GeomMagnify.Rd
```

--------------------------------

### Magnification with Convex Hull Outline

Source: https://hughjonesd.github.io/ggmagnify/reference/geom_magnify.html

Shows how to use geom_magnify to create an inset plot with a convex hull outline based on a condition. The `shape = "outline"` argument is used for this purpose.

```R
ggp + geom_magnify(aes(from = Species == "setosa"), to = c(3, 5, 6, 8),
                   shape = "outline")
```

--------------------------------

### Customize Projection Line Appearance with geom_magnify

Source: https://hughjonesd.github.io/ggmagnify/index.html

Control the color and line width of projection lines, and set projection line type using proj.linetype.

```r
ggp + 
  geom_magnify(from = from, to = to,
               colour = "darkgreen", linewidth = 0.5, proj.linetype = 3)
```

--------------------------------

### inset_theme

Source: https://hughjonesd.github.io/ggmagnify/reference/inset_theme.html

Adds a suitable theme to a manually-created inset plot. It customizes the appearance of the inset to make it visually distinct and appropriate for its context.

```APIDOC
## inset_theme()

### Description
Use `inset_theme()` to add a suitable theme to a manually-created inset plot. Use `inset_blanks()` to customize the default list of elements to blank in the inset.

### Usage
```R
inset_theme(
  blank = inset_blanks(axes = axes),
  axes = c("", "x", "y", "xy"),
  margin = if (axes == "") 0 else 8
)
```

### Arguments

*   **blank** (Character vector) - Theme elements to blank. See `ggplot2::theme()`.
*   **axes** (String) - Which axes to plot in the inset? `""`, `"x"`, `"y"` or `"xy"`.
*   **margin** (Numeric) - Margin around the plot. See `plot.margin` in `ggplot2::theme()`.

### Value
`inset_theme()` returns a ggplot theme object.

### Examples
```R
library(ggplot2)
ggp <- ggplot(iris, aes(Sepal.Width, Sepal.Length, colour = Species)) +
         geom_point() + xlim(c(2, 6))
from <- list(2.5, 3.5, 6, 7)
to <- list(4, 6, 5, 7)

blanks <- inset_blanks("panel.grid")
inset <- ggp + geom_density2d() + inset_theme(axes = "", blank = blanks)
ggp + geom_magnify(from = from, to = to, plot = inset)
```
```

--------------------------------

### Create a ggplot theme for an inset plot

Source: https://hughjonesd.github.io/ggmagnify/reference/inset_theme.html

Use `inset_theme` to apply a theme to an inset plot. It allows customization of which elements are blanked and the margin around the plot.

```R
inset_theme(
  blank = inset_blanks(axes = axes),
  axes = c("", "x", "y", "xy"),
  margin = if (axes == "") 0 else 8
)
```

--------------------------------

### BibTeX Citation for ggmagnify

Source: https://hughjonesd.github.io/ggmagnify/authors.html

This BibTeX entry can be used to cite the ggmagnify R package in academic papers and other documents that use BibTeX for reference management.

```bibtex
@Manual{
  title = {ggmagnify: Create a Magnified Inset of Part of a "Ggplot" Object},
  author = {David Hugh-Jones},
  year = {2026},
  note = {R package version 0.4.2},
  url = {https://github.com/hughjonesd/ggmagnify},
}
```

--------------------------------

### Calculate bounding rectangle for data points

Source: https://hughjonesd.github.io/ggmagnify/reference/rect_around.html

Use `rect_around` to find the minimum and maximum x and y coordinates that enclose a given set of data points. Specify the data frame and the column names for x and y using unquoted expressions.

```R
library(ggplot2)
to <- c(2, 4.5, 6, 8)
setosas <- iris[iris$Species == "setosa", ]
rect_around(Sepal.Width, Sepal.Length, data = setosas)
```

--------------------------------

### Magnify Map Polygons with Outline Shape

Source: https://hughjonesd.github.io/ggmagnify/index.html

Magnifies specific map polygons using `shape = "outline"`. The `from` aesthetic is used to select polygons, and `aspect = "fixed"` is applied.

```r
usa <- sf::st_as_sf(maps::map("state", fill=TRUE, plot = FALSE))

ggpm <- ggplot(usa) +
          geom_sf(aes(fill = ID == "texas"), colour = "grey20") +
          coord_sf(default_crs = sf::st_crs(4326), ylim = c(10, 50)) + 
          theme(legend.position = "none") +
          scale_fill_manual(values = c("TRUE" = "red", "FALSE" = "steelblue4"))


ggpm + geom_magnify(aes(from = ID == "texas"),
                    to = c(-125, -98, 10, 30), 
                    shadow = TRUE, linewidth = 1, colour = "orange2",
                    shape = "outline", 
                    aspect = "fixed", 
                    expand = 0)
```

--------------------------------

### Basic Magnification with Custom Breaks

Source: https://hughjonesd.github.io/ggmagnify/index.html

This snippet shows how to add a magnified region to a ggplot with custom x and y axis breaks. The 'from' and 'to' arguments define the source and target regions for magnification.

```R
ggp2 + 
  scale_x_continuous(breaks = seq(2, 5, 0.5)) + 
  scale_y_continuous(breaks = seq(5, 8, 0.5)) + 
  geom_magnify(from = c(2.45, 3.05, 5.9, 6.6), to = c(3.4, 4.4, 5.5, 6.6),
               shadow = TRUE) 
```

--------------------------------

### Find Rectangles or Hulls

Source: https://hughjonesd.github.io/ggmagnify/reference/index.html

Helper functions to find rectangles or convex hulls of data.

```r
rect_around()
hull_around()
```

--------------------------------

### hull_around

Source: https://hughjonesd.github.io/ggmagnify/reference/index.html

Helper function to find convex hulls of data.

```APIDOC
## hull_around

### Description
Helper function to find convex hulls of data.

### Method
Not applicable (R function)

### Endpoint
Not applicable (R function)

### Parameters
None explicitly documented for direct user invocation in this context.

### Request Example
Not applicable (R function)

### Response
Not applicable (R function)
```

--------------------------------

### Magnification within Facets

Source: https://hughjonesd.github.io/ggmagnify/index.html

Demonstrates magnifying specific regions within facets of a plot. The `from` aesthetic is used to select points within each facet.

```r
ggpi +
  facet_wrap(vars(Species)) +
  geom_magnify(aes(from = Sepal.Length > 5 & Sepal.Length < 6.5), 
                    to = c(4.5, 6, 6, 7.5),
                    shadow = TRUE)
```

--------------------------------

### inset_blanks

Source: https://hughjonesd.github.io/ggmagnify/reference/inset_theme.html

Customizes the default list of theme elements to be blanked in an inset plot.

```APIDOC
## inset_blanks()

### Description
Use `inset_blanks()` to customize the default list of elements to blank in the inset.

### Usage
```R
inset_blanks(..., axes = c("", "x", "y", "xy"))
```

### Arguments

*   **...** (Character vector) - Extra elements to blank.
*   **axes** (String) - Which axes to plot in the inset? `""`, `"x"`, `"y"` or `"xy"`.

### Value
`inset_blanks()` returns a character vector of theme element names.

### Examples
```R
library(ggplot2)
ggp <- ggplot(iris, aes(Sepal.Width, Sepal.Length, colour = Species)) +
         geom_point() + xlim(c(2, 6))
from <- list(2.5, 3.5, 6, 7)
to <- list(4, 6, 5, 7)

blanks <- inset_blanks("panel.grid")
inset <- ggp + geom_density2d() + inset_theme(axes = "", blank = blanks)
ggp + geom_magnify(from = from, to = to, plot = inset)
```
```

--------------------------------

### geom_magnify

Source: https://hughjonesd.github.io/ggmagnify/reference/geom_magnify.html

`geom_magnify()` creates a magnified inset of part of a ggplot. Optional borders are drawn around the target and inset, along with projection lines from one to the other. `from` gives the location of the target area, and `to` gives the location of the inset. Usually, these are specified as `c(xmin, xmax, ymin, ymax)`.

```APIDOC
## geom_magnify()

### Description
Creates a magnified inset of part of a ggplot. Optional borders are drawn around the target and inset, along with projection lines from one to the other. `from` gives the location of the target area, and `to` gives the location of the inset. Usually, these are specified as `c(xmin, xmax, ymin, ymax)`.

### Usage
```R
geom_magnify(
  mapping = NULL,
  data = NULL,
  stat = StatMagnify,
  position = "identity",
  ...,
  shape = c("rect", "ellipse", "outline"),
  expand = 0.1,
  aspect = c("free", "fixed"),
  axes = "",
  proj = c("facing", "corresponding", "single"),
  shadow = FALSE,
  corners = 0,
  colour = "black",
  linetype = 1,
  target.linetype = linetype,
  inset.linetype = linetype,
  proj.linetype = 2,
  alpha = 1,
  linewidth = 0.4,
  proj.fill = NULL,
  plot = NULL,
  shadow.args = list(sigma = 5, colour = "grey40", x_offset = 5, y_offset = 5),
  recompute = FALSE,
  scale.inset = 1,
  proj.combine = TRUE,
  na.rm = FALSE,
  inherit.aes = TRUE
)
```

### Arguments
* `mapping`: Set of aesthetic mappings created by `aes()` or `aes_()`.
* `data`: A data frame.
* `stat`: The statistics to use for this layer. This can be a character string or the base class of a stat object, such as `Stat"identity"`.
* `position`: Position adjustment, either as a string, or the result of a call to a position adjustment function.
* `...`: Other arguments passed on to `layer()`.
* `shape`: Shape of the target and inset borders. One of "rect", "ellipse", or "outline".
* `expand`: Expansion factor for the inset area.
* `aspect`: Aspect ratio of the inset. Either "free" or "fixed".
* `axes`: Which axes to draw for the inset. Can be "x", "y", or "xy".
* `proj`: Type of projection lines from target to inset. One of "facing", "corresponding", or "single".
* `shadow`: If TRUE, add a shadow effect to the inset.
* `corners`: Number of corners to use for the projection lines.
* `colour`: Colour of the borders and projection lines.
* `linetype`: Linetype of the borders and projection lines.
* `target.linetype`: Linetype for the target border.
* `inset.linetype`: Linetype for the inset border.
* `proj.linetype`: Linetype for the projection lines.
* `alpha`: Transparency of the inset.
* `linewidth`: Thickness of the borders and projection lines.
* `proj.fill`: Fill colour for the projection lines.
* `plot`: The plot object to magnify.
* `shadow.args`: List of arguments for the shadow effect.
* `recompute`: If TRUE, recompute the inset area.
* `scale.inset`: Scaling factor for the inset.
* `proj.combine`: If TRUE, combine projection lines.
* `na.rm`: If TRUE, remove missing values.
* `inherit.aes`: If FALSE, overrides the default aesthetics.

### Details
This geom is useful for highlighting specific regions of a plot in an inset window.
```

--------------------------------

### Define inset theme elements to blank

Source: https://hughjonesd.github.io/ggmagnify/reference/inset_theme.html

Use `inset_blanks` to specify which theme elements should be blanked in an inset plot. This function returns a character vector of theme element names.

```R
inset_blanks(axes = c("", "x", "y", "xy"))
```

--------------------------------

### geom_magnify_tile Function Signature

Source: https://hughjonesd.github.io/ggmagnify/reference/geom_magnify.html

Defines the geom_magnify_tile function, a variant for creating magnified insets, potentially with tile-based behavior. It shares many parameters with geom_magnify.

```R
geom_magnify_tile(
  mapping = NULL,
  data = NULL,
  stat = StatMagnifyTile,
  position = "identity",
  ...,
  shape = c("rect", "ellipse", "outline"),
  expand = 0.1,
  aspect = c("free", "fixed"),
  axes = "",
  proj = "facing",
  shadow = FALSE,
  corners = 0,
  colour = "black",
  linetype = 1,
  target.linetype = linetype,
  inset.linetype = linetype,
  proj.linetype = 2,
  alpha = 1,
  linewidth = 0.4,
  proj.fill = NULL,
  plot = NULL,
  shadow.args = list(sigma = 5, colour = "grey40", x_offset = 5, y_offset = 5),
  recompute = FALSE,
  scale.inset = 1,
  proj.combine = TRUE,
  na.rm = FALSE,
  inherit.aes = FALSE
)
```

--------------------------------

### Magnification with Rounded Corners

Source: https://hughjonesd.github.io/ggmagnify/index.html

Applies rounded corners to the magnified region. The `corners` argument controls the proportional radius.

```r
ggp + geom_magnify(from = from, to = to, 
                   corners = 0.1, shadow = TRUE)
```

--------------------------------

### geom_magnify_tile

Source: https://hughjonesd.github.io/ggmagnify/reference/geom_magnify.html

`geom_magnify_tile()` creates a magnified inset of part of a ggplot, similar to `geom_magnify()`, but optimized for tiling.

```APIDOC
## geom_magnify_tile()

### Description
Creates a magnified inset of part of a ggplot, similar to `geom_magnify()`, but optimized for tiling.

### Usage
```R
geom_magnify_tile(
  mapping = NULL,
  data = NULL,
  stat = StatMagnifyTile,
  position = "identity",
  ...,
  shape = c("rect", "ellipse", "outline"),
  expand = 0.1,
  aspect = c("free", "fixed"),
  axes = "",
  proj = "facing",
  shadow = FALSE,
  corners = 0,
  colour = "black",
  linetype = 1,
  target.linetype = linetype,
  inset.linetype = linetype,
  proj.linetype = 2,
  alpha = 1,
  linewidth = 0.4,
  proj.fill = NULL,
  plot = NULL,
  shadow.args = list(sigma = 5, colour = "grey40", x_offset = 5, y_offset = 5),
  recompute = FALSE,
  scale.inset = 1,
  proj.combine = TRUE,
  na.rm = FALSE,
  inherit.aes = FALSE
)
```

### Arguments
* `mapping`: Set of aesthetic mappings created by `aes()` or `aes_()`.
* `data`: A data frame.
* `stat`: The statistics to use for this layer. This can be a character string or the base class of a stat object, such as `Stat"identity"`.
* `position`: Position adjustment, either as a string, or the result of a call to a position adjustment function.
* `...`: Other arguments passed on to `layer()`.
* `shape`: Shape of the target and inset borders. One of "rect", "ellipse", or "outline".
* `expand`: Expansion factor for the inset area.
* `aspect`: Aspect ratio of the inset. Either "free" or "fixed".
* `axes`: Which axes to draw for the inset. Can be "x", "y", or "xy".
* `proj`: Type of projection lines from target to inset. "facing" is the default.
* `shadow`: If TRUE, add a shadow effect to the inset.
* `corners`: Number of corners to use for the projection lines.
* `colour`: Colour of the borders and projection lines.
* `linetype`: Linetype of the borders and projection lines.
* `target.linetype`: Linetype for the target border.
* `inset.linetype`: Linetype for the inset border.
* `proj.linetype`: Linetype for the projection lines.
* `alpha`: Transparency of the inset.
* `linewidth`: Thickness of the borders and projection lines.
* `proj.fill`: Fill colour for the projection lines.
* `plot`: The plot object to magnify.
* `shadow.args`: List of arguments for the shadow effect.
* `recompute`: If TRUE, recompute the inset area.
* `scale.inset`: Scaling factor for the inset.
* `proj.combine`: If TRUE, combine projection lines.
* `na.rm`: If TRUE, remove missing values.
* `inherit.aes`: If FALSE, overrides the default aesthetics.
```

--------------------------------

### Set Projection Mode to 'corresponding' with geom_magnify

Source: https://hughjonesd.github.io/ggmagnify/index.html

Use proj = 'corresponding' to always project corner to corner. Requires ggplot2.

```r
ggpi + 
  geom_magnify(from = from2, to = to2,
               proj = "corresponding") # always project corner to corner
```

--------------------------------

### Calculate convex hull for data points

Source: https://hughjonesd.github.io/ggmagnify/reference/rect_around.html

Use `hull_around` to compute the convex hull of a set of data points, returning a data frame with the x and y coordinates of the hull vertices. Specify the data frame and the column names for x and y using unquoted expressions.

```R
library(ggplot2)
to <- c(2, 4.5, 6, 8)
setosas <- iris[iris$Species == "setosa", ]
hull_around(Sepal.Width, Sepal.Length, data = setosas)
```

--------------------------------

### Create Magnified Inset

Source: https://hughjonesd.github.io/ggmagnify/reference/index.html

Functions to create a magnified inset of a plot.

```r
geom_magnify()
geom_magnify_tile()
```

--------------------------------

### Add Layers to Inset Plot with geom_magnify

Source: https://hughjonesd.github.io/ggmagnify/index.html

Layers added before geom_magnify will appear in the inset plot. Ensure R version 4.1.0+ and a masking-compatible graphics device.

```r
ggpi <- ggplot(iris, aes(Sepal.Width, Sepal.Length, colour = Species)) +
              geom_point() + xlim(2, 6)

from3 <-  c(2.5, 3.5, 6, 7)
to3 <- c(4.7, 6.1, 4.3, 5.7)
ggpi + 
  geom_smooth() + 
  geom_magnify(from = from3, to = to3)
```

--------------------------------

### Order of Operations in geom_magnify

Source: https://hughjonesd.github.io/ggmagnify/reference/geom_magnify.html

Illustrates how the order of adding layers affects the final plot when using geom_magnify with other ggplot2 elements like scale adjustments. Storing the plot object before adding geom_magnify is shown.

```R
# Order matters

# `geom_magnify()` stores the plot when it is added to it:
ggp +
  scale_color_brewer() +
  geom_magnify(from = from, to = to)
```

```R
# This will print the inset without the new scale:
ggp +
  geom_magnify(from = from, to = to) +
  scale_color_brewer()
```

--------------------------------

### rect_around

Source: https://hughjonesd.github.io/ggmagnify/reference/index.html

Helper function to find rectangles around data.

```APIDOC
## rect_around

### Description
Helper function to find rectangles of data.

### Method
Not applicable (R function)

### Endpoint
Not applicable (R function)

### Parameters
None explicitly documented for direct user invocation in this context.

### Request Example
Not applicable (R function)

### Response
Not applicable (R function)
```

--------------------------------

### Set Projection Mode to 'facing' with geom_magnify

Source: https://hughjonesd.github.io/ggmagnify/index.html

The default projection mode 'facing' projects the specified 'from' and 'to' coordinates. Requires ggplot2.

```r
ggpi + 
  geom_magnify(from = from2, to = to2,
               proj = "facing") # the default
```

--------------------------------

### Magnify Arbitrary Shape using Grob or Data Frame

Source: https://hughjonesd.github.io/ggmagnify/index.html

Magnifies a region defined by a grid grob object or a data frame. The `aspect = "fixed"` argument maintains the aspect ratio.

```r
s <- seq(0, 2*pi, length = 7)
hex <- data.frame(x = 3 + sin(s)/2, y = 6 + cos(s)/2) 

gwpi + geom_magnify(from = hex, 
                    to = c(4, 6, 5, 7), shadow = TRUE, aspect = "fixed")
```

--------------------------------

### geom_magnify_tile

Source: https://hughjonesd.github.io/ggmagnify/reference/index.html

A function related to creating magnified insets, likely used in conjunction with geom_magnify.

```APIDOC
## geom_magnify_tile

### Description
Related to creating magnified insets.

### Method
Not applicable (R function)

### Endpoint
Not applicable (R function)

### Parameters
None explicitly documented for direct user invocation in this context.

### Request Example
Not applicable (R function)

### Response
Not applicable (R function)
```

--------------------------------

### Magnification with Ellipse Shape

Source: https://hughjonesd.github.io/ggmagnify/index.html

Uses an ellipse shape for the magnified region. Requires R 4.1 or higher and an appropriate graphics device.

```r
ggp + geom_magnify(from = from, to = to, 
                   shape = "ellipse", shadow = TRUE)
```

--------------------------------

### GeomMagnify Internals

Source: https://hughjonesd.github.io/ggmagnify/reference/index.html

Internal geom for creating magnified plot insets.

```r
GeomMagnify
```

--------------------------------

### Set Projection Mode to 'single' with geom_magnify

Source: https://hughjonesd.github.io/ggmagnify/index.html

Use proj = 'single' to draw only one projection line. Requires ggplot2.

```r
ggpi + 
  geom_magnify(from = from2, to = to2,
               proj = "single") # just one line
```

--------------------------------

### Projection Fill with Different Shapes in geom_magnify

Source: https://hughjonesd.github.io/ggmagnify/index.html

Projection fill works with various shapes, including ellipses. Requires ggplot2.

```r
ggpi + 
  geom_magnify(from = from2, to = to2, shape = "ellipse",
               proj.fill = alpha("orange", 0.2)) # works with any shape
```

--------------------------------

### Hide X-axis Labels with geom_magnify

Source: https://hughjonesd.github.io/ggmagnify/index.html

Use scale_x_continuous(labels = NULL) to hide x-axis labels when using geom_magnify.

```r
ggp + 
  scale_x_continuous(labels = NULL) + 
  geom_magnify(from = from, to = to,
               axes = "xy")
```

--------------------------------

### geom_magnify

Source: https://hughjonesd.github.io/ggmagnify/reference/index.html

Creates a magnified inset of a plot, allowing users to zoom into specific areas of a ggplot visualization.

```APIDOC
## geom_magnify

### Description
Creates a magnified inset of a plot.

### Method
Not applicable (R function)

### Endpoint
Not applicable (R function)

### Parameters
None explicitly documented for direct user invocation in this context.

### Request Example
Not applicable (R function)

### Response
Not applicable (R function)
```

--------------------------------

### geom_magnify Function Signature

Source: https://hughjonesd.github.io/ggmagnify/reference/geom_magnify.html

Defines the geom_magnify function, used to create a magnified inset of a plot. It specifies parameters for the target area, inset location, and visual styling.

```R
geom_magnify(
  mapping = NULL,
  data = NULL,
  stat = StatMagnify,
  position = "identity",
  ...,
  shape = c("rect", "ellipse", "outline"),
  expand = 0.1,
  aspect = c("free", "fixed"),
  axes = "",
  proj = c("facing", "corresponding", "single"),
  shadow = FALSE,
  corners = 0,
  colour = "black",
  linetype = 1,
  target.linetype = linetype,
  inset.linetype = linetype,
  proj.linetype = 2,
  alpha = 1,
  linewidth = 0.4,
  proj.fill = NULL,
  plot = NULL,
  shadow.args = list(sigma = 5, colour = "grey40", x_offset = 5, y_offset = 5),
  recompute = FALSE,
  scale.inset = 1,
  proj.combine = TRUE,
  na.rm = FALSE,
  inherit.aes = TRUE
)
```
Tokens:
Raw