support composing input variables

Author: juliasloan25

docs/src/datahandling.md

@@ -17,7 +17,7 @@ interface). For instance, if need arises, the `DataHandler` can be used (almost)
 directly to process files with a different format from NetCDF.
 
 The key struct in `DataHandling` is the `DataHandler`. The `DataHandler`
-contains a `FileReader`, a `Regridder`, and other metadata necessary to perform
+contains one or more `FileReader`(s), a `Regridder`, and other metadata necessary to perform
 its operations (e.g., target `ClimaCore.Space`). The `DataHandler` can be used
 for static or temporal data, and exposes the following key functions:
 - `regridded_snapshot(time)`: to obtain the regridded field at the given `time`.
@@ -52,7 +52,16 @@ It is possible to pass down keyword arguments to underlying constructors in
 `DataHandler` with the `regridder_kwargs` and `file_reader_kwargs`. These have
 to be a named tuple or a dictionary that maps `Symbol`s to values.
 
-## Example
+A `DataHandler` can contain information about a variable that we read directly from
+an input file, or about a variable that is produced by composing data from multiple
+input variables. In the latter case, the input variables may either all come from
+the same input file, or may each come from a separate input file. The user must
+provide the composing function, which operates pointwise on each of the inputs,
+as well as an ordered list of the variable names to be passed to the function.
+Composing multiple input variables is currently only supported with the
+`InterpolationsRegridder`, not with `TempestRegridder`.
+
+## Example with a single data variable
 
 As an example, let us implement a simple linear interpolation for a variable `u`
 defined in the `era5_example.nc` NetCDF file. The file contains monthly averages
@@ -68,6 +77,7 @@ import Interpolations
 
 import Dates
 
+# Define pre-processing function to convert units of input
 unit_conversion_func = (data) -> 1000. * data
 
 data_handler = DataHandling.DataHandler("era5_example.nc",
@@ -93,6 +103,55 @@ function linear_interpolation(data_handler, time)
 end
 ```
 
+## Example with a multiple input data variables
+
+As an example, let us take two input variables, `u` and `v` defined in the
+`era5_example.nc` NetCDF file. Suppose that we care only about the sum of these
+variables, rather than their individual values. We'll use a composing function
+and the `InterpolationsRegridder` to produce the data we want, `u + v`.
+The input file contains monthly averages for each variable starting from the year 2000.
+
+We'll use the same linear interpolation function defined in the previous function.
+
+```julia
+import ClimaUtilities.DataHandling
+import ClimaCore
+import NCDatasets
+# Loading ClimaCore and Interpolations automatically loads DataHandling
+import Interpolations
+# This will load InterpolationsRegridder
+
+import Dates
+
+# Define pre-processing function to convert units of input
+unit_conversion_func = (data) -> 1000. * data
+
+# Define the pointwise composing function we want, a simple sum in this case
+compose_func = (x, y) -> x + y
+data_handler = DataHandling.DataHandler("era5_example.nc",
+                                        ["u", "v"],
+                                        target_space,
+                                        reference_date = Dates.DateTime(2000, 1, 1),
+                                        regridder_type = :InterpolationsRegridder,
+                                        file_reader_kwargs = (; preprocess_func = unit_conversion_func),
+                                        compose_func)
+
+function linear_interpolation(data_handler, time)
+    # Time is assumed to be "simulation time", ie seconds starting from reference_date
+
+    time_of_prev_snapshot = DataHandling.previous_time(data_handler, time)
+    time_of_next_snapshot = DataHandling.next_time(data_handler, time)
+
+    prev_snapshot = DataHandling.regridded_snaphsot(data_handler, time_of_prev_snapshot)
+    next_snapshot = DataHandling.regridded_snaphsot(data_handler, time_of_next_snapshot)
+
+    # prev and next snapshots are ClimaCore.Fields defined on the target_space
+
+    return @. prev_snapshot + (next_snapshot - prev_snapshot) *
+        (time - time_of_prev_snapshot) / (time_of_next_snapshot - time_of_prev_snapshot)
+end
+```
+
 ## API
 
 ```@docs

docs/src/inputs.md

@@ -28,7 +28,7 @@ regridding onto the computational domains (using [`Regridders`](@ref) and
 `TimeVaryingInputs` support:
 - analytic functions of time;
 - pairs of 1D arrays (for `PointSpaces`);
-- 2/3D NetCDF files;
+- 2/3D NetCDF files (including composing multiple variables from one or more files into one variable);
 - linear interpolation in time (default), nearest neighbors, and "period filling";
 - boundary conditions and repeating periodic data.
 
@@ -153,10 +153,10 @@ albedo_tv = TimeVaryingInputs.TimeVaryingInput("cesem_albedo.nc", "alb", target_
 (chiefly the [`DataHandling`](@ref) module) to construct a `Field` from
 different sources.
 
-`TimeVaryingInputs` support:
+`SpaceVaryingInputs` support:
 - analytic functions of coordinates;
 - pairs of 1D arrays (for columns);
-- 2/3D NetCDF files.
+- 2/3D NetCDF files (including composing multiple variables from one or more files into one variable).
 
 In some ways, a `SpaceVaryingInput` can be thought as an alternative constructor
 for a `ClimaCore` `Field`.
@@ -202,4 +202,3 @@ ClimaUtilities.TimeVaryingInputs.extrapolation_bc
 Base.in
 Base.close
 ```
-