Box plot | ArcGIS Maps SDK for JavaScript

Box plots visualize the distribution of data and identify outliers. They provide a summary of a dataset by displaying its minimum, first quartile, median, third quartile, and maximum values.

To render a basic box plot, you will need to provide a numeric field by using the numericFields property. Variations of the box plot can be created, such as:

With one numeric field:
- When one numeric field is specified via the numericFields property, a single box plot will be created to show the overall distribution of the numeric field.
- With a category field specified via the category property, box plots will be created for each category, allowing for comparison across different groups.
- With a split-by field specified via the splitByField property, box plots will be created for each unique value in the split-by field, allowing for comparison across different groups.
- With a category field specified via the category property and a split-by field specified via the splitByField property, box plots will be created for each combination of category and split-by values, allowing for a more detailed comparison across groups.
With multiple numeric fields:
- When multiple numeric fields are specified via the numericFields property, box plots will be created for each numeric field, allowing for comparison of distributions across different numeric variables.
- With a category field specified via the category property, box plots will be created for each category and numeric field combination, allowing for comparison of distributions across different groups and numeric variables.
- With a split-by field specified via the splitByField property, box plots will be created for each split-by value and numeric field combination, allowing for comparison of distributions across different groups and numeric variables.

In this tutorial, you will create and customize a box plot using box plot model and render it with the <arcgis-chart> component.

Prerequisites

Steps

Create a new pen

Go to CodePen to create a new pen for your application.

Add basic HTML

Define a basic HTML page.

In CodePen > HTML, add HTML to create a basic page.

<html>

<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no" />
  <title>
    ArcGIS Maps SDK for JavaScript Tutorials: Box plot
  </title>

  <style>
    html,
    body,
    arcgis-chart {
      height: 100%;
      margin: 0;
    }
  </style>

</head>


<body>

</body>


</html>

Add the ArcGIS Maps SDK for JavaScript script tag

In the <head>, add the <script> tag for the JavaScript Maps SDK.

9 collapsed lines
<html>

<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no" />
  <title>
    ArcGIS Maps SDK for JavaScript Tutorials: Box plot
  </title>

  <style>
    html,
    body,
    arcgis-chart {
      height: 100%;
      margin: 0;
    }
  </style>

  <!-- Load the ArcGIS Maps SDK for JavaScript from CDN -->
  <script type="module" src="https://js.arcgis.com/5.0/"></script>
5 collapsed lines

</head>


</html>

Add chart component

In the <body> tag, add the <arcgis-chart> component.

23 collapsed lines
<html>

<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no" />
  <title>
    ArcGIS Maps SDK for JavaScript Tutorials: Box plot
  </title>

  <style>
    html,
    body,
    arcgis-chart {
      height: 100%;
      margin: 0;
    }
  </style>

  <!-- Load the ArcGIS Maps SDK for JavaScript from CDN -->
  <script type="module" src="https://js.arcgis.com/5.0/"></script>

</head>


<body>

  <arcgis-chart></arcgis-chart>

</body>
3 collapsed lines


</html>

Component reference (chart)

Add logic to create a chart

Within the <body> tag, add a <script> tag with type="module" to write JavaScript code to create a chart with charts model.

28 collapsed lines
<html>

<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no" />
  <title>
    ArcGIS Maps SDK for JavaScript Tutorials: Box plot
  </title>

  <style>
    html,
    body,
    arcgis-chart {
      height: 100%;
      margin: 0;
    }
  </style>

  <!-- Load the ArcGIS Maps SDK for JavaScript from CDN -->
  <script type="module" src="https://js.arcgis.com/5.0/"></script>

</head>


<body>

  <arcgis-chart></arcgis-chart>

  <script type="module">

  </script>
5 collapsed lines

</body>


</html>

Within the <script> tag, use @arcgis.import() to import the createModel function from @arcgis/charts-components and FeatureLayer from @arcgis/core/layers/FeatureLayer.js.

28 collapsed lines
<html>

<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no" />
  <title>
    ArcGIS Maps SDK for JavaScript Tutorials: Box plot
  </title>

  <style>
    html,
    body,
    arcgis-chart {
      height: 100%;
      margin: 0;
    }
  </style>

  <!-- Load the ArcGIS Maps SDK for JavaScript from CDN -->
  <script type="module" src="https://js.arcgis.com/5.0/"></script>

</head>


<body>

  <arcgis-chart></arcgis-chart>

  <script type="module">

    const { createModel } = await $arcgis.import("@arcgis/charts-components");
    const FeatureLayer = await $arcgis.import("@arcgis/core/layers/FeatureLayer.js");

  </script>
5 collapsed lines

</body>


</html>

Load a feature layer from a portalItem that contains life expectancy data.

28 collapsed lines
<html>

<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no" />
  <title>
    ArcGIS Maps SDK for JavaScript Tutorials: Box plot
  </title>

  <style>
    html,
    body,
    arcgis-chart {
      height: 100%;
      margin: 0;
    }
  </style>

  <!-- Load the ArcGIS Maps SDK for JavaScript from CDN -->
  <script type="module" src="https://js.arcgis.com/5.0/"></script>

</head>


<body>

  <arcgis-chart></arcgis-chart>

  <script type="module">

    const { createModel } = await $arcgis.import("@arcgis/charts-components");
    const FeatureLayer = await $arcgis.import("@arcgis/core/layers/FeatureLayer.js");

    const featureLayer = new FeatureLayer({
      portalItem: {
        id: "c99e16e5573c47ab8c4536cb77673211",
      },
    });

  </script>
5 collapsed lines

</body>


</html>

Use document.querySelector() to select the <arcgis-chart> component.

28 collapsed lines
<html>

<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no" />
  <title>
    ArcGIS Maps SDK for JavaScript Tutorials: Box plot
  </title>

  <style>
    html,
    body,
    arcgis-chart {
      height: 100%;
      margin: 0;
    }
  </style>

  <!-- Load the ArcGIS Maps SDK for JavaScript from CDN -->
  <script type="module" src="https://js.arcgis.com/5.0/"></script>

</head>


<body>

  <arcgis-chart></arcgis-chart>

  <script type="module">

    const { createModel } = await $arcgis.import("@arcgis/charts-components");
    const FeatureLayer = await $arcgis.import("@arcgis/core/layers/FeatureLayer.js");

    const featureLayer = new FeatureLayer({
      portalItem: {
        id: "c99e16e5573c47ab8c4536cb77673211",
      },
    });

    const chartElement = document.querySelector("arcgis-chart");

  </script>
5 collapsed lines

</body>


</html>

Use createModel() to create a new box plot model with the feature layer. The chart type is set to boxPlot.

28 collapsed lines
<html>

<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no" />
  <title>
    ArcGIS Maps SDK for JavaScript Tutorials: Box plot
  </title>

  <style>
    html,
    body,
    arcgis-chart {
      height: 100%;
      margin: 0;
    }
  </style>

  <!-- Load the ArcGIS Maps SDK for JavaScript from CDN -->
  <script type="module" src="https://js.arcgis.com/5.0/"></script>

</head>


<body>

  <arcgis-chart></arcgis-chart>

  <script type="module">

    const { createModel } = await $arcgis.import("@arcgis/charts-components");
    const FeatureLayer = await $arcgis.import("@arcgis/core/layers/FeatureLayer.js");

    const featureLayer = new FeatureLayer({
      portalItem: {
        id: "c99e16e5573c47ab8c4536cb77673211",
      },
    });

    const chartElement = document.querySelector("arcgis-chart");

    const boxPlotModel = await createModel({ layer: featureLayer, chartType: "boxPlot" });

  </script>
5 collapsed lines

</body>


</html>

Customize the box plot

In this section, we’ll explore how to use various properties and methods from the box plot model together with the <arcgis-chart> component to render the box plot.

Specifically, we will be creating a box plot with a single numeric field, a category field, and a split-by field to compare the distribution of life expectancy across different years and continents.

First, set the numericFields property to the field name life_expectancy.

43 collapsed lines
<html>

<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no" />
  <title>
    ArcGIS Maps SDK for JavaScript Tutorials: Box plot
  </title>

  <style>
    html,
    body,
    arcgis-chart {
      height: 100%;
      margin: 0;
    }
  </style>

  <!-- Load the ArcGIS Maps SDK for JavaScript from CDN -->
  <script type="module" src="https://js.arcgis.com/5.0/"></script>

</head>


<body>

  <arcgis-chart></arcgis-chart>

  <script type="module">

    const { createModel } = await $arcgis.import("@arcgis/charts-components");
    const FeatureLayer = await $arcgis.import("@arcgis/core/layers/FeatureLayer.js");

    const featureLayer = new FeatureLayer({
      portalItem: {
        id: "c99e16e5573c47ab8c4536cb77673211",
      },
    });

    const chartElement = document.querySelector("arcgis-chart");

    const boxPlotModel = await createModel({ layer: featureLayer, chartType: "boxPlot" });

    boxPlotModel.numericFields = ["life_expectancy"];

8 collapsed lines
    chartElement.model = boxPlotModel;

  </script>

</body>


</html>

Next, set the category property to the field name year_long to group the box plots by year.

43 collapsed lines
<html>

<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no" />
  <title>
    ArcGIS Maps SDK for JavaScript Tutorials: Box plot
  </title>

  <style>
    html,
    body,
    arcgis-chart {
      height: 100%;
      margin: 0;
    }
  </style>

  <!-- Load the ArcGIS Maps SDK for JavaScript from CDN -->
  <script type="module" src="https://js.arcgis.com/5.0/"></script>

</head>


<body>

  <arcgis-chart></arcgis-chart>

  <script type="module">

    const { createModel } = await $arcgis.import("@arcgis/charts-components");
    const FeatureLayer = await $arcgis.import("@arcgis/core/layers/FeatureLayer.js");

    const featureLayer = new FeatureLayer({
      portalItem: {
        id: "c99e16e5573c47ab8c4536cb77673211",
      },
    });

    const chartElement = document.querySelector("arcgis-chart");

    const boxPlotModel = await createModel({ layer: featureLayer, chartType: "boxPlot" });

    boxPlotModel.numericFields = ["life_expectancy"];

    boxPlotModel.category = "year_long";

8 collapsed lines
    chartElement.model = boxPlotModel;

  </script>

</body>


</html>

By setting the splitByField property to continent, this will group the box plots by continent within the year range.

43 collapsed lines
<html>

<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no" />
  <title>
    ArcGIS Maps SDK for JavaScript Tutorials: Box plot
  </title>

  <style>
    html,
    body,
    arcgis-chart {
      height: 100%;
      margin: 0;
    }
  </style>

  <!-- Load the ArcGIS Maps SDK for JavaScript from CDN -->
  <script type="module" src="https://js.arcgis.com/5.0/"></script>

</head>


<body>

  <arcgis-chart></arcgis-chart>

  <script type="module">

    const { createModel } = await $arcgis.import("@arcgis/charts-components");
    const FeatureLayer = await $arcgis.import("@arcgis/core/layers/FeatureLayer.js");

    const featureLayer = new FeatureLayer({
      portalItem: {
        id: "c99e16e5573c47ab8c4536cb77673211",
      },
    });

    const chartElement = document.querySelector("arcgis-chart");

    const boxPlotModel = await createModel({ layer: featureLayer, chartType: "boxPlot" });

    boxPlotModel.numericFields = ["life_expectancy"];

    boxPlotModel.category = "year_long";

    boxPlotModel.splitByField = "continent";

8 collapsed lines
    chartElement.model = boxPlotModel;

  </script>

</body>


</html>

The display mode of the box plot can be changed to show the mean lines by setting the showMeanLines property to true. This will create one box plot for each category or numeric field variable and use lines to show the mean for each unique value in the split-by field.

Outliers can be shown by setting the showOutliers property to true, which will display individual points beyond the upper and lower whiskers of the box plot.

43 collapsed lines
<html>

<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no" />
  <title>
    ArcGIS Maps SDK for JavaScript Tutorials: Box plot
  </title>

  <style>
    html,
    body,
    arcgis-chart {
      height: 100%;
      margin: 0;
    }
  </style>

  <!-- Load the ArcGIS Maps SDK for JavaScript from CDN -->
  <script type="module" src="https://js.arcgis.com/5.0/"></script>

</head>


<body>

  <arcgis-chart></arcgis-chart>

  <script type="module">

    const { createModel } = await $arcgis.import("@arcgis/charts-components");
    const FeatureLayer = await $arcgis.import("@arcgis/core/layers/FeatureLayer.js");

    const featureLayer = new FeatureLayer({
      portalItem: {
        id: "c99e16e5573c47ab8c4536cb77673211",
      },
    });

    const chartElement = document.querySelector("arcgis-chart");

    const boxPlotModel = await createModel({ layer: featureLayer, chartType: "boxPlot" });

    boxPlotModel.numericFields = ["life_expectancy"];

    boxPlotModel.category = "year_long";

    boxPlotModel.splitByField = "continent";

    boxPlotModel.showOutliers = true;
    boxPlotModel.showMeanLines = true;

8 collapsed lines
    chartElement.model = boxPlotModel;

  </script>

</body>


</html>

Customize other properties such as legendPosition, titleText and setAxisTitleText() to enhance the appearance of the box plot.

43 collapsed lines
<html>

<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no" />
  <title>
    ArcGIS Maps SDK for JavaScript Tutorials: Box plot
  </title>

  <style>
    html,
    body,
    arcgis-chart {
      height: 100%;
      margin: 0;
    }
  </style>

  <!-- Load the ArcGIS Maps SDK for JavaScript from CDN -->
  <script type="module" src="https://js.arcgis.com/5.0/"></script>

</head>


<body>

  <arcgis-chart></arcgis-chart>

  <script type="module">

    const { createModel } = await $arcgis.import("@arcgis/charts-components");
    const FeatureLayer = await $arcgis.import("@arcgis/core/layers/FeatureLayer.js");

    const featureLayer = new FeatureLayer({
      portalItem: {
        id: "c99e16e5573c47ab8c4536cb77673211",
      },
    });

    const chartElement = document.querySelector("arcgis-chart");

    const boxPlotModel = await createModel({ layer: featureLayer, chartType: "boxPlot" });

    boxPlotModel.numericFields = ["life_expectancy"];

    boxPlotModel.category = "year_long";

    boxPlotModel.splitByField = "continent";

    boxPlotModel.showOutliers = true;
    boxPlotModel.showMeanLines = true;

    boxPlotModel.legendPosition = "top";
    boxPlotModel.titleText = "Distribution of Life Expectancy by Year and Continent"
    boxPlotModel.setAxisTitleText("Year", 0);
9 collapsed lines

    chartElement.model = boxPlotModel;

  </script>

</body>


</html>

Set the model property of the chartElement to the boxPlotModel to apply the configurations and render the chart.

56 collapsed lines
<html>

<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no" />
  <title>
    ArcGIS Maps SDK for JavaScript Tutorials: Box plot
  </title>

  <style>
    html,
    body,
    arcgis-chart {
      height: 100%;
      margin: 0;
    }
  </style>

  <!-- Load the ArcGIS Maps SDK for JavaScript from CDN -->
  <script type="module" src="https://js.arcgis.com/5.0/"></script>

</head>


<body>

  <arcgis-chart></arcgis-chart>

  <script type="module">

    const { createModel } = await $arcgis.import("@arcgis/charts-components");
    const FeatureLayer = await $arcgis.import("@arcgis/core/layers/FeatureLayer.js");

    const featureLayer = new FeatureLayer({
      portalItem: {
        id: "c99e16e5573c47ab8c4536cb77673211",
      },
    });

    const chartElement = document.querySelector("arcgis-chart");

    const boxPlotModel = await createModel({ layer: featureLayer, chartType: "boxPlot" });

    boxPlotModel.numericFields = ["life_expectancy"];

    boxPlotModel.category = "year_long";

    boxPlotModel.splitByField = "continent";

    boxPlotModel.showOutliers = true;
    boxPlotModel.showMeanLines = true;

    boxPlotModel.legendPosition = "top";
    boxPlotModel.titleText = "Distribution of Life Expectancy by Year and Continent"
    boxPlotModel.setAxisTitleText("Year", 0);

    chartElement.model = boxPlotModel;
7 collapsed lines

  </script>

</body>


</html>

Run the app

In CodePen, run your code to display the chart.

You should see a box plot showing how life expectancy distrubutions change over time, grouped by year and continent. Displaying mean lines and outliers allows you to observe the steady rise in life expectancy across all continents, with sharp gains occurring after the mid 20th century.

What’s next?

Learn how to use additional SDK features and ArcGIS services in these tutorials: