Skip to content

Commit fa7dc5f

Browse files
docs: add impl-level filter categories to API and Plausible docs
- Add 5 impl-level URL params: dep, tech, pat, prep, style - Update category values reference with spec/impl distinction - Add filter_* properties for og:image tracking - Update API response example with impl-level counts
1 parent 551ea5c commit fa7dc5f

2 files changed

Lines changed: 35 additions & 7 deletions

File tree

docs/reference/api.md

Lines changed: 15 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -160,13 +160,22 @@ The pyplots API is a **FastAPI-based REST API** serving plot data to the fronten
160160
**Purpose**: Filter plots with faceted counts for all filter categories
161161

162162
**Query Parameters** (combinable):
163+
164+
*Spec-level filters (WHAT is visualized):*
163165
- `lib` - Library filter (matplotlib, seaborn, etc.)
164166
- `spec` - Spec ID filter
165167
- `plot` - Plot type tag filter
166168
- `data` - Data type tag filter
167169
- `dom` - Domain tag filter
168170
- `feat` - Features tag filter
169171

172+
*Impl-level filters (HOW it is implemented):*
173+
- `dep` - Dependencies filter (scipy, sklearn, etc.)
174+
- `tech` - Techniques filter (twin-axes, annotations, etc.)
175+
- `pat` - Patterns filter (data-generation, groupby-aggregation, etc.)
176+
- `prep` - Dataprep filter (kde, binning, regression, etc.)
177+
- `style` - Styling filter (minimal-chrome, alpha-blending, etc.)
178+
170179
**Filter Logic**:
171180
- Comma-separated values: OR (`lib=matplotlib,seaborn`)
172181
- Multiple params same name: AND (`lib=matplotlib&lib=seaborn`)
@@ -192,7 +201,12 @@ The pyplots API is a **FastAPI-based REST API** serving plot data to the fronten
192201
"plot": {"scatter": 10},
193202
"data": {"numeric": 15},
194203
"dom": {"statistics": 8},
195-
"feat": {"basic": 12}
204+
"feat": {"basic": 12},
205+
"dep": {"scipy": 3},
206+
"tech": {"annotations": 5},
207+
"pat": {"data-generation": 8},
208+
"prep": {"kde": 2},
209+
"style": {"alpha-blending": 4}
196210
},
197211
"globalCounts": {...},
198212
"orCounts": [...]

docs/reference/plausible.md

Lines changed: 20 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@ Filters create dynamic URLs with the following format:
2323
https://pyplots.ai/{category}/{value}/{category}/{value}/...
2424
```
2525

26-
**Ordered categories**: `lib`, `spec`, `plot`, `data`, `dom`, `feat`
26+
**Ordered categories**: `lib`, `spec`, `plot`, `data`, `dom`, `feat`, `dep`, `tech`, `pat`, `prep`, `style`
2727

2828
**Examples**:
2929
- `/?lib=matplotlib``https://pyplots.ai/lib/matplotlib`
@@ -213,17 +213,23 @@ To see event properties in Plausible dashboard, you **MUST** register them as cu
213213
| `method` | Action method (card, image, tab, click, space, doubletap) | `copy_code`, `random` |
214214
| `page` | Page context (home, catalog, spec_overview, spec_detail) | `copy_code`, `download_image`, `og_image_view` |
215215
| `platform` | Bot/platform name (twitter, whatsapp, teams, etc.) | `og_image_view` |
216-
| `category` | Filter category (lib, plot, dom, feat, data, spec) | `search`, `random`, `filter_remove` |
216+
| `category` | Filter category (lib, spec, plot, data, dom, feat, dep, tech, pat, prep, style) | `search`, `random`, `filter_remove` |
217217
| `value` | Filter value | `random`, `filter_remove` |
218218
| `query` | Search query text | `search`, `search_no_results` |
219219
| `destination` | External link target (linkedin, github, stats) | `external_link` |
220220
| `tab` | Tab name (code, specification, implementation, quality) | `tab_click` |
221221
| `size` | Grid size (normal, compact) | `toggle_grid_size` |
222222
| `filter_lib` | Library filter value (for og:image) | `og_image_view` |
223-
| `filter_dom` | Domain filter value (for og:image) | `og_image_view` |
223+
| `filter_spec` | Specification filter value (for og:image) | `og_image_view` |
224224
| `filter_plot` | Plot type filter value (for og:image) | `og_image_view` |
225-
| `filter_feat` | Features filter value (for og:image) | `og_image_view` |
226225
| `filter_data` | Data type filter value (for og:image) | `og_image_view` |
226+
| `filter_dom` | Domain filter value (for og:image) | `og_image_view` |
227+
| `filter_feat` | Features filter value (for og:image) | `og_image_view` |
228+
| `filter_dep` | Dependencies filter value (for og:image) | `og_image_view` |
229+
| `filter_tech` | Techniques filter value (for og:image) | `og_image_view` |
230+
| `filter_pat` | Patterns filter value (for og:image) | `og_image_view` |
231+
| `filter_prep` | Dataprep filter value (for og:image) | `og_image_view` |
232+
| `filter_style` | Styling filter value (for og:image) | `og_image_view` |
227233

228234
### Goals Configuration
229235

@@ -378,12 +384,20 @@ unknown
378384

379385
### `category` Values
380386
```
387+
# Spec-level (WHAT is visualized)
381388
lib # library filter
389+
spec # specification filter
382390
plot # plot_type filter
391+
data # data_type filter
383392
dom # domain filter
384393
feat # features filter
385-
data # data_type filter
386-
spec # specification filter
394+
395+
# Impl-level (HOW it is implemented)
396+
dep # dependencies filter
397+
tech # techniques filter
398+
pat # patterns filter
399+
prep # dataprep filter
400+
style # styling filter
387401
```
388402

389403
### `tab` Values

0 commit comments

Comments
 (0)