*! version 0.1.3 2026-07-04

Title

googlechart -- Stata wrapper for the Google Charts (Visualization API) library

Syntax

googlechart [varlist] [if] [in] , type(type)
[ type_specific_options cross-cutting_options ]

type is one of:
column bar line area combo pie donut
scatter bubble geo timeline table histogram divbar

Description

googlechart renders an interactive Google Charts visualization from a
long-form Stata dataset and writes a self-contained HTML file. The package
is a sibling to sparkta2, not a replacement: sparkta2 ships D3 and
TopoJSON inline (offline-capable), while googlechart uses the Google Charts
loader at gstatic.com (CDN-only, requires network at view time).

Use googlechart when: you want native filter dropdowns / range sliders
(filters() option), polished default tooltips,
animations on most chart types, and types not in sparkta2 -- bubble, combo,
timeline, geo (country/state-level), table.

Use sparkta2 when: the HTML must work offline (LaTeX deck handouts,
embargoed reports), the visualization is a Texas county / school-district
choropleth, or you want bivariate / hexbin maps.

Colors come from scheme(), which selects among the built-in palettes
(blues, reds, viridis, and others). One further option,
tx2036style, applies a fixed house style (Montserrat plus the Texas 2036
palette) for teams that publish under it; see the option list below.

Chart types

type

column vertical bars; one row per category

bar horizontal bars; one row per category

line line chart; supports multiple series via over()

area filled-area line chart; same data shape as line

combo mixed bars + lines / areas via combotypes()

pie pie chart; one row per slice

donut pie with center hole; innerradius() controls hole size

scatter point cloud; two-variable varlist = (x y)

bubble like scatter; two-variable varlist, plus sizevar() and over() for size/color

geo country / US-state choropleth -- see Limitations

timeline Gantt-style swimlanes; startvar()/endvar() required

table sortable/paginated HTML table -- no chart

histogram distribution; one numeric var

divbar Pew-style diverging stacked bar for Likert items

Options

Data shape
name(varname) category / item / region label

over(varname) series / group / color dimension

level(varname) response level (Likert) for divbar

levelorder(string) pipe-separated explicit level order

centerlevel(string) centering level for divbar (e.g. Neutral)

startvar(varname) timeline start date or year

endvar(varname) timeline end date or year

sizevar(varname) bubble size

tooltipvars(varlist) extra fields shown in the data table

Per-type appearance
horizontal swap column to bar (or accept the bar default)

stacked stacked instead of grouped

normalize stacked + 100% normalised

directlabels values on bars (column/bar, via annotation role); switches pie/donut slice text from value to percentage

innerradius(#) donut hole fraction (default 0.45)

legendpos(string) top | right | bottom | left -- pie/donut default to bottom

bucketsize(#) explicit histogram bucket width (default auto)

labelwrap(#|none) divbar row-label wrap width (default 50 chars; none disables)

tablesearch free-text Search box above type(table) -- substring match across all columns

tableheadersticky accepted for compatibility; type(table) headers are sticky on scroll whether or not it is given

time(varname) for type(bubble): time dimension that drives a Play button + range slider (requires a panel -- one row per entity per value of varname)

georegion(string) geo region: world | US | 150 | etc.

georesolution(string) countries | provinces | metros | us-states (alias for provinces)

combotypes(string) pipe-separated per-series chart type for combo

combodflt(string) default chart type per series for combo

Brand + interactivity
tx2036style Texas 2036 brand + Montserrat font

scheme(string) color palette: tx2036 | blues | reds | viridis | etc.

download include the Export menu (PNG/SVG)

datatable add CSV download + "View data table" toggle

animate IntersectionObserver-gated draw (chart appears + animates when scrolled into view)

downloadpos(string) side (default) | below | none

filters(varlist) build a Google Dashboard with CategoryFilter (categorical) / NumberRangeFilter (numeric) per variable;

takes effect for type(column), type(bar), type(line), type(area), and type(table) only

Text + layout
title(string)

subtitle(string)

note(string) page-foot attribution

xlabel(string) x-axis title

ylabel(string) y-axis title

namelabel(string) override the category-column display name

valuelabel(string) override the value-column display name

width(#) default 980

height(#) default 644

Output
export(path) output HTML path; default googlechart_type.html in cwd

noopen accepted for compatibility; googlechart never opens a browser, it only prints a clickable link

Network requirement

Important: the output HTML requires network access at view time. The
file is small (~10-20 KB) because the Google Charts library is fetched from
the CDN at https://www.gstatic.com/charts/loader.js at view time, and the
per-chart-type packages (corechart, controls, geochart, timeline, ...) are
fetched lazily after that. This is a hard requirement of Google's Terms of
Service: the loader.js code may not be self-hosted or bundled into your
output.

If your deliverable must work offline (LaTeX deck handouts, embargoed
reports), use sparkta2 instead. See sparkta2.

Limitations worth knowing

Geo resolution stops at US state level. GeoChart does not
support county FIPS, school-district shapes, or any custom GeoJSON. For
Texas county / school-district choropleth, use sparkta2.

No native diverging-bar mode. The divbar type fakes it
by sign-flipping the negative-side levels and stacking via isStacked.
Axis ticks display absolute values via custom format so readers see
"40%, 20%, 0%, 20%, 40%" rather than negative numbers on the left half.

Animation skips some chart types. Native Google Charts
animation supports only Column, Bar, Line, Area, Scatter, Bubble, Combo,
Candlestick, SteppedArea, and Gauge. GeoChart, Pie / Donut, Treemap,
Timeline, Sankey, Table, and Calendar do not animate -- the animate
option is silently ignored. IntersectionObserver-gated initial draw still
fires for those types; the chart just doesn't ease in.

isHtml tooltips disable PNG export. The package does not
currently turn on isHtml tooltips so PNG export works on all corechart
types.

animate is incompatible with directlabels on bar/column.
directlabels adds an annotation-role column, and Google Charts throws
on animation.startup when that column is present, leaving the chart
blank. googlechart detects this combination on type(bar) and
type(column), drops animate, and prints a note. Use one or the
other on these types.

time() needs a panel. time(varname) on
type(bubble) animates one bubble per entity across the frames given by
varname, so the data must be in long/panel form: one row per entity per
time value (e.g. 51 states × 10 years = 510 rows). A single
cross-section gives the Play control only one frame and nothing moves.

PDF is intentionally omitted. Use your browser's File > Print
to save the chart as PDF -- a print stylesheet in the HTML hides the
controls panel and renders only the chart card.

Examples

A runnable do-file exercising every chart type sits at
examples/test_googlechart.do in the package. Each example below
expects an open cwd; HTML files are written there.

1. Column chart -- mean poverty by region

collapse (mean) poverty_rate, by(region)

googlechart poverty_rate, name(region) type(column) ///

download datatable animate ///

title("Texas regions: mean poverty rate") ///

ylabel("Poverty rate (%)") ///

export("01_column.html")

2. Bar (horizontal) with filter dropdowns

googlechart poverty_rate, name(region) type(bar) ///

over(year) filters(year urban) ///

download datatable downloadpos(below) ///

title("Poverty by region -- filter by year / urbanisation") ///

export("02_bar_filters.html")

3. Multi-series line + animate-on-scroll

googlechart y yr, over(region) type(line) ///

download datatable animate ///

xlabel("Year") ylabel("% meeting standard") ///

title("Texas regions: trend 2018-2024") ///

export("03_line.html")

4. Donut chart with brand palette (legend below)

googlechart enrollment, name(sector) type(donut) ///

innerradius(0.5) directlabels animate ///

download datatable downloadpos(below) ///

title("Texas postsecondary enrollment by sector") ///

width(640) height(540) ///

export("04_donut.html")

Pie / donut default to legend below the chart and the standard 980x644
frame, so the bounding card hugs the chart instead of leaving an empty
band of right-side legend space. Pass legendpos(right) to restore
the older layout.

5. Bubble chart -- 3+ variable comparison

googlechart life_expect poverty_rate, name(county) ///

over(region_name) sizevar(pop_thou) ///

type(bubble) download datatable animate ///

title("Life expectancy vs poverty rate; bubble = pop") ///

xlabel("Poverty rate (%)") ylabel("Life expectancy (yrs)") ///

export("05_bubble.html")

6. Combo chart -- bars + overlay line

googlechart value, name(year) over(metric) type(combo) ///

combodflt(bars) combotypes("bars|bars|line") ///

download datatable ///

title("Bars + overlay line via combotypes()") ///

export("06_combo.html")

7. Geo chart -- US state choropleth

Important: only country and US-state level are supported.

googlechart value, name(state_code) type(geo) ///

georegion("US") georesolution("us-states") ///

download datatable ///

title("US states -- example metric") ///

export("07_geo.html")

8. Timeline -- Gantt-style swimlanes

* Data: one row per session, with name(=row), startvar, endvar.

googlechart, type(timeline) name(session_label) ///

startvar(date_start) endvar(date_end) ///

download datatable ///

title("Texas legislative session timeline") ///

export("08_timeline.html")

9. Table -- searchable, with sticky header

A free-text search box can be wired above the rendered table
using tablesearch; rows filter live by substring match across all
columns and the row count updates next to the input. The header row stays
visible while you scroll a long table; that is the default for every
type(table) rendering and needs no option.

googlechart, type(table) ///

tooltipvars(region poverty_rate uninsured_rate pop_thou) ///

tablesearch ///

download datatable ///

title("Texas regions: searchable data table") ///

export("09_table.html")

For a dropdown-filtered (Dashboard + CategoryFilter) variant, add
filters(group year). Note that the two do not combine: when
filters() is given, the table is rendered inside a dashboard and the
tablesearch box is not built. Choose dropdowns or the search box.

10. Diverging stacked bar (Pew-style Likert)

* Long form: name = item, level = response, varlist = share %.

googlechart share, name(q) level(response) type(divbar) ///

levelorder("Strongly disagree|Disagree|Neutral|Agree|Strongly agree") ///

centerlevel(Neutral) ///

download datatable downloadpos(below) ///

title("Texans on K-12 and higher-ed policy") ///

width(1100) height(640) ///

export("10_divbar.html")

11. Combine multiple charts on one page (dashboard)

* The sparkta2 dashboard composer works on any HTML files,

* including googlechart outputs. Pass the file basenames:

sparkta2_dashboard, ///

files("01_column.html 03_line.html 04_donut.html 10_divbar.html") ///

titles("Column|Line|Donut|Divbar") ///

heights("680") ///

title("googlechart demo gallery") ///

export("gallery.html")

Stored results

googlechart stores the following in r():

Scalars

r(n_rows) number of data rows written to the HTML payload

Macros

r(export) path of the HTML file written

r(type) chart type rendered

Author and acknowledgements

googlechart is by Eric A. Booth, Sr Researcher, Texas2036.org (eric.a.booth@gmail.com), 2026. Built atop Google Charts
(https://developers.google.com/chart) which is the property of Google LLC
and is subject to the Google Charts Terms of Service. This package is
not affiliated with or endorsed by Google.

Design inheritance: the file layout, brand defaults, Export menu UX,
animate-on-view pattern, and dashboard composer all mirror sparkta2.
sparkta2 is the sister package and the right tool when offline
HTML or Texas county / district choropleths are required.