closes #120

doc/examples/example_cli_famos.ipynb

@@ -33,6 +33,7 @@
     "\n",
     "from example_cli_famos_helpers import (\n",
     "    parse_summary_to_progress_list,\n",
+    "    petab_select_problem_yaml,  # noqa: F401\n",
     ")\n",
     "\n",
     "output_path = Path().resolve() / \"output_famos\"\n",
@@ -141,8 +142,8 @@
      "name": "stderr",
      "output_type": "stream",
      "text": [
-      "/home/dilan/Documents/future_annex/model_selection/packages/petab_select/petab_select/candidate_space.py:376: RuntimeWarning: Model `model_subspace_1-0001011010010010` has been previously excluded from the candidate space so is skipped here.\n",
-      "  warnings.warn(\n"
+      "petab_select/candidate_space.py:1137: RuntimeWarning: Model `model_subspace_1-0001011010010010` has been previously excluded from the candidate space so is skipped here.\n",
+      "  return_value = self.inner_candidate_space.consider(model)\n"
      ]
     },
     {
@@ -173,7 +174,6 @@
    ],
    "source": [
     "%%bash -s \"$petab_select_problem_yaml\" \"$output_path_str\"\n",
-    "\n",
     "petab_select_problem_yaml=$1\n",
     "output_path_str=$2\n",
     "\n",

doc/examples/example_cli_famos_calibration_tool.py

@@ -7,14 +7,12 @@
 models_yaml = sys.argv[1]
 calibrated_models_yaml = sys.argv[2]
 
-models = petab_select.model.models_from_yaml_list(models_yaml)
+models = petab_select.Models.from_yaml(models_yaml)
 predecessor_model_hashes = set()
 for model in models:
     calibrate(model=model)
     predecessor_model_hashes |= {model.predecessor_model_hash}
-petab_select.model.models_to_yaml_list(
-    models=models, output_yaml=calibrated_models_yaml
-)
+models.to_yaml(output_yaml=calibrated_models_yaml)
 
 if len(predecessor_model_hashes) == 0:
     pass

doc/examples/workflow_cli.ipynb

@@ -177,7 +177,7 @@
     "output_path_str=$1\n",
     "\n",
     "petab_select end_iteration \\\n",
-    "--state=output/state.dill \\\n",
+    "--state=$output_path_str/state.dill \\\n",
     "--calibrated-models=model_selection/calibrated_models_1.yaml \\\n",
     "--output-models=$output_path_str/models_1.yaml \\\n",
     "--output-metadata=$output_path_str/metadata.yaml \\\n",
@@ -289,7 +289,7 @@
     "petab_select get_best \\\n",
     "--problem model_selection/petab_select_problem.yaml \\\n",
     "--models model_selection/calibrated_models_1.yaml \\\n",
-    "--output output_cli/predecessor_model.yaml\n",
+    "--output $output_path_str/predecessor_model.yaml\n",
     "# create a copy of the original PEtab select problem and update its paths\n",
     "cp model_selection/petab_select_problem.yaml $output_path_str/custom_problem.yaml\n",
     "sed -i 's|- model_space.tsv|- ../model_selection/model_space.tsv|' $output_path_str/custom_problem.yaml\n",
@@ -470,7 +470,7 @@
    "id": "889dedc1",
    "metadata": {},
    "source": [
-    "As we are performing a forward search from `M1_4`, which has two parameters, then all models in this iteration with have 3+ parameters. This model space contains only one model with 3 or more estimated parameters. We finalize the iteration with its calibration results."
+    "As we are performing a forward search from `M1_4`, which has two parameters, then all models in this iteration will have 3+ parameters. This model space contains only one model with 3 or more estimated parameters. We finalize the iteration with its calibration results."
    ]
   },
   {
@@ -531,7 +531,7 @@
    "metadata": {},
    "source": [
     "## Fourth iteration\n",
-    "As there are no models in the model space with 4+ parameters, subsequent forward searches will return no candidate models. This can be used by tools to detect when model selection terminates."
+    "As there are no models in the model space with 4+ parameters, subsequent forward searches will return no candidate models. Tools can detect when to terminate by inspecting the metadata produced by `end_iteration`, as demonstrated at the end of this iteration."
    ]
   },
   {
@@ -600,8 +600,7 @@
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "null\n",
-      "...\n",
+      "[]\n",
       "\n"
      ]
     }
@@ -611,6 +610,43 @@
     "    print(f.read())"
    ]
   },
+  {
+   "cell_type": "code",
+   "execution_count": 16,
+   "id": "02df7ed9-422d-4f28-9b01-8670be873933",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "%%bash -s \"$output_path_str\"\n",
+    "output_path_str=$1\n",
+    "\n",
+    "petab_select end_iteration \\\n",
+    "--state=$output_path_str/state.dill \\\n",
+    "--output-models=$output_path_str/models_4.yaml \\\n",
+    "--output-metadata=$output_path_str/metadata.yaml \\\n",
+    "--relative-paths"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 17,
+   "id": "57e483fd-5ffa-48a4-8c2a-359f6ebd1422",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "terminate: true\n",
+      "\n"
+     ]
+    }
+   ],
+   "source": [
+    "with open(\"output_cli/metadata.yaml\") as f:\n",
+    "    print(f.read())"
+   ]
+  },
   {
    "cell_type": "markdown",
    "id": "7b0b1123",
@@ -622,7 +658,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 16,
+   "execution_count": 18,
    "id": "d5b5087d",
    "metadata": {},
    "outputs": [],
@@ -643,7 +679,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 17,
+   "execution_count": 19,
    "id": "30721bfa",
    "metadata": {},
    "outputs": [
@@ -716,7 +752,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 18,
+   "execution_count": 20,
    "id": "73d54111",
    "metadata": {},
    "outputs": [],
@@ -736,7 +772,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 19,
+   "execution_count": 21,
    "id": "c36564f1",
    "metadata": {},
    "outputs": [
@@ -781,7 +817,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 20,
+   "execution_count": null,
    "id": "d5d03cd6",
    "metadata": {},
    "outputs": [

doc/examples/workflow_python.ipynb

@@ -35,7 +35,7 @@
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "Information about the model selection problem.\n",
+      "Information about the model selection problem:\n",
       "YAML: model_selection/petab_select_problem.yaml\n",
       "Method: forward\n",
       "Criterion: Criterion.AIC\n",
@@ -306,7 +306,7 @@
       "Model ID: M1_2-000\n",
       "Criterion.AIC: 140\n",
       "\n",
-      "\u001B[1mBEST MODEL OF CURRENT ITERATION\u001B[0m\n",
+      "\u001b[1mBEST MODEL OF CURRENT ITERATION\u001b[0m\n",
       "Model subspace ID: M1_3\n",
       "PEtab YAML location: model_selection/petab_problem.yaml\n",
       "Custom model parameters: {'k1': 'estimate', 'k2': 0.1, 'k3': 0}\n",
@@ -356,7 +356,7 @@
       "Model ID: M1_5-000\n",
       "Criterion.AIC: -70\n",
       "\n",
-      "\u001B[1mBEST MODEL OF CURRENT ITERATION\u001B[0m\n",
+      "\u001b[1mBEST MODEL OF CURRENT ITERATION\u001b[0m\n",
       "Model subspace ID: M1_6\n",
       "PEtab YAML location: model_selection/petab_problem.yaml\n",
       "Custom model parameters: {'k1': 'estimate', 'k2': 'estimate', 'k3': 0}\n",
@@ -399,7 +399,7 @@
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "\u001B[1mBEST MODEL OF CURRENT ITERATION\u001B[0m\n",
+      "\u001b[1mBEST MODEL OF CURRENT ITERATION\u001b[0m\n",
       "Model subspace ID: M1_7\n",
       "PEtab YAML location: model_selection/petab_problem.yaml\n",
       "Custom model parameters: {'k1': 'estimate', 'k2': 'estimate', 'k3': 'estimate'}\n",

petab_select/__init__.py

@@ -9,6 +9,7 @@
 from .model import *
 from .model_space import *
 from .model_subspace import *
+from .models import *
 from .problem import *
 from .ui import *