Struct ScatterMap 

pub struct ScatterMap { /* private fields */ }

A structure representing a scatter plot on a map.

The ScatterMap struct allows for visualizing geographical data points on an interactive map. Each data point is defined by its latitude and longitude, with additional options for grouping, coloring, size, opacity, and map configuration such as zoom level and center coordinates. This struct is ideal for displaying spatial data distributions, such as city locations or geospatial datasets.

Backend Support

Backend	Supported
Plotly	Yes
Plotters	–

Arguments

• data - A reference to the DataFrame containing the data to be plotted.
• latitude - A string slice specifying the column name containing latitude values.
• longitude - A string slice specifying the column name containing longitude values.
• center - An optional array [f64; 2] specifying the initial center point of the map ([latitude, longitude]).
• zoom - An optional u8 specifying the initial zoom level of the map.
• group - An optional string slice specifying the column name for grouping data points (e.g., by city or category).
• sort_groups_by - Optional comparator fn(&str, &str) -> std::cmp::Ordering to control group ordering. Groups are sorted lexically by default.
• opacity - An optional f64 value between 0.0 and 1.0 specifying the opacity of the points.
• size - An optional usize specifying the size of the scatter points.
• color - An optional Rgb value specifying the color of the points (if no grouping is applied).
• colors - An optional vector of Rgb values specifying colors for grouped points.
• shape - An optional Shape enum specifying the marker shape for the points.
• shapes - An optional vector of Shape enums specifying shapes for grouped points.
• plot_title - An optional Text struct specifying the title of the plot.
• legend_title - An optional Text struct specifying the title of the legend.
• legend - An optional reference to a Legend struct for customizing the legend (e.g., positioning, font, etc.).

Example

Basic Scatter Map Plot

use plotlars::{Plot, ScatterMap, Text};
use polars::prelude::*;

let dataset = LazyCsvReader::new(PlRefPath::new("data/cities.csv"))
    .finish()
    .unwrap()
    .collect()
    .unwrap();

ScatterMap::builder()
    .data(&dataset)
    .latitude("latitude")
    .longitude("longitude")
    .center([48.856613, 2.352222])
    .zoom(4)
    .group("city")
    .opacity(0.5)
    .size(12)
    .plot_title(
        Text::from("Scatter Map")
            .font("Arial")
            .size(18)
    )
    .legend_title("cities")
    .build()
    .plot();

Implementations

impl ScatterMap

pub fn builder<'f1, 'f2, 'f3, 'f4, 'f5>() -> ScatterMapBuilder<'f1, 'f2, 'f3, 'f4, 'f5>

Examples found in repository

examples/plotly_scattermap.rs (line 6)

fn main() {
    let dataset = CsvReader::new("data/cities.csv").finish().unwrap();

    ScatterMap::builder()
        .data(&dataset)
        .latitude("latitude")
        .longitude("longitude")
        .center([48.856613, 2.352222])
        .zoom(4)
        .group("city")
        .opacity(0.5)
        .size(12)
        .plot_title(Text::from("Scatter Map").font("Arial").size(18))
        .legend_title("cities")
        .build()
        .plot();
}

examples/plotly_subplot_grid.rs (line 312)

fn mixed_grid_example() {
    // 2D cartesian scatter (baseline)
    let penguins = CsvReader::new("data/penguins.csv")
        .finish()
        .unwrap()
        .lazy()
        .select([
            col("species"),
            col("bill_length_mm"),
            col("flipper_length_mm"),
            col("body_mass_g"),
        ])
        .collect()
        .unwrap();

    let scatter_2d = ScatterPlot::builder()
        .data(&penguins)
        .x("bill_length_mm")
        .y("flipper_length_mm")
        .group("species")
        .opacity(0.65)
        .size(10)
        .plot_title(Text::from("Penguins 2D").y(1.3))
        .build();

    // 3D scene subplot
    let scatter_3d = Scatter3dPlot::builder()
        .data(&penguins)
        .x("bill_length_mm")
        .y("flipper_length_mm")
        .z("body_mass_g")
        .group("species")
        .opacity(0.35)
        .size(6)
        .plot_title(Text::from("Penguins 3D").y(1.45))
        .build();

    // Polar subplot
    let polar_df = CsvReader::new("data/product_comparison_polar.csv")
        .finish()
        .unwrap();

    let polar = ScatterPolar::builder()
        .data(&polar_df)
        .theta("angle")
        .r("score")
        .group("product")
        .mode(Mode::LinesMarkers)
        .size(10)
        .plot_title(Text::from("Product Comparison (Polar)").y(1.5).x(0.72))
        .legend(&Legend::new().x(0.8))
        .build();

    // Domain-based subplot (Sankey)
    let sankey_df = CsvReader::new("data/energy_transition.csv")
        .finish()
        .unwrap();

    let sankey = SankeyDiagram::builder()
        .data(&sankey_df)
        .sources("source")
        .targets("target")
        .values("value")
        .orientation(Orientation::Horizontal)
        .arrangement(Arrangement::Freeform)
        .plot_title(Text::from("Energy Flow").y(1.2))
        .build();

    // Mapbox subplot
    let map_df = CsvReader::new("data/cities.csv").finish().unwrap();

    let scatter_map = ScatterMap::builder()
        .data(&map_df)
        .latitude("latitude")
        .longitude("longitude")
        .group("city")
        .zoom(4)
        .center([50.0, 5.0])
        .opacity(0.8)
        .plot_title(Text::from("Cities (Mapbox)").y(1.2))
        .build();

    // Geo subplot
    let geo_df = CsvReader::new("data/world_cities.csv").finish().unwrap();

    let scatter_geo = ScatterGeo::builder()
        .data(&geo_df)
        .lat("lat")
        .lon("lon")
        .group("continent")
        .mode(Mode::Markers)
        .size(10)
        .color(Rgb(255, 140, 0))
        .shape(Shape::Circle)
        .plot_title(Text::from("Global Cities (Geo)").x(0.65).y(1.2))
        .legend(&Legend::new().x(0.8))
        .build();

    SubplotGrid::regular()
        .plots(vec![
            &scatter_2d,
            &scatter_3d,
            &polar,
            &sankey,
            &scatter_map,
            &scatter_geo,
        ])
        .rows(2)
        .cols(3)
        .h_gap(0.12)
        .v_gap(0.22)
        .title(
            Text::from("Mixed Subplot Grid")
                .size(16)
                .font("Arial Black")
                .y(0.95),
        )
        .build()
        .plot();
}

impl ScatterMap

pub fn try_new( data: &DataFrame, latitude: &str, longitude: &str, center: Option<[f64; 2]>, zoom: Option<u8>, group: Option<&str>, sort_groups_by: Option<fn(&str, &str) -> Ordering>, opacity: Option<f64>, size: Option<usize>, color: Option<Rgb>, colors: Option<Vec<Rgb>>, shape: Option<Shape>, shapes: Option<Vec<Shape>>, plot_title: Option<Text>, legend_title: Option<Text>, legend: Option<&Legend>, ) -> Result<ScatterMap, PlotlarsError>

pub fn try_builder<'f1, 'f2, 'f3, 'f4, 'f5>() -> ScatterMapTryBuilder<'f1, 'f2, 'f3, 'f4, 'f5>

Trait Implementations

impl Clone for ScatterMap

fn clone(&self) -> ScatterMap

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Plot for ScatterMap

fn ir_traces(&self) -> &[TraceIR]

fn ir_layout(&self) -> &LayoutIR