From ab71e938c6496aa89056f1815237eb1ef90156af Mon Sep 17 00:00:00 2001 From: Alek Petuskey Date: Mon, 27 Jul 2026 12:01:09 -0700 Subject: [PATCH 1/3] Tighten the README and cut marketing filler Rewrite the top-of-file copy: a one-line tagline, the intro folded into two short paragraphs, and the Highlights bullet list dropped. Trim the benchmark, Reflex, and how-it-works sections, remove the "What you can build today" section that restated Highlights, and rename the example-gallery labels to what each chart actually is ("cosmic observatory" -> "HR diagram"). Also move Examples above How it works, drop the Documentation section, replace the em dashes in the roadmap list with colons, and point the styling guide and capability matrix at absolute GitHub URLs so they resolve on PyPI. Prose drops from 1145 to 761 words. No code samples, images, or benchmark numbers change. --- README.md | 190 +++++++++++++++++++++--------------------------------- 1 file changed, 73 insertions(+), 117 deletions(-) diff --git a/README.md b/README.md index 73c9ed54..ca94c879 100644 --- a/README.md +++ b/README.md @@ -10,35 +10,26 @@

- Small data should be effortless. Large data should stay interactive.
- Neither should limit the design. + XY is a fast, interactive, customizable Python charting library for + the web, notebooks, and static exports.

-XY is an actively evolving, early-alpha project with one ambition: become the -fastest and most customizable charting library for Python — across every chart -type and every scale, from a handful of values to billions of rows. +Charts are composed declaratively, or through the familiar matplotlib shim. You +can completely customize them with Python, CSS, or Tailwind. -Small datasets render directly and exactly. As data grows, XY's Rust core, -binary transport, and WebGL2 renderer reduce work to what the screen can show, -then bring detail back as you zoom. The same composable API controls marks, -axes, annotations, legends, tooltips, interactions, themes, responsive layout, -and HTML, raster, and vector exports. +Small datasets render directly with full detail. For larger datasets, a +high-performance Rust engine processes only what the screen needs, keeping +charts fast and responsive. Zooming restores the full detail. Pan, zoom, hover, +and selection are built in, and selections return the original rows. -## Highlights +XY is early alpha and moves quickly. -- **Designed for every scale.** Ordinary datasets take the direct path; large datasets automatically use decimated or density representations. -- **Customize every layer.** Control marks and composition in Python, then style chart chrome through stable CSS and Tailwind hooks. -- **Declarative interface.** Compose marks and guides, or use the familiar `xy.pyplot`. -- **Interactive by default.** Pan, zoom, hover, select, and inspect exact source rows. -- **One chart, many outputs.** Use notebooks or export HTML, raster, and vector formats. -- **Built for apps.** Embed responsive charts and style them with Python, CSS, or Tailwind. +## Is XY right for me? -## Is XY for me? - -XY is for Python users who want one charting system for everyday plots, deeply -custom application visuals, and data too large for conventional browser chart -stacks. Build charts once, then display them in notebooks and apps or export -them as self-contained HTML, images, and vector graphics. +XY is for Python users who want one flexible charting library for everything +from everyday plots to custom application visuals and large datasets. Build a +chart once, then use it in notebooks and web apps or export it as HTML, PNG, +SVG, or PDF. ## Installation @@ -49,10 +40,10 @@ pip install xy uv add xy ``` -## Getting started: one API, every scale +## Getting started -A chart is a container plus the marks inside it. Any sequence works — plain -Python lists need no NumPy: +A chart is a container plus the marks inside it. Any sequence works; NumPy is +optional. ```python import xy @@ -64,8 +55,7 @@ chart = xy.line_chart(xy.line([1, 2, 3, 4, 5], [120, 180, 165, 240, 310])) chart # notebooks render it ``` -The data size changes; the chart model does not. The same API scales to a -hundred million points as a density surface: +The same API scales to a hundred million points as a density surface:

@@ -122,28 +112,21 @@ ax.legend() plt.show() ``` -The shim intentionally covers common plotting workflows rather than every -matplotlib feature. See the [compatibility guide](spec/matplotlib/compat.md). +See the [compatibility guide](spec/matplotlib/compat.md); not all charts and +functionality are supported yet. ## Customize every layer -Performance is not a preset. Use Python to control data marks and chart -composition, then style browser chrome through stable CSS and Tailwind hooks. +Use Python to control the chart, from marks and axes to interactions and layout. -- **Marks:** data-driven color and size, custom colormaps, opacity, symbols, - gradients, strokes, and curves. -- **Guides:** axes, ticks, grids, annotations, legends, colorbars, and tooltips. -- **Interaction:** pan, zoom, hover, selection, crosshairs, callbacks, and +- **Marks:** Control color, size, opacity, symbols, gradients, strokes, curves, + and colormaps. +- **Guides:** Customize axes, ticks, grids, annotations, legends, colorbars, and + tooltips. +- **Interaction:** Add pan, zoom, hover, selections, crosshairs, callbacks, and linked charts. -- **Layout and output:** layering, facets, responsive dimensions, themes, and - HTML, raster, or vector export. - -See the [styling guide](docs/styling/index.md) for patterns and examples. - -What each mechanism reaches — per property, per chrome slot, per renderer, and -where it stops — is the [capability matrix](spec/api/capability-matrix.md), -generated from `python/xy/styling/capabilities.py` and checked against the -implementation. +- **Layout:** Create layers and facets, set responsive dimensions, and apply + themes. ```python chart = xy.line_chart( @@ -153,37 +136,31 @@ chart = xy.line_chart( ) ``` +See the [styling guide](https://github.com/reflex-dev/xy/blob/main/docs/styling/index.md) +for examples. For a detailed breakdown of what can be customized, see the +[capability matrix](https://github.com/reflex-dev/xy/blob/main/spec/api/capability-matrix.md). + ## Benchmarks

Cold-render time for a 10-million-point chart in XY, Matplotlib, and Plotly. Lower is better.

-In the recorded 10-million-point baseline, XY produced a static PNG in 0.018 s -versus 2.7 s for Matplotlib and 9.6 s for Plotly, and reached first interactive -render 16–18× sooner. - -That baseline is one proof point, not the finish line. XY is being built to -outperform every competing charting library across small-data startup, -massive-data rendering, interaction, memory, payload and export size, -multi-chart applications, chart breadth, and customization. The committed -benchmark program, raw results, capability matrix, and visual examples are how -the project measures and proves that goal. +In the recorded 10-million-point launch baseline, XY wrote a static PNG in +0.018 s against 2.7 s for Matplotlib and 9.6 s for Plotly, and reached first +interactive render 16–18× sooner. The baseline uses identical seeded data, a +900×420 output, and three isolated cold runs. -The committed launch baseline uses identical seeded data, a 900×420 output, -and three isolated cold runs. See the +For the environment, methodology, and raw results, see the [launch report](benchmarks/launch_baselines/xy-main-2026-07-26/macos-arm64-m5-pro/report.md), [benchmark runbook](benchmarks/README.md), and -[competitive benchmark specification](spec/benchmarks/results.md) for the -environment, methodology, raw results, and full evidence program. +[competitive benchmark specification](spec/benchmarks/results.md). ## Embed XY in a Reflex app -With the `reflex-xy` adapter, any XY chart becomes a regular Reflex component. -Place it inside cards, grids, tabs, or dashboards with no JavaScript, iframe, -or separate chart service. - -The adapter ships as its own package, and pulls in `xy` and `reflex`: +The `reflex-xy` adapter turns any XY chart into a regular Reflex component, with +no JavaScript, iframe, or separate chart service. It ships as its own package +and pulls in `xy` and `reflex`: ```bash pip install reflex-xy @@ -230,17 +207,30 @@ app = rx.App() app.add_page(index) ``` -The chart keeps its built-in hover, pan, and zoom behavior. For charts driven -by Reflex state, events, or live streams, see the -[Reflex integration guide](https://reflex.dev/docs/xy/integrations/reflex/) -and the [runnable example app](examples/reflex/). +Hover, pan, and zoom keep working. For charts driven by Reflex state, events, or +live streams, see the +[Reflex integration guide](https://reflex.dev/docs/xy/integrations/reflex/) and +the [runnable example app](examples/reflex/). + +## Examples + +Each notebook fetches its rows from the linked public source; no raw datasets +are stored in this repository. Counts describe the featured chart, and the +notebooks scale further. See the +[example guide](examples/real_world/README.md) for sources, workload controls, +and setup. + +| | | | +| :---: | :---: | :---: | +| **Gaia DR3 · HR diagram**
250,000 plotted stars

![Gaia DR3 stellar color versus absolute magnitude.](examples/real_world/assets/01-gaia-hr-diagram.png)

[Open notebook](examples/real_world/01_gaia_hr_diagram.ipynb) | **gnomAD v4.1 · allele frequency**
164,000 plotted variants

![gnomAD allele frequency across all autosomes.](examples/real_world/assets/02-gnomad-allele-frequency.png)

[Open notebook](examples/real_world/02_gnomad_allele_frequency.ipynb) | **Pan-UKBB · Manhattan plot**
814,294 plotted variants

![Pan-UKBB standing-height associations across all autosomes.](examples/real_world/assets/03-pan-ukbb-manhattan.png)

[Open notebook](examples/real_world/03_pan_ukbb_manhattan.ipynb) | +| **Dukascopy · EUR/USD ticks**
101,427 plotted ticks

![Dukascopy EUR/USD midpoint quotes.](examples/real_world/assets/04-dukascopy-fx-ticks.png)

[Open notebook](examples/real_world/04_dukascopy_fx_ticks.ipynb) | **LIGO · GW150914 strain**
16,777,216 raw · 3,441 shown

![GWOSC reconstructed Hanford waveform for GW150914.](examples/real_world/assets/05-ligo-gw150914-strain.png)

[Open notebook](examples/real_world/05_ligo_gw150914_strain.ipynb) | **NYC TLC · taxi pickup density**
300,000 pickup records

![Locally projected NYC yellow-taxi pickup hexbin density.](examples/real_world/assets/06-nyc-taxi-density.png)

[Open notebook](examples/real_world/06_nyc_taxi_density.ipynb) | ## How it works Most chart stacks serialize every value as JSON and ask the browser to draw -every mark. XY instead keeps exact values in a `ColumnStore`, computes an -appropriate level of detail in Rust, and transfers typed binary buffers. -Decimated and density views are bounded by the visible result. +every mark. XY keeps exact values in a `ColumnStore`, computes a level of detail +in Rust, and transfers typed binary buffers. Decimated and density views are +bounded by the visible result. ```mermaid flowchart TB @@ -253,61 +243,27 @@ flowchart TB API --> STORE --> CORE --> PAYLOAD --> RENDER ``` -This is why zooming matters: a dense overview can use aggregation, while a -narrow view can return to exact points. With a live host, pan and zoom can -request a refined payload. Canonical f64 data stays in Python so hover and -selection can still return original rows. +So a dense overview can aggregate while a narrow view returns exact points. With +a live host, pan and zoom request a refined payload. Canonical f64 data stays in +Python, so hover and selection still return original rows. For the full design, see the [design dossier](spec/design-dossier.md). -## What you can build today - -- Declarative 2D charts with marks, axes, annotations, legends, tooltips, and - CSS/Tailwind-friendly styling hooks. -- Interactive notebook and application views with pan, zoom, hover, and - selection. -- Self-contained HTML and browser-free PNG, JPEG, WebP, SVG, and PDF exports - from the same chart object. -- Large-data views that adapt from direct rendering to decimated and density - representations as the visible range changes. - -## Examples - -Each notebook fetches working rows from its linked public source; raw datasets -are not stored in this repository. See the -[example guide](examples/real_world/README.md) for source links, workload -controls, and setup. Counts describe the data behind each featured chart; the -notebooks can scale further. - -| | | | -| :---: | :---: | :---: | -| **Gaia DR3 · cosmic observatory**
250,000 plotted stars

![Gaia DR3 stellar color versus absolute magnitude.](examples/real_world/assets/01-gaia-hr-diagram.png)

[Open notebook](examples/real_world/01_gaia_hr_diagram.ipynb) | **gnomAD v4.1 · genomic atlas**
164,000 plotted variants

![gnomAD allele frequency across all autosomes.](examples/real_world/assets/02-gnomad-allele-frequency.png)

[Open notebook](examples/real_world/02_gnomad_allele_frequency.ipynb) | **Pan-UKBB · biobank editorial**
814,294 plotted variants

![Pan-UKBB standing-height associations across all autosomes.](examples/real_world/assets/03-pan-ukbb-manhattan.png)

[Open notebook](examples/real_world/03_pan_ukbb_manhattan.ipynb) | -| **Dukascopy · trading terminal**
101,427 plotted ticks

![Dukascopy EUR/USD midpoint quotes.](examples/real_world/assets/04-dukascopy-fx-ticks.png)

[Open notebook](examples/real_world/04_dukascopy_fx_ticks.ipynb) | **LIGO · signal-lab oscilloscope**
16,777,216 raw · 3,441 shown

![GWOSC reconstructed Hanford waveform for GW150914.](examples/real_world/assets/05-ligo-gw150914-strain.png)

[Open notebook](examples/real_world/05_ligo_gw150914_strain.ipynb) | **NYC TLC · night cartography**
300,000 pickup records

![Locally projected NYC yellow-taxi pickup hexbin density.](examples/real_world/assets/06-nyc-taxi-density.png)

[Open notebook](examples/real_world/06_nyc_taxi_density.ipynb) | - -## Documentation - -Start with the [XY documentation](https://reflex.dev/docs/xy/) for installation, -the chart gallery, guides, and API reference. The repository also includes -[copyable API examples](spec/api/api-examples.md), -[benchmark details](benchmarks/README.md), and the [changelog](CHANGELOG.md). - ## Roadmap -XY is headed toward every chart family. The current implementation sequence -builds broad 2D coverage on top of the binary transport and screen-bounded -renderer, then extends the same performance and customization goals to -geographic, 3D, and volume visualization. Queued next, no dates implied: +Broad 2D coverage first, then geographic, 3D, and volume visualization. Queued +next, no dates implied: -- **Categorical distributions** — strip, swarm, beeswarm, boxen, rug -- **Regression diagnostics** — trendline, residual, QQ, PP -- **Scatter matrix and joint plots** — SPLOM, pair grid, marginal histograms -- **Pie / donut** — in `xy.pyplot` today, promoting to `xy.pie_chart(xy.pie(...))` -- **Candlestick / OHLC and finance overlays** — SMA, VWAP, Bollinger, RSI, MACD; prototyped, awaiting a fresh landing +- **Categorical distributions:** strip, swarm, beeswarm, boxen, rug +- **Regression diagnostics:** trendline, residual, QQ, PP +- **Scatter matrix and joint plots:** SPLOM, pair grid, marginal histograms +- **Pie / donut:** in `xy.pyplot` today, promoting to `xy.pie_chart(xy.pie(...))` +- **Candlestick / OHLC and finance overlays:** SMA, VWAP, Bollinger, RSI, MACD; prototyped, awaiting a fresh landing - **Waterfall and funnel** - **Treemap, sunburst, and icicle** -- **Radar / polar and gauge** — needs polar axes first +- **Radar / polar and gauge:** needs polar axes first - **Slope, bump, and dumbbell** -- **3D and volume** — scatter, surfaces, meshes, isosurfaces, and volumetric views +- **3D and volume:** scatter, surfaces, meshes, isosurfaces, and volumetric views The full ranked backlog is in the [chart roadmap](spec/api/chart-roadmap.md). Want a chart or feature that isn't listed? From 89cc906389b1c1e52b1259bf437a936eb90f2422 Mon Sep 17 00:00:00 2001 From: Alek Petuskey Date: Mon, 27 Jul 2026 12:03:57 -0700 Subject: [PATCH 2/3] Make the opening line regular body text Drop the centered bold wrapper so the first sentence is left-aligned prose like the rest of the README. --- README.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index ca94c879..1c5b3aa6 100644 --- a/README.md +++ b/README.md @@ -9,10 +9,8 @@ Docs

-

- XY is a fast, interactive, customizable Python charting library for - the web, notebooks, and static exports. -

+XY is a fast, interactive, customizable Python charting library for the web, +notebooks, and static exports. Charts are composed declaratively, or through the familiar matplotlib shim. You can completely customize them with Python, CSS, or Tailwind. From 9b777628955d3c23d7e83dc5d999fce3f14b4261 Mon Sep 17 00:00:00 2001 From: Alek Petuskey Date: Mon, 27 Jul 2026 13:23:17 -0700 Subject: [PATCH 3/3] Rewrite the intro copy --- README.md | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 1c5b3aa6..b51902e9 100644 --- a/README.md +++ b/README.md @@ -9,18 +9,19 @@ Docs

-XY is a fast, interactive, customizable Python charting library for the web, -notebooks, and static exports. +XY is an extremely fast, interactive, customizable Python charting library for +the web, notebooks, and static exports. -Charts are composed declaratively, or through the familiar matplotlib shim. You -can completely customize them with Python, CSS, or Tailwind. +Charts are composed declaratively or through matplotlib conventions. You can +fully customize them with Python, CSS, or Tailwind. -Small datasets render directly with full detail. For larger datasets, a -high-performance Rust engine processes only what the screen needs, keeping -charts fast and responsive. Zooming restores the full detail. Pan, zoom, hover, -and selection are built in, and selections return the original rows. +With small charts, every point is sent to the browser. For large charts, the +Rust core computes only what the screen needs to display, based on its +resolution. Pan, zoom, hover, and selection can show full details by running the +same process for the new range, and a selection returns the original rows. -XY is early alpha and moves quickly. +XY is early alpha, and is receiving frequent enhancements. Any contributions are +appreciated! ## Is XY right for me?