Add descriptions and readmes to all examples

FabioRosado · web-flow · commit 4e028ecc1726 · 2024-03-15T18:00:44.000Z
diff --git a/altair/README.md b/altair/README.md
@@ -0,0 +1,9 @@
+# Altair Example
+
+This is an example of how to use `Altair` in `PyScript`, in this application we are using the _movies_ dataset from the `vega_datasets` package to create two graphs. The first graph creates a heatmap of the `IMDB` ratings and the `Rotten Tomatoes` ratings of the movies. The second graph creates a bar chart of the movie genres.
+
+## Libraries Used
+
+- [Altair](https://altair-viz.github.io/)
+- [Pandas](https://pandas.pydata.org/)
+- [Vega Datasets](https://vega.github.io/vega-datasets/)
diff --git a/altair/pyscript.toml b/altair/pyscript.toml
@@ -1,2 +1,3 @@
 name = "Altair"
+description = "An application that uses vega datasets and Vega to plot heatmap and bar graphs.
 packages = ["altair", "pandas", "vega_datasets"]
diff --git a/antigravity/README.md b/antigravity/README.md
@@ -0,0 +1,13 @@
+# Antigravity Example
+
+This application is based on the famous XKCD comic [Python](https://xkcd.com/353/). It creates an `Antigravity` class to load a svg and then use PyScript to display and animate it.
+
+It also shows you how you can import a file and use it in your Pyscript application - have a look at `pyscript.toml` to see how it's done.
+
+## References
+
+- [Pyodide - open_url](https://pyodide.org/en/stable/usage/api/python-api/http.html#pyodide.http.open_url)
+- [Pyodide - set_interval](https://pyodide.org/en/stable/usage/api/python-api/ffi.html#pyodide.ffi.wrappers.set_interval)
+
+
+
diff --git a/antigravity/pyscript.toml b/antigravity/pyscript.toml
@@ -1,4 +1,5 @@
 name = "Antigravity"
+description = "A simple application to display an image and animate it based on the famous XKCD comic."
 
 [files]
 "./antigravity.py" = ""
diff --git a/bokeh/README.md b/bokeh/README.md
@@ -0,0 +1,10 @@
+# Bokeh Example
+
+This simple application uses both `Pandas` and `Bokeh` to create a simple interactive plot with `PyScript`. We are using circles with orange colour and a size of 15 to represent the data points at hardcoded locations. 
+
+This application is a great start if you want to start with `Bokeh` and `Pandas` in `PyScript`.
+
+## Libraries Used
+
+- [Bokeh](https://bokeh.org/)
+- [Pandas](https://pandas.pydata.org/)
diff --git a/bokeh/pyscript.toml b/bokeh/pyscript.toml
@@ -1,2 +1,3 @@
 name = "Bokeh"
+description = "Simple application that uses Pandas and Bokeh to plot a graph."
 packages = ["pandas", "bokeh==3.2.2", "xyzservices"]
diff --git a/d3/README.md b/d3/README.md
@@ -0,0 +1,13 @@
+# D3 Example
+
+This application uses the D3 library to create a pie graph using some hardcoded data. We use this data to create a graph both in javascript and in PyScript to show you how you can use one or the other to create a graph.
+
+
+## Libraries Used
+
+- [D3](https://d3js.org/)
+
+## References
+
+- [Pyodide - create_proxy](https://pyodide.org/en/stable/usage/api/python-api/ffi.html#pyodide.ffi.create_proxy)
+- [Pyodide - to_jw](https://pyodide.org/en/stable/usage/api/python-api/ffi.html#pyodide.ffi.to_js)
diff --git a/d3/pyscript.toml b/d3/pyscript.toml
@@ -1 +1,2 @@
 name = "D3 Visualization"
+description = "A simple application that uses D3 to plot a graph both in Javascript and Pyscript."
diff --git a/folium/README.md b/folium/README.md
@@ -0,0 +1,15 @@
+# Folium Example
+
+This application uses the `Folium` library to create a map of the United States and then uses Pandas to load a dataset of the unemployment rate in the US on October 2021. We then use this data to create a choropleth map of the unemployment rate in the US.
+
+## Libraries Used
+
+- [Folium](https://python-visualization.github.io/folium/)
+- [Pandas](https://pandas.pydata.org/)
+
+## References
+
+- [Folium - Choropleth](https://python-visualization.github.io/folium/latest/reference.html#folium.features.Choropleth)
+- [Folium - Map](https://python-visualization.github.io/folium/modules.html#folium.folium.Map)
+- [Pandas - Read CSV](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.read_csv.html)
+- [Pyodide - open_url](https://pyodide.org/en/stable/usage/api/python-api/http.html#pyodide.http.open_url)
diff --git a/folium/pyscript.toml b/folium/pyscript.toml
@@ -1,2 +1,3 @@
 name = "Folium"
+description = "A simple application that uses pandas and folium to draw heatmaps on a map."
 packages = ["folium", "pandas"]
diff --git a/fractals_with_numpy_and_canvas/README.md b/fractals_with_numpy_and_canvas/README.md
@@ -0,0 +1,9 @@
+# Fractals with Numpy and Canvas Example
+
+This example demonstrates how to use Numpy and Canvas to create a web-based visualization of the Mandelbrot and Julia set.
+
+## Libraries Used
+
+- [Numpy](https://numpy.org): The fundamental package for scientific computing with Python
+- [Canvas](https://developer.mozilla.org/en-US/docs/Web/API/Canvas_API): A web-based, JavaScript drawing API
+- [SymPy](https://www.sympy.org): A Python library for symbolic mathematics
diff --git a/fractals_with_numpy_and_canvas/pyscript.toml b/fractals_with_numpy_and_canvas/pyscript.toml
@@ -1,4 +1,5 @@
 name = "Fractals with Numpy and Canvas"
+description = "Render Fractals using Numpy, Canvas in Pyscript."
 packages = ["numpy", "sympy"]
 
 [files]
diff --git a/hello_world/README.md b/hello_world/README.md
@@ -0,0 +1,7 @@
+# Hello World Example
+
+This is a basic example of how to create a `PyScript` application that adds a terminal to the page and prints "Hello World" to it. This example is meant to be a starting point for creating more complex applications.
+
+## Resources
+
+- [Pyscript - Terminal](https://pyscript.github.io/docs/2024.3.1/user-guide/terminal/)
diff --git a/hello_world/pyscript.toml b/hello_world/pyscript.toml
@@ -1 +1,2 @@
 name = "Hello World"
+description = "Basic hello world example in PyScript."
diff --git a/icosahedron/README.md b/icosahedron/README.md
@@ -0,0 +1,5 @@
+# WebGL Icosahedron
+
+This example demonstrates how to use Three.js, WebGL and PyScript to create a web-based 3D visualization of an icosahedron.
+
+This example could be a good start if you wish to use Three.js in your own PyScript applications.
diff --git a/icosahedron/pyscript.toml b/icosahedron/pyscript.toml
@@ -1 +1,2 @@
 name = "WebGL Icosahedron"
+description = "An example how to use Three.js and WebGL to render an Icosahedron in PyScript."
diff --git a/matplotlib/README.md b/matplotlib/README.md
@@ -0,0 +1,13 @@
+# Matplotlib Example
+
+This application uses Matplotlib and Numpy to create a Delaunay triangulation of a set of points and then uses the Pyscript `display` feature to display the graph on the page.
+
+## Libraries Used
+
+- [Matplotlib](https://matplotlib.org/)
+- [Numpy](https://numpy.org/)
+
+## Resources
+
+- [Pyscript - Display](https://pyscript.github.io/docs/2024.3.1/user-guide/builtins/#pyscriptdisplay)
+- [Matplotlib - Delaunay Triangulation](https://matplotlib.org/stable/gallery/images_contours_and_fields/tripcolor_demo.html)
diff --git a/matplotlib/pyscript.toml b/matplotlib/pyscript.toml
@@ -1,2 +1,3 @@
 name = "Matplotlib"
+description = "A simple application showing how to use Matplotlib to generate a graph and display it with PyScript."
 packages = ["matplotlib"]
diff --git a/pandas/README.md b/pandas/README.md
@@ -0,0 +1,13 @@
+# Pandas Example
+
+This application uses `Pandas` to load a CSV file and display the data in a table on the page. It also includes an input field and a button which allows you to change the data to be loaded in the table.
+
+## Libraries Used
+
+- [Pandas](https://pandas.pydata.org/)
+
+## Resources
+
+- [Pyscript - Display](https://pyscript.github.io/docs/2024.3.1/user-guide/builtins/#pyscriptdisplay)
+- [Pandas - Read CSV](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.read_csv.html)
+- [Pyodide - open_url](https://pyodide.org/en/stable/usage/api/python-api/http.html#pyodide.http.open_url)
diff --git a/pandas/pyscript.toml b/pandas/pyscript.toml
@@ -1,2 +1,3 @@
 name = "Pandas"
+description = "A simple application that loads a csv and displays a table of its contents."
 packages = ["pandas"]
diff --git a/panel/README.md b/panel/README.md
@@ -0,0 +1,7 @@
+# Simple Panel Example
+
+This is a basic example of a Panel application with PyScript - similar to the Hello World application, this example is aimed for you to get up and running with Panel and PyScript so you can extend it to your own needs.
+
+## Libraries Used
+
+- [Panel](https://panel.holoviz.org/)
diff --git a/panel/pyscript.toml b/panel/pyscript.toml
@@ -1,2 +1,3 @@
 name = "Simple Panel"
+description = "A basic Panel application to be used with PyScript."
 packages = ["panel", "bokeh==3.2.2"]
diff --git a/panel_deckgl/README.md b/panel_deckgl/README.md
@@ -0,0 +1,11 @@
+# NYC Taxi Panel DeckGL Example
+
+This example demonstrates how to use Panel and DeckGL to create a web-based dashboard for exploring a large dataset of taxi trips in New York City. The example uses the [NYC Taxi Dataset](https://www1.nyc.gov/site/tlc/about/tlc-trip-record-data.page) to visualize the pickup and dropoff locations of taxi trips on a map, and to explore the distribution of trip attributes such as trip distance, fare amount, and tip amount.
+
+## Libraries Used
+
+- [Panel](https://panel.holoviz.org): A high-level app and dashboarding solution for Python
+- [DeckGL](https://deck.gl): A WebGL-powered framework for visual exploratory data analysis of large datasets
+- [Bokeh](https://bokeh.org): A powerful framework for building web-based interactive visualizations
+- [Pandas](https://pandas.pydata.org): A fast, powerful, flexible, and easy-to-use open-source data analysis and data manipulation library built on top of the Python programming language
+- [NumPy](https://numpy.org): The fundamental package for scientific computing with Python
diff --git a/panel_kmeans/README.md b/panel_kmeans/README.md
@@ -0,0 +1,20 @@
+# Panel KMeans Examples
+
+This application provides an example of **building a simple dashboard using Panel**.
+
+It demonstrates how to take the output of **k-means
+clustering on the Penguins dataset** using scikit-learn,
+parameterizing the number of clusters and the variables to
+plot.
+
+The plot and the table are linked, i.e. selecting on the plot
+will filter the data in the table. The **`x` marks the center** of the cluster.
+
+## Libraries Used
+
+- [Panel](https://panel.holoviz.org/)
+- [Bokeh](https://bokeh.org/)
+- [Altair](https://altair-viz.github.io/)
+- [scikit-learn](https://scikit-learn.org/stable/)
+- [NumPy](https://numpy.org/)
+- [Pandas](https://pandas.pydata.org/)
diff --git a/panel_kmeans/pyscript.toml b/panel_kmeans/pyscript.toml
@@ -1,2 +1,3 @@
 name = "KMeans in Panel"
+description = "An example of how to build a dashboard using Panel".
 packages = ["bokeh==3.2.2", "altair", "numpy", "pandas", "scikit-learn", "panel"]
diff --git a/panel_streaming/README.md b/panel_streaming/README.md
@@ -0,0 +1,10 @@
+# Panel Streaming Example
+
+This application provides an example of how to handle streaming data and display it in a Panel application.
+
+## Libraries Used
+
+- [Panel](https://panel.holoviz.org/)
+- [Bokeh](https://bokeh.org/)
+- [NumPy](https://numpy.org/)
+- [Pandas](https://pandas.pydata.org/)
diff --git a/panel_streaming/pyscript.toml b/panel_streaming/pyscript.toml
@@ -1,2 +1,3 @@
 name = "Streaming in Panel"
+description = "Simple Panel application showing how to handle streaming data."
 packages = ["bokeh==3.2.2", "numpy", "pandas", "panel"]
diff --git a/panel_with_hvplot/README.md b/panel_with_hvplot/README.md
@@ -0,0 +1,10 @@
+# Panel and hvPlot Example
+
+This application provides an example of how to use [hvPlot](https://hvplot.holoviz.org/) and [Panel](https://panel.holoviz.org/) to create an interactive data visualization application.
+
+## Libraries Used
+
+- [Panel](https://panel.holoviz.org/)
+- [hvPlot](https://hvplot.holoviz.org/)
+- [Pandas](https://pandas.pydata.org/)
+- [Numpy](https://numpy.org/)
diff --git a/panel_with_hvplot/main.py b/panel_with_hvplot/main.py
@@ -1,20 +1,25 @@
-import panel as pn
 import hvplot.pandas
-import pandas as pd
 import numpy as np
-
 from js import console
 from pyodide_http import patch_all
+
+import pandas as pd
+import panel as pn
+
 patch_all()
 
-pn.extension(design='material')
+pn.extension(design="material")
 
-csv_file = ("https://raw.githubusercontent.com/holoviz/panel/main/examples/assets/occupancy.csv")
+csv_file = (
+    "https://raw.githubusercontent.com/holoviz/panel/main/examples/assets/occupancy.csv"
+)
 data = pd.read_csv(csv_file, parse_dates=["date"], index_col="date")
 console.log("Downloaded data")
 
 # Panel Widgets
-variable_widget = pn.widgets.Select(name="variable", value="Temperature", options=list(data.columns))
+variable_widget = pn.widgets.Select(
+    name="variable", value="Temperature", options=list(data.columns)
+)
 window_widget = pn.widgets.IntSlider(name="window", value=30, start=1, end=60)
 sigma_widget = pn.widgets.IntSlider(name="sigma", value=10, start=0, end=20)
 console.log("Set up widgets!")
@@ -28,18 +33,20 @@
 outliers = np.abs(residual) > std * sigma_widget
 
 ## Plot the average variable line together with the outliers as points
-pipeline = (
-    avg.hvplot(height=300, width=400, color="blue", legend=False)
-    * avg[outliers].hvplot.scatter(color="orange", padding=0.1, legend=False)
-)
+pipeline = avg.hvplot(height=300, width=400, color="blue", legend=False) * avg[
+    outliers
+].hvplot.scatter(color="orange", padding=0.1, legend=False)
 
 # Compute the number of outliers
 count = outliers.pipe(
     lambda s: pn.indicators.Number(
-        name='Outliers count', value=s.sum(),
-        colors=[(10, 'green'), (30, 'gold'), (np.Inf, 'red')]
+        name="Outliers count",
+        value=s.sum(),
+        colors=[(10, "green"), (30, "gold"), (np.Inf, "red")],
     )
 )
 
 # Servable App
-pn.Column(pipeline.widgets(), pn.Row(count.output(), pipeline.output())).servable(target='panel')
+pn.Column(pipeline.widgets(), pn.Row(count.output(), pipeline.output())).servable(
+    target="panel"
+)
diff --git a/panel_with_hvplot/pyscript.toml b/panel_with_hvplot/pyscript.toml
@@ -1,2 +1,3 @@
 name = "Panel and hvPlot"
+description = "Leverage hvPlot interactive feature and extending it with Panel."
 packages = ["bokeh==3.2.2", "panel", "markdown-it-py", "numpy", "pandas", "hvplot", "pyodide-http"]
diff --git a/py-jokes/README.md b/py-jokes/README.md
@@ -0,0 +1,10 @@
+# Pyjokes Example
+
+This application provides an example of how to install the package `Pyjokes` and then use it in a PyScript application.
+
+Look at the `pyscript.toml` file and see how we are specifying the `pyjokes` package as a dependency and then using it in the `main.py` file.
+
+
+## Libraries Used
+
+- [Pyjokes](https://pyjok.es/)
diff --git a/py-jokes/pyscript.toml b/py-jokes/pyscript.toml
@@ -1,2 +1,3 @@
 name = "PyScript Jokes"
+description = "A simple application showing how to install and use a package in PyScript."
 packages = ["pyjokes"]
diff --git a/simple_clock/README.md b/simple_clock/README.md
@@ -0,0 +1,5 @@
+# Simple Clock Example
+
+This is a basic application showing how you can display the current time in PyScript and how to update the time every second.
+
+It uses the `async` parameter in the `script` that loads pyscript to allow for the use of `async` functions and `await` calls.
diff --git a/simple_clock/pyscript.toml b/simple_clock/pyscript.toml
@@ -1 +1,2 @@
 name = "Simple Clock"
+description = "Simple application to display the time on the page."
diff --git a/tic-tac-toe/README.md b/tic-tac-toe/README.md
@@ -0,0 +1,3 @@
+# Tic-Tac-Toe
+
+This application provides a full working Tic-Tac-Toe game using PyScript where two players can start a game and play on the same computer.
diff --git a/tic-tac-toe/pyscript.toml b/tic-tac-toe/pyscript.toml
@@ -1 +1,2 @@
 name = "Tic Tac Toe"
+description = "A Tic-Tac-Toe game written in PyScript that allows to people take turns."
diff --git a/todo/README.md b/todo/README.md
@@ -0,0 +1,3 @@
+# TODO Example
+
+This application provides an example of how to create a simple To-Do list using `PyScript`.
diff --git a/todo/pyscript.toml b/todo/pyscript.toml
@@ -1 +1,2 @@
 name = "Todo App"
+description = "A simple To Do application written in PyScript."

Original file line number	Diff line number	Diff line change
`@@ -1,2 +1,3 @@`
`1`	`1`	`name = "Altair"`
	`2`	`+description = "An application that uses vega datasets and Vega to plot heatmap and bar graphs.`
`2`	`3`	`packages = ["altair", "pandas", "vega_datasets"]`
Original file line number	Diff line number	Diff line change
`@@ -1,2 +1,3 @@`
`1`	`1`	`name = "Bokeh"`
	`2`	`+description = "Simple application that uses Pandas and Bokeh to plot a graph."`
`2`	`3`	`packages = ["pandas", "bokeh==3.2.2", "xyzservices"]`
Original file line number	Diff line number	Diff line change
`@@ -1 +1,2 @@`
`1`	`1`	`name = "D3 Visualization"`
	`2`	`+description = "A simple application that uses D3 to plot a graph both in Javascript and Pyscript."`
Original file line number	Diff line number	Diff line change
`@@ -1,2 +1,3 @@`
`1`	`1`	`name = "Folium"`
	`2`	`+description = "A simple application that uses pandas and folium to draw heatmaps on a map."`
`2`	`3`	`packages = ["folium", "pandas"]`