Merge pull request #476 from dirac-institute/notebook_small

Expand demo notebook

notebooks/KBMOD_Demo.ipynb

@@ -75,7 +75,26 @@
     "* 21 different velocity steps from 0 pixels per day and 20 pixels per day\n",
     "* 11 different angles from 0.5 below the default angle (computed based on the ecliptic) to 0.5 above.\n",
     "\n",
-    "We require objects to be found in at least 7 of the time steps."
+    "KBMOD needs a series of configuration parameters to specify all the information about the search. In this notebook we explicitly provide the configuration parameters as a dictionary so users can see what is being specified. However most users will want to use the ``SearchConfiguration`` class. A ``SearchConfiguration`` object uses reasonable defaults when created:\n",
+    "\n",
+    "```\n",
+    "config = SearchConfiguration()\n",
+    "```\n",
+    "\n",
+    "Users can then override values one at a time or by passing a dictionary:\n",
+    "\n",
+    "```\n",
+    "d = {\"im_filepath\": \"Here\", \"encode_num_bytes\": 2}\n",
+    "config.set_multiple(d)\n",
+    "```\n",
+    "\n",
+    "More importantly ``SearchConfiguration`` can read from or written to a YAML file:\n",
+    "\n",
+    "```\n",
+    "config = SearchConfiguration.from_file(file_path)\n",
+    "```\n",
+    "\n",
+    "This allows users to define a per-task configuration and version control it."
    ]
   },
   {
@@ -99,10 +118,6 @@
     "ang_steps = 11\n",
     "ang_arr = [ang_below, ang_above, ang_steps]\n",
     "\n",
-    "# There are 10 images in the demo data. Make sure we see\n",
-    "# the object in at least 7.\n",
-    "num_obs = 7\n",
-    "\n",
     "input_parameters = {\n",
     "    # Required\n",
     "    \"im_filepath\": im_filepath,\n",
@@ -112,7 +127,7 @@
     "    \"v_arr\": v_arr,\n",
     "    \"ang_arr\": ang_arr,\n",
     "    # Important\n",
-    "    \"num_obs\": num_obs,\n",
+    "    \"num_obs\": 7,\n",
     "    \"do_mask\": True,\n",
     "    \"lh_level\": 10.0,\n",
     "    \"gpu_filter\": True,\n",
@@ -131,8 +146,22 @@
     "    \"average_angle\": 0.0,\n",
     "    \"result_filename\": \"./fake_results/results.ecsv\",\n",
     "    \"save_all_stamps\": True,\n",
-    "}\n",
-    "\n",
+    "}"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Once we have defined the search parameters, we can create a ``SearchRunner`` and use one of the run_search functions. In this case we use ``run_search_from_config`` which uses the config to search for the input files."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
     "rs = SearchRunner()\n",
     "results = rs.run_search_from_config(input_parameters)"
    ]
@@ -141,7 +170,12 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "We then check that results were written to an output directory."
+    "We then check that results were written to an output directory. The configuration parameters above specify that KBMOD should write two types of output files:\n",
+    "\n",
+    "1. A combined serialized ``ResultList`` saved as a .ecsv file (``\"result_filename\": \"./fake_results/results.ecsv\")``.\n",
+    "2. (Legacy format) A series of individual output files (``\"res_filepath\": res_filepath``).\n",
+    "\n",
+    "Users can shut off these outputs but passing ``None`` to the configuration options."
    ]
   },
   {
@@ -212,13 +246,20 @@
    "source": [
     "For additional analysis steps, please refer to the kbmod_analysis_demo notebook which uses the data generated by this notebook."
    ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": []
   }
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "Python (.conda-kbmod)",
+   "display_name": "Jeremy's KBMOD",
    "language": "python",
-   "name": "conda-env-.conda-kbmod-py"
+   "name": "kbmod_jk"
   },
   "language_info": {
    "codemirror_mode": {