Distribution Visualization JavaScript Library – Alphaswarm Charts

Alphaswarm Charts is a JavaScript data visualization library for creating distribution charts that show individual data points with statistical overlays and jittering to prevent overlap.

The library can be used to show both the forest and the trees in your data. You can see every single data point while simultaneously viewing mean and median lines.

This makes it perfect for exploratory data analysis where you need to understand both individual observations and overall distribution patterns.

Features:

• Individual data point visibility: Every observation appears as a distinct point to preserve data transparency.
• Statistical overlay lines: Customizable mean and median indicators with different styling options.
• Interactive opacity controls: Adjustable point transparency for handling different data densities.
• Intelligent jittering system: Prevents point overlap while maintaining distribution integrity.
• Multiple orientation support: Create both horizontal and vertical chart layouts.
• Observable Plot integration: Works seamlessly with existing D3.js and Observable Plot workflows.
• Rich customization options: Control colors, sizes, labels, and statistical displays.

Use Cases:

• Comparing performance metrics: You could use it to visualize bug resolution times across different engineering teams. A simple bar chart showing the average time doesn’t tell the whole story. An alphaswarm chart would show you the full distribution, revealing if one team has a few very long-running outliers while another is more consistent.
• Analyzing user engagement: Imagine you want to compare daily meeting hours for different developer levels. This chart type would show you not just the average time but also the spread. You might discover that while the mean is similar, senior developers have a bimodal distribution—either very short or very long meetings—which a box plot would completely hide.
• Visualizing A/B test results: When you run an A/B test, looking at the average conversion rate is standard. An alphaswarm chart lets you see the entire distribution of results for both the control and variant groups. This can help you spot outliers or multi-modal patterns that indicate different user segments are reacting differently to your changes.

How to use it:

1. Install alphaswarm-charts and import it into your project.

# NPM
$ npm install alphaswarm-charts

import { createAlphaswarmChart } from 'alphaswarm-charts';

// OR
<script type="module">
  import { createAlphaswarmChart } from './src/alphaswarm.js';
</script>

2. Prepare the data as an array of objects. Each object should have a property for the category and another for the numeric value.

const testScores = [
  { class: 'Class A', score: 85 },
  { class: 'Class A', score: 92 },
  { class: 'Class A', score: 78 },
  // ... more data for Class A
  { class: 'Class B', score: 76 },
  { class: 'Class B', score: 82 },
  // ... more data for Class B
  { class: 'Class C', score: 90 },
  { class: 'Class C', score: 87 },
  // ... more data for Class C
];

3. Call the createAlphaswarmChart function, passing in your data and a configuration object. At a minimum, you need to specify the x and y properties from your data objects.

const chart = createAlphaswarmChart(testScores, {
  x: 'score',
  y: 'class',
  xLabel: 'Test Score',
  yLabel: 'Class'
});

4. Append the chart to your document.

document.getElementById('chart-container').appendChild(chart);

5. Available configuration options to customize the chart.

• x (string, default: "value"): The field name from your data objects to use for the x-axis values (the numeric data).
• y (string, default: "category"): The field name from your data objects for the y-axis categories (the grouping variable).
• width (number, default: 800): The total width of the chart in pixels.
• height (number, default: 400): The total height of the chart in pixels.
• opacity (number, default: 0.6): The opacity of the data points, from 0 (transparent) to 1 (opaque).
• jitter (number, default: 0.5): The amount of vertical spread (jitter) applied to points, from 0 (a straight line) to 1 (maximum spread).
• jitterMethod (string, default: "random"): The algorithm for jittering. Can be "random" for random placement or "uniform" for a more even distribution.
• pointRadius (number, default: 4): The radius of each data point in pixels.
• pointColor (string, default: "#4285f4"): The color of the data points.
• showMean (boolean, default: true): If true, a line indicating the mean (average) for each category is displayed.
• showMedian (boolean, default: true): If true, a line indicating the median for each category is displayed.
• showTooltips (boolean, default: false): If true, tooltips will appear when hovering over data points.
• xLabel (string, default: null): The text label to display below the x-axis.
• yLabel (string, default: null): The text label to display beside the y-axis.
• xDomain (Array, default: null): An array [min, max] to manually set the domain for the x-axis.
• title (string, default: null): The main title for the chart, displayed at the top.

const chart: createAlphaswarmChart(testScores, {
  x: "value", // x-axis field name
  y: "category", // y-axis field name (for grouping)
  width: 800,
  height: 400,
  marginLeft: 100,
  marginRight: 40,
  marginTop: 20,
  marginBottom: 40,
  opacity: 0.6,
  jitter: 0.5,
  jitterMethod: 'random',
  pointRadius: 4,
  pointColor: "#4285f4",
  showMean: true,
  showMedian: true,
  showTooltips: false,
  xLabel: null,
  yLabel: null,
  xDomain: null,
  title: null
});

6. API methods.

• createAlphaswarmChart(data, options): Creates and returns a standard horizontal alphaswarm chart DOM element. This is the primary function for generating charts where categories are on the y-axis and values are on the x-axis.
• createVerticalAlphaswarmChart(data, options): Creates and returns a vertical alphaswarm chart DOM element. It uses the same options as the horizontal version but swaps the axes, placing categories on the x-axis and values on the y-axis.
• calculateStats(values): A utility function that takes an array of numbers and returns a statistics object containing the mean, median, min, max, q1 (first quartile), q3 (third quartile), and count.
• generateJitter(count, jitter, method): A helper function that generates an array of jittered coordinates. It’s used internally to position the data points and prevent overlap.

FAQs

Q: What data format does Alphaswarm Charts expect?
A: The library requires an array of objects where each object represents one data point. You need at least two fields: one numeric field for the distribution values and one categorical field for grouping. Additional fields can be included for tooltip content or custom styling.

Q: How do I handle overlapping points in dense datasets?
A: Adjust both the opacity and jitter settings. For datasets with many overlapping points, try reducing opacity to 0.3-0.4 and increasing jitter to 0.7-0.8. You can also reduce the point radius to create more visual space between observations.

Q: Can I customize the appearance of mean and median lines?
A: Yes, though the current version uses default styling. You can modify the generated SVG elements after chart creation, or the library accepts CSS classes for statistical overlay customization in advanced configurations.

Q: What happens with missing or invalid data values?
A: The library automatically filters out null, undefined, or non-numeric values from the dataset before rendering. Missing categorical values result in those points being excluded from the visualization entirely.