Merge pull request #6 from kthyng/add_export

added export_variables options, updated docs.

docs/configuration.md

@@ -2,6 +2,8 @@
 
 ## Configuration Overview
 
+Where possible, configuration information includes items like default, input range or enum options, description, units, and value, and the configuration can be queried as demonstrated in these docs to get that information.
+
 Configuration parameters are shown in `m.show_config()` for:
 
 * the specified `drift_model` (from `m._config` which for OpenDriftModel points to `m.o._config`)
@@ -130,7 +132,13 @@ m.show_config("seed:oil_type")
 
 ## Specific Configuration Options
 
-### Ocean Model
+This section is split into two: first options that are available to all models (thus are handled in the Manager) and those for `OpenDriftModel` (the only model option currently).
+
+This is not currently a comprehensive list but a place where extra details are included that might not be clear or available elsewhere. For more information look at the configuration information (previous section) and the docstrings for each class.
+
+### Manager options, available to all models
+
+#### Ocean Model
 
 Setting up an ocean model is also referred to as `add_reader()`.
 
@@ -185,8 +193,43 @@ m = ptm.OpenDriftModel(lon=4.0, lat=60.0, start_time=datetime(2015, 9, 22, 6),
 m.run_all()
 ```
 
+### OpenDriftModel options
+
+#### Drift model
+
+Though `OpenDrift` has more models available, the currently wrapped `drift_model` options in PTM are:
+
+* OceanDrift: physics-only scenario (default)
+* Leeway: scenario for Search and Rescue of various objects at the surface
+* OpenOil: oil spill scenarios
+* LarvalFish: scenario for fish eggs and larvae that can grow
+
+Set these with e.g.:
+
+```
+m = ptm.OpenDriftModel(drift_model="OpenOil")
+```
+
+This selection sets some of the configuration details and export variables that are relevant for the simulation.
+
+
+#### Export Variables
+
+All possible variables will be exported by default into the outfiles and available in memory (`m.o.history` and `m.o.history_metadata` or `m.o.get_property(<key>)` for `OpenDriftModel`).
+
+The full list of possible variables to be exported is available with
+
+```
+m.all_export_variables()
+```
+
+To limit the variables saved in the export file, input a list of just the variables that you want to save, keeping in mind that `['lon', 'lat', 'ID', 'status']` will also be included regardless. For example:
+```
+m = ptm.OpenDriftModel(export_variables=[])
+```
+
 
-### How to modify details for Stokes Drift
+#### How to modify details for Stokes Drift
 
 Turn on (on by default):
 
@@ -220,7 +263,7 @@ m.show_config(key='drift:tabularised_stokes_drift_fetch')
 ```
 
 
-### Vertical Mixing
+#### Vertical Mixing
 
 The user can change the background diffusivity with
 

particle_tracking_manager/cli.py

@@ -110,6 +110,7 @@ def __call__(self, parser, namespace, values, option_string=None):
     # if args.kwargs["ocean_model"] is None and args.kwargs["start_time"] is None:
     #     raise KeyError("Need to either use a reader or input a start_time to avoid error.")
 
-    ptm.OpenDriftModel(**args.kwargs).run_all()
+    m = ptm.OpenDriftModel(**args.kwargs)
+    m.run_all()
 
-    # ptm.ParticleTrackingManager(**args.kwargs).run_all()
+    print(m.outfile_name)

particle_tracking_manager/models/opendrift/model_opendrift.py

@@ -4,6 +4,8 @@
 import logging
 import pathlib
 
+from typing import Optional
+
 import pandas as pd
 import yaml
 
@@ -49,6 +51,8 @@ class OpenDriftModel(ParticleTrackingManager):
     ----------
     drift_model : str, optional
         Options: "OceanDrift", "LarvalFish", "OpenOil", "Leeway", by default "OceanDrift"
+    export_variables : list, optional
+        List of variables to export, by default None. See PTM docs for options.
     radius : int, optional
         Radius around each lon-lat pair, within which particles will be randomly seeded. This is used by function `seed_elements`.
     radius_type : str
@@ -134,6 +138,7 @@ class OpenDriftModel(ParticleTrackingManager):
     def __init__(
         self,
         drift_model: str = config_model["drift_model"]["default"],
+        export_variables: str = config_model["export_variables"]["default"],
         radius: int = config_model["radius"]["default"],
         radius_type: str = config_model["radius_type"]["default"],
         horizontal_diffusivity: float = config_model["horizontal_diffusivity"][
@@ -482,6 +487,7 @@ def run_drifters(self):
         self.o.run(
             time_step=timedir * self.time_step,
             steps=self.steps,
+            export_variables=self.export_variables,
             outfile=f"output-results_{datetime.datetime.utcnow():%Y-%m-%dT%H%M:%SZ}.nc",
         )
 
@@ -577,6 +583,22 @@ def _add_model_config(self):
         # this step brings other model config (plus additions from mapped parameter config) into the overall config
         self._config.update(dictC)
 
+    def all_export_variables(self):
+        """Output list of all possible export variables."""
+
+        vars = (
+            list(self.o.elements.variables.keys())
+            + ["trajectory", "time"]
+            + list(self.o.required_variables.keys())
+        )
+
+        return vars
+
+    def export_variables(self):
+        """Output list of all actual export variables."""
+
+        return self.o.export_variables
+
     def get_configspec(self, prefix, substring, level, ptm_level):
         """Copied from OpenDrift, then modified."""
 
@@ -705,3 +727,9 @@ def reader_metadata(self, key):
         if not self.has_added_reader:
             raise ValueError("reader has not been added yet.")
         return self.o.env.readers["roms native"].__dict__[key]
+
+    @property
+    def outfile_name(self):
+        """Output file name."""
+
+        return self.o.outfile_name

particle_tracking_manager/models/opendrift/opendrift_config.yaml

@@ -12,6 +12,11 @@ drift_model:
     - Leeway
   description: Which model in OpenDrift to use. This corresponds to the type of drift scenario the user wants to run.
 
+export_variables:
+  default: ["z"]
+  ptm_level: 1
+  type: list
+  description: List of variables to export. Options available with `m.all_export_variables` for a given `drift_model`. ['lon', 'lat', 'ID', 'status'] will always be exported.
 
 radius:
   default: 0.0

particle_tracking_manager/the_manager.py

@@ -424,5 +424,27 @@ def reader_metadata(self, key):
         pass
 
     def query_reader(self):
-        """Overwrite method in model."""
+        """define in child class."""
+        pass
+
+    def all_export_variables(self):
+        """Output list of all possible export variables.
+
+        define in child class.
+        """
+        pass
+
+    def export_variables(self):
+        """Output list of all actual export variables.
+
+        define in child class.
+        """
+        pass
+
+    @property
+    def outfile_name(self):
+        """Output file name.
+
+        define in child class.
+        """
         pass