update example readmes (#741)

Co-authored-by: Allison Horst <[email protected]>
observablehq · Feb 9, 2024 · dc6d5de · dc6d5de
1 parent 0fc1f3d
commit dc6d5de
Show file tree

Hide file tree

Showing 9 changed files with 54 additions and 12 deletions.
diff --git a/examples/api/README.md b/examples/api/README.md
@@ -2,6 +2,8 @@
 
 This is an example Observable Framework project. It uses API logs data collected from [observablehq.com](observablehq.com), and visualizes them as heatmaps, histograms and bar charts.
 
+View the [live project](https://observablehq.com/framework/examples/api/). 
+
 ## Data loaders
 
 The datasets used are static snapshots. We use an [Apache Arrow](https://arrow.apache.org/) file to handle the large number of API logs.

diff --git a/examples/chess/README.md b/examples/chess/README.md
@@ -0,0 +1,13 @@
+# Chess
+
+This page displays chess rankings from the [International Chess Federation](http://ratings.fide.com/) for the past year.
+
+View the [live project](https://observablehq.com/framework/examples/chess/).
+
+## Data loaders
+
+A single JavaScript data loader, `top-ranked-players.json.js`, accesses the data (in a Zip archive) from the site above, performs some basic wrangling, and writes the simplified snapshot of rankings in JSON format to standard out. 
+
+## Charts
+
+Bump charts are made with [Observable Plot](https://observablehq.com/plot/), and highlight changes in ratings for the top Women’s and Men’s chess players over time. 
diff --git a/examples/chess/docs/index.md b/examples/chess/docs/index.md
@@ -117,11 +117,11 @@ function bumpChart(data, width) {
 
 <div class="grid">
   <div class="card">
-    <h1>Womens</h1>
+    <h1>Women’s</h1>
     ${resize((width) => bumpChart(womens, width))}
   </div>
   <div class="card">
-    <h1>Mens</h1>
+    <h1>Men’s</h1>
     ${resize((width) => bumpChart(mens, width))}
   </div>
 </div>
diff --git a/examples/eia/README.md b/examples/eia/README.md
@@ -4,6 +4,8 @@ This is an example Observable Framework project, based on parts of the US Energy
 
 Visit <a href="https://www.eia.gov/electricity/gridmonitor/about">About the EIA-930 data</a> to learn more about data collection and quality, the US electric grid, and balancing authorities responsible for nationwide electricity interchange.
 
+View the [live project](https://observablehq.com/framework/examples/eia/).
+
 Move the time slider above the map to see how the “[duck curve](https://en.wikipedia.org/wiki/Duck_curve)” of electricity demand varies during the day in different regions, with greater demand in before- and after-work hours, and lower demand during typical working hours.
 
 ## Data loaders

diff --git a/examples/google-analytics/README.md b/examples/google-analytics/README.md
@@ -2,6 +2,8 @@
 
 This dashboard tracks data from Google Analytics using the [Google Analytics Data API](https://developers.google.com/analytics/devguides/reporting/data/v1/quickstart-client-libraries). It contains a single page in `docs/index.md`.
 
+View the [live project](https://observablehq.com/framework/examples/google-analytics/).
+
 ## Data loaders
 
 To connect the data loaders to the Analytics API, you will need to set up a `.env` file at the root of this directory with three variables:
@@ -18,4 +20,4 @@ The Google Analytics [API Quickstart](https://developers.google.com/analytics/de
 
 ## Charts
 
-The dashboard displays a variety of charts, made with Observable Plot. With the key numbers at the top, a line chart or an area chart. Activity by country is represented by a choropleth map. Active users use a horizon chart, faceted by channel. The “new vs. returning” chart is a Marimekko. Finally, the activity by day and hour is a punchcard chart. The code for each of these charts is available in [docs/index.md](https://github.com/observablehq/framework/blob/main/examples/google-analytics/docs/index.md).
+The dashboard displays a variety of charts, made with [Observable Plot](https://observablehq.com/plot/). With the key numbers at the top, a line chart or an area chart. Activity by country is represented by a choropleth map. Active users use a horizon chart, faceted by channel. The “new vs. returning” chart is a Marimekko. Finally, the activity by day and hour is a punchcard chart. The code for each of these charts is available in [docs/index.md](https://github.com/observablehq/framework/blob/main/examples/google-analytics/docs/index.md).
diff --git a/examples/hello-world/README.md b/examples/hello-world/README.md
@@ -1,3 +1,5 @@
 # Hello, world!
 
 This is a minimal example Observable Framework project. It contains a single page in `docs/index.md`, with no configuration file.
+
+View the [live project](https://observablehq.com/framework/examples/hello-world/).
diff --git a/examples/mortgage-rates/README.md b/examples/mortgage-rates/README.md
@@ -1,11 +1,13 @@
 # Mortage tracker
 
-This is an example Observable Framework project. It uses a data loader to track the mortage rates published by Freddie Mac — Federal Home Loan Mortgage Corporation — every week since 1971.
+This is an example Observable Framework project that tracks mortage rates published by Freddie Mac — Federal Home Loan Mortgage Corporation — every week since 1971.
+
+View the [live project](https://observablehq.com/framework/examples/mortgage-rates/). 
 
 ## Data loader
 
-The `docs/data/pmms.csv.ts` loader fetches the data from Freddie Mac’s website. The original dataset is a csv file, with several columns that we don’t need and the classic American date format (month/day/year). The data loader restructures this dataset a little, by minimizing it to three columns (date, in ISO format; 30-year rate; 15-year rate).
+A single TypeScript data loader `docs/data/pmms.csv.ts` fetches the data from Freddie Mac’s website. The original dataset is a csv file, with several columns that we don’t need and the classic American date format (month/day/year). The data loader restructures this dataset a little, by minimizing it to three columns (date, in ISO format; 30-year rate; 15-year rate).
 
 ## Charts
 
-The cards and charts reinterpret the original elements of Freddie Mac’s [PMMS dashboard](https://www.freddiemac.com/pmms). We’re using Observable Plot to draw the charts. The chart code is simple enough to be directly inlined in the page’s markdown `docs/index.md`.
+The cards and charts reinterpret the original elements of Freddie Mac’s [PMMS dashboard](https://www.freddiemac.com/pmms). We use [Observable Plot](https://observablehq.com/plot/) to draw the charts. The chart code is simple enough to be directly inlined in the page’s markdown `docs/index.md`.
diff --git a/examples/penguin-classification/README.md b/examples/penguin-classification/README.md
@@ -1,13 +1,30 @@
+# Penguin classification
 
-- Homebrew install python3
-- Create virtual & activate environment
+This is an example Observable Framework project that uses logistic regression (performed in a Python data loader) to classify penguins by species, based on body mass measurements. Charts highlights and explore which penguins are misclassified. [Learn more](https://journal.r-project.org/articles/RJ-2022-020/) about the penguins dataset.
+
+View the [live project](https://observablehq.com/framework/examples/penguin-classification/).
+
+## Data loader
+
+The Python [data loader](../../docs/loaders.md) `predictions.csv.py` reads in the `penguins.csv` file, then performs logistic regression using scikit-learn's [LogisticRegression](https://scikit-learn.org/stable/modules/generated/sklearn.linear_model.LogisticRegression.html) function.
+
+## Charts
+
+All charts are drawn with [Observable Plot](https://observablehq/com/plot).
+
+## Reuse this example
+
+Copy the contents of the `penguins-classification` directory into a new Observable Framework project. Then, run the following set up steps (as needed) get started: 
+
+- If needed, install python3
+- Create and activate a virtual environment
   - `$ python3 -m venv .venv`
   - `$ source .venv/bin/activate`
 - Pip install modules from requirements.txt
   - `$ pip install -r requirements.txt`
-- Run the CLI
+- Run and preview the page
   - `$ yarn`
   - `$ yarn dev`
+- Make changes to the page (`index.md`) or data loader and save to see instant updates in the [live preview](https://observablehq.com/framework/getting-started#test-live-preview)
 
-[Learn more about deploying with Github actions](https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python#requirements-file) for Python 3.6 & requirements.txt
-
+[Learn more about deploying with Github actions](https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python#requirements-file) for Python 3.6 & `requirements.txt`.
diff --git a/examples/plot/README.md b/examples/plot/README.md
@@ -1,6 +1,8 @@
 # Tracking Observable Plot
 
-This dashboard tracks several metrics about the development and usage of [Observable Plot](https://observablehq.com/plot/). It contains a single page in [`docs/index.md`](./docs/index.md), with no configuration file.
+This is an example Observable Framework project that tracks several metrics about the development and usage of [Observable Plot](https://observablehq.com/plot/). It contains a single page in [`docs/index.md`](./docs/index.md), with no configuration file.
+
+View the [live project](https://observablehq.com/framework/examples/plot/).
 
 ## Data loaders