From f81e28bb231c7ce8d4f342440c9f952c134b9015 Mon Sep 17 00:00:00 2001 From: Wenbo Tao Date: Thu, 3 Sep 2020 11:01:03 -0700 Subject: [PATCH] detailed READMEs for example apps (#154) --- README.md | 2 +- compiler/README.md | 1 - compiler/examples/README.md | 10 ----- compiler/examples/USMap/README.md | 34 +++++++++++++++++ compiler/examples/USMap_cmv/README.md | 38 +++++++++++++++++++ .../examples/dots-pushdown-uniform/README.md | 1 + compiler/examples/dots-skewed-80-20/README.md | 1 + compiler/examples/dots-uniform/README.md | 11 +----- compiler/examples/flare/README.md | 35 +++++++++++++++++ compiler/examples/forest/README.md | 34 +++++++++++++++++ compiler/examples/nba/README.md | 33 ++++++++++++++++ compiler/examples/nba_cmv/README.md | 35 +++++++++++++++++ .../examples/template-api-examples/README.md | 38 +++++++++++++++++++ compiler/examples/template/README.md | 1 + 14 files changed, 253 insertions(+), 21 deletions(-) delete mode 100644 compiler/README.md delete mode 100644 compiler/examples/README.md create mode 100644 compiler/examples/USMap/README.md create mode 100644 compiler/examples/USMap_cmv/README.md create mode 100644 compiler/examples/flare/README.md create mode 100644 compiler/examples/forest/README.md create mode 100644 compiler/examples/nba/README.md create mode 100644 compiler/examples/nba_cmv/README.md create mode 100644 compiler/examples/template-api-examples/README.md create mode 100644 compiler/examples/template/README.md diff --git a/README.md b/README.md index cf023ed5..10016cf9 100644 --- a/README.md +++ b/README.md @@ -21,7 +21,7 @@ Kyrix facilitates the creation of data visualizations with details-on-demand int 1. Install [Docker](https://docs.docker.com/engine/install/) and [Docker Compose](https://docs.docker.com/compose/install/) (must be `v1.17.0` or later). For Mac users, installing [Docker Desktop](https://docs.docker.com/docker-for-mac/install/) will install Docker Compose automatically. Ubuntu 18.04 users can also simply install with `sudo apt update; sudo apt install -y docker.io docker-compose;`. 2. Run `sudo ./run-kyrix.sh --nba --build` in the root directory. You might need to make `run-kyrix.sh` executable, i.e. `sudo chmod +x run-kyrix.sh`. -3. Wait a couple minutes, then point your browser at :8000 - remember that if you are using a cloud instance you may (probably) need to open your cloud provider's firewall for this port. If that sounds scary, you can create an SSH tunnel from your PC (e.g. Mac) using `ssh -N -L 8000::8000` to forward your laptop's port 8000 to the server via [SSH tunneling](https://www.tecmint.com/create-ssh-tunneling-port-forwarding-in-linux/). +3. Wait a couple minutes, then point your browser at `:8000` - remember that if you are using a cloud instance you may (probably) need to open your cloud provider's firewall for this port. If that sounds scary, you can create an SSH tunnel from your PC (e.g. Mac) using `ssh -N -L 8000::8000` to forward your laptop's port 8000 to the server via [SSH tunneling](https://www.tecmint.com/create-ssh-tunneling-port-forwarding-in-linux/). note that you'll need to wait for a message saying `Backend server started...` like this: ``` diff --git a/compiler/README.md b/compiler/README.md deleted file mode 100644 index 74c0ebc7..00000000 --- a/compiler/README.md +++ /dev/null @@ -1 +0,0 @@ -# Compiler for Parsing Kyrix User Spec \ No newline at end of file diff --git a/compiler/examples/README.md b/compiler/examples/README.md deleted file mode 100644 index f1ec4a47..00000000 --- a/compiler/examples/README.md +++ /dev/null @@ -1,10 +0,0 @@ -## Example applications - -Data for four example application can be found here: [nba](https://www.dropbox.com/s/baqb01thxvfthk5/nba_db_psql.sql?dl=0), [usmap](https://www.dropbox.com/s/youvfap909mk1m3/usmap_db_psql.sql?dl=0), [forest](https://www.dropbox.com/s/39ji04m926lfx5i/forest_db_psql.sql?dl=0) and [flare](https://www.dropbox.com/s/ugr3cx63ul3tt0k/flare_db_psql.sql?dl=0). - -To load data of `app` (can be one of `nba`, `usmap`, `forest` or `flare`) into our docker container, run the following under root git directory: - - $ ./docker-scripts/load-sql.sh [appname].sql --dbname app - -Please refer to [the tutorial](https://github.com/tracyhenry/Kyrix/wiki/Tutorial) for more details on how to run an example application. Refer to Section 6 of [this paper](http://web.mit.edu/wenbo/www/kyrix_eurovis.pdf) for more explanation on the example applications. - diff --git a/compiler/examples/USMap/README.md b/compiler/examples/USMap/README.md new file mode 100644 index 00000000..6f152728 --- /dev/null +++ b/compiler/examples/USMap/README.md @@ -0,0 +1,34 @@ +# US Crime Rate Map +

+ + + +

+ +This example app has two canvases. The top-level canvas shows state-level US crime rates, where darker colors indicate higher crime crime rates per 100,000 population. The user can click on a state, and zoom into a detailed county-level crime rate map centered at the clicked state. On the county canvas, the user can pan around. + +# Installation Instructions for the Impatient +After running `sudo ./run-kyrix.sh --nba`, open another terminal tab and run the following commands: +``` +wget https://www.dropbox.com/s/youvfap909mk1m3/usmap_db_psql.sql # download data +sudo ./docker-scripts/load-sql.sh usmap_db_psql.sql --dbname usmap # load data into the database, must be run in root folder +cp docker-scripts/compile.sh compiler/examples/USMap/compile.sh # copy the compile script +cd compiler/examples/USMap # go to the app directory +chmod +x compile.sh # make the compile script excutable +sudo ./compile.sh USMap.js # compile the application +``` +Wait for about one minute, then point your browser at `:8000` - remember that if you are using a cloud instance you may (probably) need to open your cloud provider's +firewall for this port. If that sounds scary, you can create an SSH tunnel from your PC (e.g. Mac) using `ssh -N -L 8000::8000` to forward your laptop's port 8000 to the server via [SSH tunneling](https://www.tecmint.com/create-ssh-tunneling-port-forwarding-in-linux/). + +note that you'll need to wait for a message saying `Backend server started...` like this: +``` +Serving /project +New project definition coming... +There is diff that requires recomputing indexes. Shutting down server and recomputing... +Precomputing... +Done precomputing! +Completed recomputing indexes. Server restarting... +Backend server started... +``` + +Please refer to the [tutorial](https://github.com/tracyhenry/Kyrix/wiki/Tutorial) for more details on how to start writing your own Kyrix application! diff --git a/compiler/examples/USMap_cmv/README.md b/compiler/examples/USMap_cmv/README.md new file mode 100644 index 00000000..4535ccc0 --- /dev/null +++ b/compiler/examples/USMap_cmv/README.md @@ -0,0 +1,38 @@ +# US Crime Rate Map (with two views) +

+ + + +

+ +This example app is a variant of the [USMap application]() with two coordinated views placed side by side. The view on the left shows state-level US crime rates, where darker colors indicate higher crime rates per 100,000 population. The user can click on a state, and populate the view on the right with a detailed county-level crime rate map centered at the clicked state. On the county canvas, the user can pan around. + +In the [embedding API documentation](https://github.com/tracyhenry/Kyrix/wiki/Web-Embedding), we offer an example to embed this Kyrix app into a web app where more controls and a minimap are available. + +# Installation Instructions for the Impatient +After running `sudo ./run-kyrix.sh --nba`, open another terminal tab and run the following commands: +``` +wget https://www.dropbox.com/s/youvfap909mk1m3/usmap_db_psql.sql # download data +sudo ./docker-scripts/load-sql.sh usmap_db_psql.sql --dbname usmap # load data into the database, must be run in root folder +cp docker-scripts/compile.sh compiler/examples/USMap_cmv/compile.sh # copy the compile script +cd compiler/examples/USMap_cmv # go to the app directory +chmod +x compile.sh # make the compile script excutable +sudo ./compile.sh USMap_cmv.js # compile the application +``` +Wait for about one minute, then point your browser at `:8000` - remember that if you are using a cloud instance you may (probably) need to open your cloud provider's +firewall for this port. If that sounds scary, you can create an SSH tunnel from your PC (e.g. Mac) using `ssh -N -L 8000::8000` to forward your laptop's port 8000 to the server via [SSH tunneling](https://www.tecmint.com/create-ssh-tunneling-port-forwarding-in-linux/). + +note that you'll need to wait for a message saying `Backend server started...` like this: +``` +Serving /project +New project definition coming... +There is diff that requires recomputing indexes. Shutting down server and recomputing... +Precomputing... +Done precomputing! +Completed recomputing indexes. Server restarting... +Backend server started... +``` + + + +Please refer to the [tutorial](https://github.com/tracyhenry/Kyrix/wiki/Tutorial) for more details on how to start writing your own Kyrix application! diff --git a/compiler/examples/dots-pushdown-uniform/README.md b/compiler/examples/dots-pushdown-uniform/README.md index 485e7380..6dcb94aa 100644 --- a/compiler/examples/dots-pushdown-uniform/README.md +++ b/compiler/examples/dots-pushdown-uniform/README.md @@ -1,3 +1,4 @@ +# For maintainers only This is an application used to test performance/scalability. For dots-pushdown-uniform, the assumption is that the data is distributed evenly/randomly across the canvas. diff --git a/compiler/examples/dots-skewed-80-20/README.md b/compiler/examples/dots-skewed-80-20/README.md index 7edfe502..d353fb93 100644 --- a/compiler/examples/dots-skewed-80-20/README.md +++ b/compiler/examples/dots-skewed-80-20/README.md @@ -1,3 +1,4 @@ +# For maintainers only This is an application used to test performance/scalability. For -skewed-80-20, the assuming is 80% of the data resides in 20% of the Euclidean space. diff --git a/compiler/examples/dots-uniform/README.md b/compiler/examples/dots-uniform/README.md index 9374dc42..8248bfcc 100644 --- a/compiler/examples/dots-uniform/README.md +++ b/compiler/examples/dots-uniform/README.md @@ -1,11 +1,4 @@ -This is an application used to test performance/scalability. +# For maintainers only +This is an application used to test performance/scalability. For dots-uniform, the assumption is that the data is distributed evenly/randomly across the canvas. - -## Generating data (legacy) -As defined in `transform.js`, running this app needs a database `dots` with a relation `dots`, whose schema is `create table dots (id int, x int, y int);`. The data generator `/datagen/gen.cpp` can generate a file which you can use to populate the `dots` relation (e.g. in Postgres, `COPY dots FROM 'absolute/path/to/data/file'`). You can modify `num_points` in the cpp file to vary the number of total points. - -## Running the app -You need to change the first line of the kyrix config file to `dots` (name of the app), restart the server, then run `node dots.js`. - -You will see a scatterplot with uniformly distributed dots. There are two zoom levels (double click to zoom in, shift + double click to zoom out). There are three parameters you can tune to adjust visual density (which greatly affects performance): `num_points` in the data generator, `topWidth` and `topHeight` in `dots.js`.If you have Trypophobia, be careful not to make it too dense.... diff --git a/compiler/examples/flare/README.md b/compiler/examples/flare/README.md new file mode 100644 index 00000000..2c0474f5 --- /dev/null +++ b/compiler/examples/flare/README.md @@ -0,0 +1,35 @@ +# Flare Class Hierarchy +

+ + + +

+ +This example app visualizes classes in the [Flare visualization library](https://blokt.com/tool/prefuse-flare) in a zoomable circle packing layout. The user can click on a class to zoom into another view showing its direct child classes. This visualization is composed of only one canvas, so the zoom object is a self-loop of this canvas. + + +# Installation Instructions for the Impatient +After running `sudo ./run-kyrix.sh --nba`, open another terminal tab and run the following commands: +``` +wget https://www.dropbox.com/s/ugr3cx63ul3tt0k/flare_db_psql.sql # download data +sudo ./docker-scripts/load-sql.sh flare_db_psql.sql --dbname flare # load data into the database, must be run in root folder +cp docker-scripts/compile.sh compiler/examples/flare/compile.sh # copy the compile script +cd compiler/examples/flare # go to the app directory +chmod +x compile.sh # make the compile script excutable +sudo ./compile.sh flare.js # compile the application +``` +Wait for a couple seconds, then point your browser at `:8000` - remember that if you are using a cloud instance you may (probably) need to open your cloud provider's +firewall for this port. If that sounds scary, you can create an SSH tunnel from your PC (e.g. Mac) using `ssh -N -L 8000::8000` to forward your laptop's port 8000 to the server via [SSH tunneling](https://www.tecmint.com/create-ssh-tunneling-port-forwarding-in-linux/). + +note that you'll need to wait for a message saying `Backend server started...` like this: +``` +Serving /project +New project definition coming... +There is diff that requires recomputing indexes. Shutting down server and recomputing... +Precomputing... +Done precomputing! +Completed recomputing indexes. Server restarting... +Backend server started... +``` + +Please refer to the [tutorial](https://github.com/tracyhenry/Kyrix/wiki/Tutorial) for more details on how to start writing your own Kyrix application! diff --git a/compiler/examples/forest/README.md b/compiler/examples/forest/README.md new file mode 100644 index 00000000..82274e54 --- /dev/null +++ b/compiler/examples/forest/README.md @@ -0,0 +1,34 @@ +# Animals in the Amazon Rainforest +

+ + + +

+ +This example is a map of animals in the Amazon rainforest. There are three canvases, each with two layers. One shows background images. The other layer shows the animals. In the top two canvas, animals are previewed as white dots. In the bottom canvas, images of the animals are shown. The background images in the bottom canvas are higher-resolution versions of those in the top canvases. + +# Installation Instructions for the Impatient +After running `sudo ./run-kyrix.sh --nba`, open another terminal tab and run the following commands: +``` +wget https://www.dropbox.com/s/39ji04m926lfx5i/forest_db_psql.sql # download data +sudo ./docker-scripts/load-sql.sh forest_db_psql.sql --dbname forest # load data into the database, must be run in root folder +cp docker-scripts/compile.sh compiler/examples/forest/compile.sh # copy the compile script +cd compiler/examples/forest # go to the app directory +chmod +x compile.sh # make the compile script excutable +sudo ./compile.sh forest.js # compile the application +``` +Wait for about half a minute, then point your browser at `:8000` - remember that if you are using a cloud instance you may (probably) need to open your cloud provider's +firewall for this port. If that sounds scary, you can create an SSH tunnel from your PC (e.g. Mac) using `ssh -N -L 8000::8000` to forward your laptop's port 8000 to the server via [SSH tunneling](https://www.tecmint.com/create-ssh-tunneling-port-forwarding-in-linux/). + +note that you'll need to wait for a message saying `Backend server started...` like this: +``` +Serving /project +New project definition coming... +There is diff that requires recomputing indexes. Shutting down server and recomputing... +Precomputing... +Done precomputing! +Completed recomputing indexes. Server restarting... +Backend server started... +``` + +Please refer to the [tutorial](https://github.com/tracyhenry/Kyrix/wiki/Tutorial) for more details on how to start writing your own Kyrix application! diff --git a/compiler/examples/nba/README.md b/compiler/examples/nba/README.md new file mode 100644 index 00000000..5607c63a --- /dev/null +++ b/compiler/examples/nba/README.md @@ -0,0 +1,33 @@ +# NBA Basketball Data Visualization + +

+ + + +

+ +This example app visualizes NBA data in the season 2017~2018. There are four canvases, showing different type of entities in the dataset: teams, games, plays and boxscores. Canvases are connected via semantic zooms, allowing users to see related entities of an entity of interest. + +# Installation Instructions for the Impatient +After running `sudo ./run-kyrix.sh --nba`, you should be able to see this application at :8000. If later you want to switch back to this application, you can run the following commands in a separate terminal: + +``` +cp docker-scripts/compile.sh compiler/examples/nba/compile.sh # copy the compile script (run in the root folder) +cd compiler/examples/nba # go to the app directory +chmod +x compile.sh # make the compile script excutable +sudo ./compile.sh nba.js # compile the application +``` +Wait for about one minute, then point your browser at `:8000` - remember that if you are using a cloud instance you may (probably) need to open your cloud provider's firewall for this port. If that sounds scary, you can create an SSH tunnel from your PC (e.g. Mac) using `ssh -N -L 8000::8000` to forward your laptop's port 8000 to the server via [SSH tunneling](https://www.tecmint.com/create-ssh-tunneling-port-forwarding-in-linux/). + +note that you'll need to wait for a message saying `Backend server started...` like this: +``` +Serving /project +New project definition coming... +There is diff that requires recomputing indexes. Shutting down server and recomputing... +Precomputing... +Done precomputing! +Completed recomputing indexes. Server restarting... +Backend server started... +``` + +Please refer to the [tutorial](https://github.com/tracyhenry/Kyrix/wiki/Tutorial) for more details on how to start writing your own Kyrix application! diff --git a/compiler/examples/nba_cmv/README.md b/compiler/examples/nba_cmv/README.md new file mode 100644 index 00000000..96ad1846 --- /dev/null +++ b/compiler/examples/nba_cmv/README.md @@ -0,0 +1,35 @@ +# NBA Basketball Data Visualization (with two views) + +

+ + + +

+ +This example app is a variant of the default NBA application with two coordinated views. The view on the left shows the logos of 30 NBA teams. When clicking on a team, the user can populate the view on the right with the schedule of the clicked team. This schedule is pannable, and allows the user to click on a game to zoom into the boxscore/play-by-play canvas, similar to the default NBA app. + +A key functionality this variant app enables is coordinated selection. Say the view on the right is showing the schedule of the the Boston Celtics. The user can click on another team in the left view, say the Golden State Warriors, to highlight the games between the Celtics and the Warriors. + +# Installation Instructions for the Impatient +After running `sudo ./run-kyrix.sh --nba`, open another terminal tab and run the following commands: + +``` +cp docker-scripts/compile.sh compiler/examples/nba_cmv/compile.sh # copy the compile script (run in the root folder) +cd compiler/examples/nba_cmv # go to the app directory +chmod +x compile.sh # make the compile script excutable +sudo ./compile.sh nba_cmv.js # compile the application +``` +Wait for about one minute, then point your browser at `:8000` - remember that if you are using a cloud instance you may (probably) need to open your cloud provider's firewall for this port. If that sounds scary, you can create an SSH tunnel from your PC (e.g. Mac) using `ssh -N -L 8000::8000` to forward your laptop's port 8000 to the server via [SSH tunneling](https://www.tecmint.com/create-ssh-tunneling-port-forwarding-in-linux/). + +note that you'll need to wait for a message saying `Backend server started...` like this: +``` +Serving /project +New project definition coming... +There is diff that requires recomputing indexes. Shutting down server and recomputing... +Precomputing... +Done precomputing! +Completed recomputing indexes. Server restarting... +Backend server started... +``` + +Please refer to the [tutorial](https://github.com/tracyhenry/Kyrix/wiki/Tutorial) for more details on how to start writing your own Kyrix application! diff --git a/compiler/examples/template-api-examples/README.md b/compiler/examples/template-api-examples/README.md new file mode 100644 index 00000000..a785fdbb --- /dev/null +++ b/compiler/examples/template-api-examples/README.md @@ -0,0 +1,38 @@ +This folder has several examples for higher-level APIs built on top of the [base Kyrix API](https://github.com/tracyhenry/Kyrix/wiki/API-Reference). Currently, only examples for [Kyrix-S](https://github.com/tracyhenry/Kyrix/wiki/Kyrix%E2%80%90S-API-Reference) (files starting with `SSV_`) are well tested. + +## NBA game SSVs (Scalable Scatterplot Visualizations) +Files `SSV_circle.js`, `SSV_contour.js` and `SSV_custom.js` correspond to three different SSVs of NBA games, where X axis is the score of the home team, Y axis is the score of the away team, and games between higher-ranked teams appear on top levels. These three examples respectively represent games using clustered circles, contour lines, and a custom rendered scoreboard. + +

+ +

+ +The data for these three examples are pre-loaded into Docker containers after you run `sudo ./run-kyrix.sh --nba`, so you only need to run the following commands to start them: +``` +cp docker-scripts/compile.sh compiler/examples/template-api-examples/compile.sh # copy the compile script +cd compiler/examples/template-api-examples # go to the app directory +chmod +x compile.sh # make the compile script excutable +sudo ./compile.sh SSV_circle.js # compile the application +``` +Replace `circle` in the last line with `contour` or `custom` to see `SSV_circle` or `SSV_custom`. + +## FIFA video game SSVs +Files `SSV_radar.js` and `SSV_pie.js` correspond to two different SSVs of players in the video game FIFA20. On the left is a radar-chart-based SSV where clusters of players are represented using radar charts that show aggregated player stats on 8 axes. On the right is a pie-chart-based SSV where each pie represents the age group of a cluster of players. + +

+ +

+ +To get these two applications running, run the following commands: +``` +wget https://www.dropbox.com/s/sd5vx2rkdsqcwtv/fifa20.csv # download data +sudo ./docker-scripts/load-csv.sh fifa20.csv # load data into the db container (must be run in the root folder) +cp docker-scripts/compile.sh compiler/examples/template-api-examples/compile.sh # copy the compile script +cd compiler/examples/template-api-examples # go to the app directory +chmod +x compile.sh # make the compile script excutable +sudo ./compile.sh SSV_radar.js # compile the application +``` +Replace `radar` in the last line with `pie` to see `SSV_pie`. + +## Other Template API examples +WIP - stay tuned. diff --git a/compiler/examples/template/README.md b/compiler/examples/template/README.md new file mode 100644 index 00000000..de99ad63 --- /dev/null +++ b/compiler/examples/template/README.md @@ -0,0 +1 @@ +This folder has template specs for a base Kyrix application. Refer to the [tutorial](https://github.com/tracyhenry/Kyrix/wiki/Tutorial) and the [API reference](https://github.com/tracyhenry/Kyrix/wiki/API-Reference) to get started on writing your own Kyrix application!