DOCSEARCHbyAlgolia
Submit Docs

eulerr R Package

repository·main·Indexed 41 days ago

https://github.com/jolars/eulerr

An R package for generating area-proportional Euler diagrams using circles or ellipses. It utilizes the Eunoia numerical optimization engine to approximate set relationships when exact diagrams are mathematically impossible, providing goodness-of-fit statistics such as stress and diagonal error. The package includes functions for fitting diagrams via euler(), calculating plot data, and placing region and set labels.

Tokens
3.4K
Snippets
5
Records
17
Agent score
50%

What's inside eulerr

  1. Overview of eulerr

    main

    eulerr is an R package used to generate area-proportional Euler diagrams. These diagrams display set relationships (intersections, unions, and disjoints) using circles or ellipses.

    Unlike Venn diagrams, Euler diagrams do not require all possible set interactions to be present. When exact diagrams are impossible (common with three or more intersecting sets), eulerr uses numerical tuning to approximate the diagram by minimizing error. The package provides goodness-of-fit statistics to help users determine if the resulting approximation is reliable.

  2. Eunoia Ecosystem: Cross-language availability

    main

    eulerr is based on Eunoia, a Rust library for fitting and visualizing Euler and Venn diagrams. The fitting engine is available in several other languages:

    LanguagePackageInstall Command
    Pythoneunoiapip install eunoia
    JuliaEunoia.jl] add Eunoia
    JavaScript@jolars/eunoianpm install @jolars/eunoia
    Rusteunoiacargo add eunoia

  3. Install eulerr

    main

    You can install eulerr via CRAN for the stable version, or via GitHub for the development version.

    Note on building from source: If you are building from source, a Rust toolchain is required. The minimum supported rustc version is 1.88.0. You can install or update Rust via rustup. CRAN binary builds do not require a local Rust toolchain.

    # CRAN version
install.packages("eulerr")

# Development Version
devtools::install_github("jolars/eulerr")

  4. Understand the Euler Diagram Result Schema

    main

    The fit_euler_diagram function returns a list containing the fitted parameters and error metrics. The schema is designed to be "wide" to accommodate different shapes using NaN padding for irrelevant fields.

    Set Parameters (Vectors of length n_sets):

    • h, k: Center coordinates (x, y).
    • a, b: Semi-axes (for Ellipse/Circle).
    • phi: Rotation angle (for Ellipse/RotatedRectangle).
    • width, height: Dimensions (for Rectangle/Square/RotatedRectangle).
    • side: Side length (for Square).

    Combination/Metric Data (Vectors of length n_combinations):

    • combo_labels: String labels for combinations (e.g., "A&B").
    • original_values: The requested areas.
    • fitted_values: The areas achieved by the fit.
    • residuals: Difference between original and fitted.
    • region_error: Error specifically in region areas.
    • diag_error: Diagonal error metric.
    • stress: Stress metric.

    Metadata:

    • all_set_names: Names of all sets involved.
    • fitted_set_names: Names of sets that are non-empty in the fit.
    • has_container: Boolean indicating if a bounding container was used.

  5. Inspect goodness-of-fit and plot Euler diagrams

    main

    After fitting a diagram with euler(), you can inspect the quality of the approximation using the following metrics:

    • $stress: The stress value of the solution.
    • $diagError: The diagonal error.

    You can visualize the resulting diagram using the standard plot() function.

    # Inspect goodness-of-fit
fit$stress
fit$diagError

# Plot the diagram
plot(fit)

  6. Use the euler() function to fit diagrams

    main

    The core function euler() takes a named numeric vector representing set sizes and intersections. You can specify the shape of the sets (e.g., "ellipse" or "circle").

    Intersections are specified using the & operator in the names (e.g., "A&B").

    library(eulerr)

set.seed(26)

# Fit an Euler diagram using an ellipse shape
fit <- euler(
  c(
    "A" = 4,
    "B" = 6,
    "C" = 3,
    "D" = 2,
    "E" = 7,
    "F" = 3,
    "A&B" = 2,
    "A&F" = 2,
    "B&C" = 2,
    "B&D" = 1,
    "B&F" = 2,
    "C&D" = 1,
    "D&E" = 1,
    "E&F" = 1,
    "A&B&F" = 1,
    "B&C&D" = 1
  ),
  shape = "ellipse"
)

  7. Pack rectangular glyph boxes with place_euler_glyph_boxes

    main

    Packs measured rectangular boxes (e.g., for text or icons) inside exclusive regions.

    Parameters:

    • item_widths / item_heights: Dimensions of the boxes to be packed.
    • arrangement: The packing pattern.
    • scale: Scaling factor for the boxes.
    • min_scale: Minimum allowable scale.
    • gap: Minimum distance between boxes.

    Output Fields:

    • scale: The actual scale used.
    • h / k / width / height: The center and dimensions of each placed box.
    • id_lengths: Number of boxes placed per region.
    • unplaced: Number of boxes that could not be placed per region.

  8. Generate Venn layout with venn_layout

    main

    Returns per-set geometry for a canonical (non-proportional) Venn diagram. This is used when a true Venn layout is required rather than a fitted Euler diagram.

    Supported Shapes:

    • "rotated_rectangle": Supports 1 to 4 sets. The rotation allows for all 15 possible regions to be opened, which is impossible with axis-aligned rectangles.

    Output Fields:

    • h, k, width, height, phi: Geometric parameters for each set's rectangle.

  9. Compute Euler diagram plot data with euler_plot_data

    main

    Computes polygon geometry and label anchors for plotting a fitted Euler diagram. It handles set shapes (circles, ellipses, rectangles, or squares) and can optionally include a complement region if a container (universe-box) is provided.

    Shape parameter mapping:

    • "circle" or "ellipse": uses (h, k, a, b, phi)
    • "rectangle": uses (h, k, width, height)
    • "square": uses (h, k, side)

    Output Fields:

    • set_polygons: List of polygons for each set.
    • region_labels: Labels for each region (e.g., "A&B").
    • region_polygons: Polygons for each region.
    • region_centers_x / region_centers_y: Anchor points for labels.
    • has_complement: Boolean indicating if a container was provided.
    • complement_polygon: Geometry for the area inside the container but outside all sets.
    • complement_label_x / complement_label_y: Anchor for the complement label.
    • container_outline_x / container_outline_y: Coordinates for the container boundary.
    // Note: This is an internal R-interface function (extendr).
// It expects vectors for shape parameters (h, k, a, b, phi, width, height, side)
// corresponding to the provided `shape` type.

  10. Pack circular glyphs with place_euler_glyphs

    main

    Packs equal-sized circular glyphs inside exclusive regions of the Euler diagram.

    Parameters:

    • arrangement: The packing pattern (e.g., via parse_glyph_arrangement).
    • radius: The radius of the glyphs.
    • gap: Minimum distance between glyphs.
    • seed: Random seed for deterministic placement.
    • max_attempts: Number of attempts to find a valid packing.

    Output Fields:

    • radius: The actual radius used.
    • x / y: Coordinates of the placed glyphs.
    • id_lengths: Number of glyphs placed in each requested region.
    • unplaced: Number of glyphs that could not be placed in each region.

  11. Place region labels with place_euler_labels

    main

    Calculates optimal positions for labels within Euler diagram regions. It supports various placement strategies and handles leader lines (tethers) for exterior labels.

    Placement Strategies (placement):

    • "interior"
    • "exterior_raycast"
    • "exterior_force_directed"
    • "exterior_elbow"
    • "exterior_matched"

    Output Fields:

    • anchor_x / anchor_y: The coordinates where the label should be placed.
    • kind: The strategy used (e.g., "interior", "exterior_elbow").
    • tether_x / tether_y: The point on the region where the leader line starts.
    • leader_end_x / leader_end_y: The point on the label box where the leader line terminates.
    • leader_waypoints_x / leader_waypoints_y / leader_waypoints_lengths: Coordinates for non-straight leader lines (e.g., elbow paths).
    • canvas_bbox_h / canvas_bbox_k / canvas_bbox_width / canvas_bbox_height: The bounding box of all placements, used to expand plot limits so exterior labels aren't clipped.

  12. Convert Polygons and Region Pieces to XY lists

    main

    For plotting purposes, the Rust implementation provides utilities to flatten geometric data into a format compatible with R's grid package (specifically grid::pathGrob).

    • polygons_to_xy_list: Flattens a collection of Polygon objects into three vectors: x (coordinates), y (coordinates), and id_lengths (number of vertices per polygon). This is used for drawing edges.
    • region_pieces_to_xy_list: Flattens RegionPiece objects (which consist of an outer ring and zero or more holes) into x, y, and id_lengths. Outer rings are normalized to CCW and holes to CW to ensure correct rendering using the winding rule.