Add postprocess_g_ensemble

Author: ph-kev

docs/src/api.md

@@ -6,6 +6,7 @@
 ClimaCalibrate.forward_model
 ClimaCalibrate.observation_map
 ClimaCalibrate.analyze_iteration
+ClimaCalibrate.postprocess_g_ensemble
 ```
 
 ## Worker Interface

docs/src/quickstart.md

@@ -49,6 +49,17 @@ end
 
 ### Optional postprocessing
 
+It may be the case that `observation_map` is insufficient as you need to more information,
+such as information from the `ekp` object to compute `G_ensemble`. Further postprocessing of the
+`G_ensemble` object can be done by implementing the `postprocess_g_ensemble` as shown
+below.
+
+```julia
+function postprocess_g_ensemble(ekp, g_ensemble, prior, output_dir, iteration)
+    return g_ensemble
+end
+```
+
 After each evaluation of the observation map and before updating the ensemble, it may be
 helpful to print the errors from the `ekp` object or plot `G_ensemble`. This can be done
 by implementing the `analyze_iteration` as shown below.

src/ekp_interface.jl

@@ -377,6 +377,8 @@ Compute the observation map and update the given EKP object.
 """
 function observation_map_and_update!(ekp, output_dir, iteration, prior)
     g_ensemble = observation_map(iteration)
+    g_ensemble =
+        postprocess_g_ensemble(ekp, g_ensemble, prior, output_dir, iteration)
     save_G_ensemble(output_dir, iteration, g_ensemble)
     terminate = update_ensemble!(ekp, g_ensemble, output_dir, iteration, prior)
     analyze_iteration(ekp, g_ensemble, prior, output_dir, iteration)

src/model_interface.jl

@@ -37,7 +37,7 @@ For example, one may want to print information from the `eki` object or plot
 `g_ensemble`.
 """
 function analyze_iteration(ekp, g_ensemble, prior, output_dir, iteration)
-    @info "Mean constrained parameter: $(EKP.get_ϕ_mean_final(prior, ekp))"
+    @info "Mean constrained parameter(s): $(EKP.get_ϕ_mean_final(prior, ekp))"
     @info "Covariance-weighted error: $(last(EKP.get_error(ekp)))"
     return nothing
 end

test/model_interface.jl

@@ -3,8 +3,10 @@ import ClimaCalibrate
 using EnsembleKalmanProcesses.ParameterDistributions
 using Test
 
-# Tests for ensuring ClimaCalibrate has protected interfaces. The API tested below must be defined for each model,
-# otherwise ClimaCalibrate will throw an error.
+# Tests for ensuring ClimaCalibrate has protected interfaces. The API tested
+# below must be defined for each model, otherwise ClimaCalibrate will throw an
+# error. However, `analyze_iteration` and `postprocess_g_ensemble` are
+# optional to implement.
 
 @testset "Model Interface stubs" begin
     @test_throws ErrorException("forward_model not implemented") ClimaCalibrate.forward_model(
@@ -15,4 +17,5 @@ using Test
         1,
     )
     @test isnothing(ClimaCalibrate.analyze_iteration(1, 1, 1, 1, 1))
+    @test 2 == ClimaCalibrate.postprocess_g_ensemble(1, 2, 3, 4, 5)
 end