From 85f1ef04b03d4f0dbe137d3d5b8b8572940c9f3c Mon Sep 17 00:00:00 2001 From: Allison Horst Date: Fri, 9 Feb 2024 13:51:51 -0800 Subject: [PATCH] update example readmes --- examples/api/README.md | 2 ++ examples/chess/README.md | 13 +++++++++++ examples/chess/docs/index.md | 4 ++-- examples/eia/README.md | 2 ++ examples/google-analytics/README.md | 4 +++- examples/hello-world/README.md | 2 ++ examples/mortgage-rates/README.md | 8 ++++--- examples/penguin-classification/README.md | 27 ++++++++++++++++++----- examples/plot/README.md | 4 +++- 9 files changed, 54 insertions(+), 12 deletions(-) create mode 100644 examples/chess/README.md diff --git a/examples/api/README.md b/examples/api/README.md index 50e77be00..76299d739 100644 --- 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 new file mode 100644 index 000000000..960e6a4fc --- /dev/null +++ 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. \ No newline at end of file diff --git a/examples/chess/docs/index.md b/examples/chess/docs/index.md index cd50af41f..c014e0906 100644 --- a/examples/chess/docs/index.md +++ b/examples/chess/docs/index.md @@ -117,11 +117,11 @@ function bumpChart(data, width) {
-

Womens

+

Women’s

${resize((width) => bumpChart(womens, width))}
-

Mens

+

Men’s

${resize((width) => bumpChart(mens, width))}
diff --git a/examples/eia/README.md b/examples/eia/README.md index d3e100b64..08ea4b990 100644 --- 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 About the EIA-930 data 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 index c22498584..f58f5e451 100644 --- 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 index 4d8c9517e..2662f6dbe 100644 --- 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 index 07a9351cc..a1b4e6152 100644 --- 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 index 74df82ff5..c017fe1ed 100644 --- 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`. \ No newline at end of file diff --git a/examples/plot/README.md b/examples/plot/README.md index a859a28f5..adb4545a7 100644 --- 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