restructure examples directory and README for better readability and …

…sorting by function followed by language implementation

examples/README.md

@@ -3,37 +3,46 @@
 In order to run the examples, make sure that you have datmo properly installed with the latest 
 stable or development version.
 
-## Bash Scripts
+## Using the Examples
+### CLI
+1. `$ pip install datmo` or `$ git clone https://github.com/datmo/datmo`
+2. Navigate to desired project folder
+3. Copy/save example files within project folder
+4. Open the `SCRIPT_NAME.sh` file in a text editor and run the commands individually, or run `$ bash SCRIPT_NAME.sh`
+
+### Python
+1. `$ pip install datmo`
+2. Navigate to desired project folder
+3. `$ datmo init`
+4. Copy/save example files within project folder
+5. Run `python SCRIPT_NAME.py`
+
+### Jupyter Notebook
+1. `$ pip install datmo`
+2. Navigate to desired project folder
+3. `$ datmo init`
+4. Copy/save files within project folder
+5. Run `jupyter notebook`, navigate to `.ipynb` file
+6. Run cells in order
+
+
+## Examples
+#### Creating a Snapshot
+* CLI
+	* TBD
+* Python
+	* [sklearn iris classifier](/examples/python/snapshot_create_iris_sklearn.py)
+* Jupyter notebook
+	* [sklearn iris classifier](/examples/jupyter_notebook/snapshot_create_iris_sklearn.ipynb)
+
+#### Running a containerized task (with option to create Snapshot)
+* CLI
+	* Run a training script (any language) (Coming soon)
+	* Run an inference script (any language) (Coming soon)
+* Python
+	* [Train a basic sklearn iris classifier](/examples/python/task_run_iris_sklearn/basic_task.py)
+	* [Run multiple tasks and snapshot the best result](/examples/python/task_run_iris_sklearn/basic_task.py)
+    * Perform inference on saved model (iris sklearn) (Coming soon)
+* Jupyter notebook
+    * TBD
 
-Bash scripts are meant to show you an entire flow for creating a datmo project, running a particular command
-and seeing the output. These scripts result in new repositories that will contain the project in question. 
-You can run them with the following command -- example given is for the iris sklearn example
-
-```
-$ bash iris-sklearn.sh
-```
-
-Once the scripts are finished they will have created a project folder which you can navigate to and 
-run datmo commands in to see how it works. 
-
-## Python Scripts
-
-Datmo python scripts that `import datmo` must be run within a Datmo-enabled repository. Enabling datmo is as simple as
-running a `datmo init` within an existing directory. The directory can already have your model code or can 
-be completely empty. 
-
-Python scripts that do not include `import datmo` are meant to be like any other script you are already running. 
-They can be run completely separately and do not need to run within a datmo-enabled repository, but they can be 
-called and referenced in scripts that run datmo tasks. 
-
-In order to run any of the scripts present in this `examples/` directory, you can do the following: 
-1) copy over the script to an empty repo or an existing repo
-2) run the following within the destination directory `datmo init` to ensure it is a datmo-enabled repo
-3) run the script: `python SCRIPT.py` or if it is a Jupyter Notebook `jupyter notebook` and run the cells
-
-For any of the directories present within the `examples/` directory, they require more than just the script. 
-In this case you can do the following:
-1) copy the entire directory to an empty repo or an existing repo
-2) run the following within the destination directory `datmo init` to ensure it is a datmo-enabled repo
-3) navigate to within the directory in the repo 
-4) run the script: `python SCRIPT.py` or if it is a Jupyter Notebook `jupyter notebook` and run the cells

examples/iris_sklearn.sh → examples/cli/snapshot_create_iris_sklearn.sh

@@ -1,5 +1,6 @@
 #!/usr/bin/env bash
 
+# --- TEMPORARY ---
 # This script will create a datmo-enabled repository called `iris_sklearn`
 # run the initial script to create a snapshot and will list out the snapshots
 # by calling the `datmo snapshot ls` command
@@ -20,5 +21,4 @@ cp ../iris_sklearn.ipynb .
 python iris_sklearn.py
 
 # Run the datmo command to list all snapshots
-datmo snapshot ls
-
+datmo snapshot ls

examples/iris_sklearn.py → examples/python/snapshot_create_iris_sklearn.py

@@ -1,11 +1,11 @@
 from sklearn import datasets
 from sklearn.linear_model import LogisticRegression
 from sklearn.model_selection import train_test_split
-import datmo  # extra line
+import datmo # extra line
 
 # Run `$ datmo init` in your terminal to instantiate a Datmo project
 
-config = {"solver": "newton-cg"}  # extra line
+config = { "solver": "newton-cg" } # extra line
 iris_dataset = datasets.load_iris()
 X, y = iris_dataset.data, iris_dataset.target
 X_train, X_test, y_train, y_test = train_test_split(X, y)
@@ -17,6 +17,5 @@
 print(train_acc)
 print(test_acc)
 
-stats = {"train_accuracy": train_acc, "test_accuracy": test_acc}  # extra line
-datmo.snapshot.create(
-    message="my first snapshot", config=config, stats=stats)  # extra line
+stats = { "train_accuracy": train_acc, "test_accuracy": test_acc } # extra line
+datmo.snapshot.create(message="my first snapshot", config=config, stats=stats) # extra line

examples/python/task_run_iris_sklearn/basic_task.py

@@ -0,0 +1,26 @@
+import datmo
+
+"""
+WHAT IT DOES: 
+    Instantiates a new task object, and runs the task inside of local container.
+    As this is run within a datmo project with python dependencies, the
+    environment will automatically be generated from the file dependencies.
+
+INSTRUCTIONS
+    1. Instantiate your current folder as a Datmo project with:
+    $ datmo init --name="basic iris model" --description="run an iris sklearn training script as a task"
+
+    2. Run this script to create a snapshot
+    $ python task_compare.py
+
+    3. Run this datmo command to view the snapshot:
+    $ datmo snapshot ls
+"""
+
+task = datmo.task.run(command="python train_model_1.py")
+
+print(task.files())
+print(task.results)
+
+# create a snapshot from the task id directly
+snapshot = datmo.snapshot.create_from_task(message="my great snapshot", task_id=task.id)

examples/python/task_run_iris_sklearn/task_compare.py

@@ -0,0 +1,31 @@
+import datmo
+
+"""
+WHAT IT DOES: 
+	Instantiates new task objects, and runs tasks inside of local container.
+	As this is run within a datmo project with python dependencies, the
+	environment will automatically be generated from the file dependencies.
+
+INSTRUCTIONS
+	1. Instantiate your current folder as a Datmo project with:
+	$ datmo init --name="Iris sklearn model comparison" --description="create sklearn models for iris data using tasks, and compare their results with snapshots"
+    
+	2. Run this script to create a snapshot
+	$ python task_compare.py
+
+	3. Run this datmo command to list all snapshots in this Datmo project:
+	$ datmo snapshot ls
+"""
+
+task_1 = datmo.task.run(command="python train_model_1.py")
+task_2 = datmo.task.run(command="python train_model_2.py")
+
+# create a single snapshot from the task id directly, depending on which model was more accurate
+if task_1.results['test accuracy'] > task_2.results['test accuracy']:
+    print("creating a snapshot with model 1")
+    snapshot = datmo.snapshot.create_from_task(
+        message="my great snapshot", task_id=task_1.id)
+else:
+    print("creating a snapshot with model 2")
+    snapshot = datmo.snapshot.create_from_task(
+        message="my great snapshot", task_id=task_2.id)