Link to docs from FAQ (#521)

montanalow · montanalow · commit 3c3893e0f7ad · 2023-01-30T17:47:51.000-08:00
Co-authored-by: Montana Low &lt;montana.low@gmail.com&gt;
diff --git a/pgml-dashboard/README.md b/pgml-dashboard/README.md
@@ -0,0 +1,36 @@
+# PostgresML Dashboard
+
+PostgresML provides a dashboard with analytical views of the training data and model performance, as well as integrated notebooks for rapid iteration. It is primarily written in Rust using [Rocket](https://rocket.rs/) as a lightweight web framework and [SQLx](https://github.com/launchbadge/sqlx) to interact with the database.
+
+Please see the [online documentation](https://postgresml.org/user_guides/setup/quick_start_with_docker/) for general information on installing or deploying PostgresML. This document is intended to help developers set up a local copy of the dashboard. 
+
+## Requirements
+
+The dashboard requires a Postgres database with the [pgml-extension](https://github.com/postgresml/postgresml/tree/master/pgml-extension) to generate the core schema. See that subproject for developer setup.
+
+We develop and test this web application on Linux, OS X, and Windows using WSL2.
+
+## Build process
+
+You'll need to specify a database url for the extension to interact with via an environment variable:
+
+```commandline
+export DATABASE_URL=postgres://user_name:password@localhost:5432/database_name
+```
+
+Build and run:
+
+```commandline
+cargo run
+```
+
+Incremental and automatic compilation for development cycles is supported with: 
+
+```commandline
+cargo watch --exec run
+```
+
+Run tests:
+```commandline
+cargo test
+```
diff --git a/pgml-docs/docs/about/faq.md b/pgml-docs/docs/about/faq.md
@@ -10,7 +10,7 @@ Postgres is widely considered mission critical, and some of the most [reliable](
 
 *How good are the models?*
 
-Model quality is often a trade-off between compute resources and incremental quality improvements. Sometimes a few thousands training examples and an off the shelf algorithm can deliver significant business value after a few seconds of training. PostgresML allows stakeholders to choose several different algorithms to get the most bang for the buck, or invest in more computationally intensive techniques as necessary. In addition, PostgresML automatically applies best practices for data cleaning like imputing missing values by default and normalizing data to prevent common problems in production. 
+Model quality is often a trade-off between compute resources and incremental quality improvements. Sometimes a few thousands training examples and an off the shelf algorithm can deliver significant business value after a few seconds of training. PostgresML allows stakeholders to choose several [different algorithms](/user_guides/training/algorithm_selection/) to get the most bang for the buck, or invest in more computationally intensive techniques as necessary. In addition, PostgresML can automatically apply best practices for [data cleaning](/user_guides/training/preprocessing/)) like imputing missing values by default and normalizing features to prevent common problems in production. 
 
 PostgresML doesn't help with reformulating a business problem into a machine learning problem. Like most things in life, the ultimate in quality will be a concerted effort of experts working over time. PostgresML is intended to establish successful patterns for those experts to collaborate around while leveraging the expertise of open source and research communities.
 
diff --git a/pgml-docs/docs/user_guides/setup/v2/installation.md b/pgml-docs/docs/user_guides/setup/v2/installation.md
@@ -216,46 +216,23 @@ That's it, PostgresML is ready. You can validate the installation by running:
 	(1 row)
 	```
 
-## Dashboard
+## Run the dashboard
 
-The dashboard is a Django application. Installing it requires no special dependencies or commands:
+The dashboard is a web app that can be run against any Postgres database with the extension installed. There is a Dockerfile included with the source code if you wish to run it as a container. Basic installation can be achieved with:
 
+1. Clone the repo (if you haven't already for the extension):
+```bash
+git clone https://github.com/postgresml/postgresml && cd postgresml/pgml-dashboard
+```
 
-=== ":material-linux: :material-microsoft: Linux & WSL"
-
-	Install Python if you don't have it already:
-
-	```bash
-	sudo apt-get update && \
-	sudo apt-get install python3 python3-pip python3-virtualenv
-	```
-
-=== ":material-apple: Mac"
-
-	Install Python if you don't have it already:
-
-	```bash
-	brew install python3
-	```
-
-1. Clone our repository (if you haven't already):
-
-	```bash
-	git clone https://github.com/postgresml/postgresml && \
-	cd postgresml/pgml-dashboard
-	```
-
-2. Setup a virtual environment (recommended but not required):
-
-	```bash
-	virtualenv venv && \
-	source venv/bin/activate
-	```
+2. Set the `DATABASE_URL` environment variable:
+```bash
+export DATABASE_URL=postgres://user_name:password@localhost:5432/database_name
+```
 
-3. Run the dashboard:
+3. Build and run the web application:
+```bash
+cargo run
+```
 
-	```bash
-	pip3 install -r requirements.txt && \
-	python manage.py migrate && \
-	python manage.py runserver
-	```
+The dashboard can be packaged for distribution. You'll need to copy the static files along with the `target/release` directory to your server.
diff --git a/pgml-extension/README.md b/pgml-extension/README.md
@@ -1,16 +1,16 @@
-# PostgresML 2.0
+# PostgresML Extension
 
-PostgresML is a PostgreSQL extension providing end-to-end machine learning inside your database. The extension is written in Rust using `tcdi/pgx` and provides LightGBM, XGBoost and [Linfa](https://github.com/rust-ml/linfa) algorithms.
+PostgresML is a PostgreSQL extension providing end-to-end machine learning inside your database. The extension is primarily written in Rust using [pgx](https://github.com/tcdi/pgx) and provides a SQL interface to various machine learning algorithm implementations such as [XGBoost](https://github.com/dmlc/xgboost), [LightGBM](https://github.com/microsoft/LightGBM), and [other classical methods](https://github.com/rust-ml/linfa).
 
-A backwards compatibility layer to Scikit-learn is provided as well, so the entirety of Scikit, XGBoost and LightGBM are available via the standard Scikit interface using Python. The Python layer is written using `pyo3`.
+Python seems to be the de facto ML industry standard, so we also include "reference" implementations of classical algorithms from Scikit-learn as well for comparison to the Rust implementations, but runtime performance and correctness. The Python integration is written using `pyo3`.
 
-See [our blog](https://postgresml.org/blog/postgresml-is-moving-to-rust-for-our-2.0-release/) for a performance comparison to Python.
+See [our blog](https://postgresml.org/blog/postgresml-is-moving-to-rust-for-our-2.0-release/) for a performance comparison and further motivations.
 
 ## Requirements
 
-PostgresML 2.0 requires Python 3.7 or above and the Rust compiler and toolchain. You can download the Rust compiler [here](https://rust-lang.org).
+PostgresML requires Python 3.7 or above and the Rust compiler and toolchain. You can download the Rust compiler [here](https://rust-lang.org).
 
-We develop this extension on Ubuntu, so it'll work best there, but it's very likely to work on other distros as well. Windows is only supported through WSL2. It's been tested and it works. Mac OS is also supported.
+We develop and test this extension on Linux, OS X, and Windows using WSL2.
 
 ## Dependencies
 
@@ -36,7 +36,7 @@ If your system comes with Python 3.6 or lower, you'll need to install `libpython
 
 ## Update postgresql.conf
 
-PostgresML 2.0 requires to be loaded as a shared library. For local development, this is in `~/.pgx/data-13/postgresql.conf`:
+PostgresML requires to be loaded as a shared library. For local development, this is in `~/.pgx/data-13/postgresql.conf`:
 
 ```
 shared_preload_libraries = 'pgml'     # (change requires restart)
@@ -54,6 +54,19 @@ shared_preload_libraries = 'pgml'     # (change requires restart)
 7. `SELECT * FROM pgml.train('Project name', 'regression', 'pgml.diabetes', 'target', 'xgboost');`
 8. `SELECT target, pgml.predict('Project name', ARRAY[age, sex, bmi, bp, s1, s2, s3, s4, s5, s6]) FROM pgml.diabetes LIMIT 10;`
 
+## Testing
+
+Run unit tests:
+```commandline
+cargo test
+```
+
+Run integration tests:
+```commandline
+cargo pgx run --release
+psql -h localhost -p 28813 -d pgml -f tests/test.sql -P pager
+```
+
 ## Packaging
 
 This requires Docker. Once Docker is installed, you can run:
diff --git a/pgml-extension/examples/image_classification.sql b/pgml-extension/examples/image_classification.sql
@@ -95,6 +95,6 @@ SELECT * FROM pgml.deploy('Handwritten Digits', 'rollback');
 SELECT * FROM pgml.deploy('Handwritten Digits', 'best_score', 'svm');
 
 -- check out the improved predictions
-SELECT target, pgml.predict('Handwritten Digits', image) AS prediction
+SELECT target, pgml.predict('Handwritten Digits', image::FLOAT4[]) AS prediction
 FROM pgml.digits 
 LIMIT 10;
diff --git a/pgml-extension/tests/test.sql b/pgml-extension/tests/test.sql
@@ -4,7 +4,7 @@
 --- Usage:
 ---
 ---   $ cargo pgx run --release
----   $ psql -P pager-off -h localhost -p 28813 -d pgml -f tests/test.sql
+---   $ psql -h localhost -p 28813 -d pgml -f tests/test.sql -P pager
 ---
 \set ON_ERROR_STOP true
 \timing on
