Update docs and examples; use semicolon notation for named tuples

ArneBouillon · ArneBouillon · commit 6d1b6dfa20b9 · 2025-08-20T10:05:59.000+02:00
diff --git a/docs/src/data_processing.md b/docs/src/data_processing.md
@@ -28,7 +28,7 @@ complex_schedule = [
 In this (rather unrealistic) chain;
 1. The inputs are decorrelated with their sample mean and covariance (and projected to low dimensional subspace if necessary) i.e PCA
 2. The scaled inputs are then subject to a "Robust" univariate scaling, mapping 1st-3rd quartiles to [0,1]
-3. The outputs are decorrelated using an "output structure matrix" (provided to the emulator `output_structure_matrix=`). Furthermore, apply a dimension-reduction to a space that retains 95% of the total variance. 
+3. The outputs are decorrelated using an "output structure matrix" (provided to the emulator in the `encoder_kwargs` parameter, e.g. as `(; obs_cov_noise =)`). Furthermore, apply a dimension-reduction to a space that retains 95% of the total variance. 
 4. In the reduced input-output space, a canonical correlation analysis is performed. Data is oriented and reduced (if necessary) maximize the joint correlation between inputs and outputs.
 
 !!! note "Default Encoder schedule"
@@ -44,12 +44,12 @@ The schedule is then passed into the Emulator, along with the data and desired s
 ```julia
 emulator = Emulator(
     machine_learning_tool,       
-    input_output_pairs; 
-    output_structure_matrix = obs_noise_cov, 
+    input_output_pairs,
+    (; obs_noise_cov = obs_noise_cov);
     encoder_schedule = complex_schedule,
 )
 ```
-Note that due to the item `(decorrelate_structure_mat(retain_var=0.95), "out")` in the schedule, we must provide the `output_structure_matrix`.
+Note that due to the item `(decorrelate_structure_mat(retain_var=0.95), "out")` in the schedule, we must provide an output structure matrix. In this case, we provide `obs_noise_cov`.
 
 # Types of data processors
 
diff --git a/docs/src/emulate.md b/docs/src/emulate.md
@@ -16,8 +16,8 @@ Wrapping a predefined machine learning tool, e.g. a Gaussian process `gauss_proc
 ```julia
 emulator = Emulator(
     gauss_proc, 
-    input_output_pairs; # optional arguments after this
-    output_structure_matrix = Γy,
+    input_output_pairs,
+    (; obs_noise_cov = Γy); # optional arguments after this
     encoder_schedule = encoder_schedule,
 )
 ```
diff --git a/examples/Cloudy/Cloudy_emulate_sample.jl b/examples/Cloudy/Cloudy_emulate_sample.jl
@@ -171,9 +171,8 @@ function main()
         # build emulator
         emulator = Emulator(
             mlt,
-            input_output_pairs;
-            input_structure_matrix = cov(priors),
-            output_structure_matrix = Γy,
+            input_output_pairs,
+            (; prior_cov = cov(priors), obs_noise_cov = Γy);
             encoder_schedule = encoder_schedule,
         )
 
diff --git a/examples/Darcy/emulate_sample.jl b/examples/Darcy/emulate_sample.jl
@@ -96,9 +96,8 @@ function main()
 
         emulator = Emulator(
             mlt,
-            input_output_pairs;
-            input_structure_matrix = cov(prior),
-            output_structure_matrix = Γy,
+            input_output_pairs,
+            (; prior_cov = cov(prior), obs_noise_cov = Γy);
             encoding_schedule = encoding_schedule,
         )
         optimize_hyperparameters!(emulator, kernbounds = [fill(-1e2, n_params + 1), fill(1e2, n_params + 1)])
diff --git a/examples/EDMF_data/emulator-rank-test.jl b/examples/EDMF_data/emulator-rank-test.jl
@@ -256,9 +256,8 @@ function main()
             ttt[rank_id, rep_idx] = @elapsed begin
                 emulator = Emulator(
                     mlt,
-                    train_pairs;
-                    input_structure_matrix = cov(prior),
-                    output_structure_matrix = truth_cov,
+                    train_pairs,
+                    (; prior_cov = cov(prior), obs_noise_cov = truth_cov);
                     encoder_schedule = encoder_schedule,
                 )
 
diff --git a/examples/EDMF_data/uq_for_edmf.jl b/examples/EDMF_data/uq_for_edmf.jl
@@ -230,9 +230,8 @@ function main()
     # Fit an emulator to the data
     emulator = Emulator(
         mlt,
-        input_output_pairs;
-        input_structure_matrix = cov(prior),
-        output_structure_matrix = truth_cov,
+        input_output_pairs,
+        (; prior_cov = cov(prior), obs_noise_cov = truth_cov);
         encoder_schedule = encoder_schedule,
     )
 
diff --git a/examples/Emulator/G-function/emulate-test-n-features.jl b/examples/Emulator/G-function/emulate-test-n-features.jl
@@ -151,12 +151,8 @@ function main()
 
             # Emulate
             ttt[f_idx, rep_idx] = @elapsed begin
-                emulator = Emulator(
-                    mlt,
-                    iopairs;
-                    output_structure_matrix = Γ * I,
-                    encoder_schedule = deepcopy(encoder_schedule),
-                )
+                emulator =
+                    Emulator(mlt, iopairs, (; obs_noise_cov = Γ * I); encoder_schedule = deepcopy(encoder_schedule))
                 optimize_hyperparameters!(emulator)
             end
 
diff --git a/examples/Emulator/G-function/emulate.jl b/examples/Emulator/G-function/emulate.jl
@@ -142,12 +142,7 @@ function main()
 
         # Emulate
         times[rep_idx] = @elapsed begin
-            emulator = Emulator(
-                mlt,
-                iopairs;
-                output_structure_matrix = Γ * I,
-                encoder_schedule = deepcopy(encoder_schedule),
-            )
+            emulator = Emulator(mlt, iopairs, (; obs_noise_cov = Γ * I); encoder_schedule = deepcopy(encoder_schedule))
             optimize_hyperparameters!(emulator)
         end
 
diff --git a/examples/Emulator/Ishigami/emulate.jl b/examples/Emulator/Ishigami/emulate.jl
@@ -123,8 +123,7 @@ function main()
         end
 
         # Emulate
-        emulator =
-            Emulator(mlt, iopairs; output_structure_matrix = Γ * I, encoder_schedule = deepcopy(encoder_schedule))
+        emulator = Emulator(mlt, iopairs, (; obs_noise_cov = Γ * I); encoder_schedule = deepcopy(encoder_schedule))
         optimize_hyperparameters!(emulator)
 
         # get EKP errors - just stored in "optimizer" box for now
diff --git a/examples/Emulator/L63/emulate.jl b/examples/Emulator/L63/emulate.jl
@@ -215,7 +215,7 @@ function main()
         else
             encoder_schedule = (decorrelate_structure_mat(), "out")
         end
-        emulator = Emulator(mlt, iopairs; output_structure_matrix = Γy, encoder_schedule = deepcopy(encoder_schedule))
+        emulator = Emulator(mlt, iopairs, (; obs_noise_cov = Γy); encoder_schedule = deepcopy(encoder_schedule))
         optimize_hyperparameters!(emulator)
 
         # diagnostics
diff --git a/examples/Emulator/L63/emulate_diff-rank-test.jl b/examples/Emulator/L63/emulate_diff-rank-test.jl
@@ -191,12 +191,7 @@ function main()
                 encoder_schedule = nothing
             end
             ttt[rank_id, rep_idx] = @elapsed begin
-                emulator = Emulator(
-                    mlt,
-                    iopairs;
-                    output_structure_matrix = Γy,
-                    encoder_schedule = deepcopy(encoder_schedule),
-                )
+                emulator = Emulator(mlt, iopairs, (; obs_noise_cov = Γy); encoder_schedule = deepcopy(encoder_schedule))
                 optimize_hyperparameters!(emulator)
             end
 
diff --git a/examples/Emulator/Regression_2d_2d/compare_regression.jl b/examples/Emulator/Regression_2d_2d/compare_regression.jl
@@ -166,13 +166,7 @@ function main()
 
             end
 
-            emulator = Emulator(
-                mlt,
-                iopairs,
-                encoder_schedule = enc,
-                input_structure_matrix = prior_cov,
-                output_structure_matrix = Σ,
-            )
+            emulator = Emulator(mlt, iopairs, (; prior_cov = prior_cov, obs_noise_cov = Σ); encoder_schedule = enc)
 
 
             optimize_hyperparameters!(emulator) # although RF already optimized
diff --git a/examples/GCM/emulate_sample_script.jl b/examples/GCM/emulate_sample_script.jl
@@ -160,20 +160,15 @@ function main()
     if emulator_type == "VectorRFR-nondiag"
 
         encoder_schedule = [(quartile_scale(), "in"), (decorrelate_structure_mat(), "out")]
-        emulator = Emulator(
-            mlt,
-            input_output_pairs;
-            output_structure_matrix = obs_noise_cov,
-            encoder_schedule = encoder_schedule,
-        )
+        emulator =
+            Emulator(mlt, input_output_pairs, (; obs_noise_cov = obs_noise_cov); encoder_schedule = encoder_schedule)
     else
         encoder_schedule = [(decorrelate_structure_mat(), "in_and_out")]
 
         emulator = Emulator(
             mlt,
-            input_output_pairs;
-            input_structure_matrix = cov(prior),
-            output_structure_matrix = obs_noise_cov,
+            input_output_pairs,
+            (; prior_cov = cov(prior), obs_noise_cov = obs_noise_cov);
             encoder_schedule = encoder_schedule,
         )
 
diff --git a/examples/Lorenz/emulate_sample.jl b/examples/Lorenz/emulate_sample.jl
@@ -170,7 +170,7 @@ function main()
         retain_var = 0.95
         encoder_schedule = [(quartile_scale(), "in"), (decorrelate_structure_mat(retain_var = retain_var), "out")]
 
-        emulator = Emulator(mlt, input_output_pairs; output_structure_matrix = Γy, encoder_schedule = encoder_schedule)
+        emulator = Emulator(mlt, input_output_pairs, (; obs_noise_cov = Γy); encoder_schedule = encoder_schedule)
         optimize_hyperparameters!(emulator)
 
         # Check how well the Gaussian Process regression predicts on the
diff --git a/examples/Lorenz/emulate_sample_spatial_dep.jl b/examples/Lorenz/emulate_sample_spatial_dep.jl
@@ -143,9 +143,8 @@ function main()
 
         emulator = Emulator(
             mlt,
-            input_output_pairs;
-            input_structure_matrix = cov(priors),
-            output_structure_matrix = Γy,
+            input_output_pairs,
+            (; prior_cov = cov(priors), obs_noise_cov = Γy);
             encoder_schedule = encoder_schedule,
         )
         optimize_hyperparameters!(emulator)
diff --git a/test/Emulator/runtests.jl b/test/Emulator/runtests.jl
@@ -74,10 +74,10 @@ struct MLTester <: Emulators.MachineLearningTool end
     @test_logs (:warn,) (:info,) (:info,) (:warn,) Emulator(
         gp,
         io_pairs,
-        (prior_cov = 4.0 * I, obs_noise_cov = 2.0 * I);
+        (; prior_cov = 4.0 * I, obs_noise_cov = 2.0 * I);
         obs_noise_cov = 3.0 * I,
     )
-    em1 = Emulator(gp, io_pairs, (obs_noise_cov = Σ,))
+    em1 = Emulator(gp, io_pairs, (; obs_noise_cov = Σ))
 
     enc_sch1 = create_encoder_schedule([(decorrelate_sample_cov(), "in"), (decorrelate_structure_mat(), "out")])
     initialize_and_encode_with_schedule!(
diff --git a/test/GaussianProcess/runtests.jl b/test/GaussianProcess/runtests.jl
@@ -177,11 +177,11 @@ using CalibrateEmulateSample.Utilities
     # with noise learning - e.g. we add a kernel to learn the noise (even though we provide the Sigma to the emulator)
     gp4_noise_learnt = GaussianProcess(gppackage; kernel = nothing, noise_learn = true, prediction_type = pred_type)
     # without noise learning, just use the SVD transform to deal with observational noise
-    em4_noise_learnt = Emulator(gp4_noise_learnt, iopairs2, (obs_noise_cov = Σ,))
+    em4_noise_learnt = Emulator(gp4_noise_learnt, iopairs2, (; obs_noise_cov = Σ))
 
     gp4 = GaussianProcess(gppackage; kernel = nothing, noise_learn = false, prediction_type = pred_type)
 
-    em4_noise_from_Σ = Emulator(gp4, iopairs2, (obs_noise_cov = Σ,))
+    em4_noise_from_Σ = Emulator(gp4, iopairs2, (; obs_noise_cov = Σ))
 
     Emulators.optimize_hyperparameters!(em4_noise_learnt)
     Emulators.optimize_hyperparameters!(em4_noise_from_Σ)
@@ -226,7 +226,7 @@ using CalibrateEmulateSample.Utilities
         ) for model_params in gp4_opt_params
     ]
 
-    em_agp_from_gp4 = Emulator(agp4, iopairs2, (obs_noise_cov = Σ,); kernel_params = kernel_params)
+    em_agp_from_gp4 = Emulator(agp4, iopairs2, (; obs_noise_cov = Σ); kernel_params = kernel_params)
 
     μ4b, σ4b² = Emulators.predict(em_agp_from_gp4, new_inputs, transform_to_real = true)
 
diff --git a/test/MarkovChainMonteCarlo/runtests.jl b/test/MarkovChainMonteCarlo/runtests.jl
@@ -57,7 +57,7 @@ function test_gp_mv(y, σ2_y, iopairs::PairedDataContainer)
     # Squared exponential kernel (note that hyperparameters are on log scale)
     # with observational noise
     gp = GaussianProcess(gppackage; noise_learn = true, prediction_type = pred_type)
-    em = Emulator(gp, iopairs, (obs_noise_cov = σ2_y,))
+    em = Emulator(gp, iopairs, (; obs_noise_cov = σ2_y))
     Emulators.optimize_hyperparameters!(em)
     return em
 end
@@ -70,7 +70,7 @@ function test_gp_1(y, σ2_y, iopairs::PairedDataContainer)
     # with observational noise
     GPkernel = SE(log(1.0), log(1.0))
     gp = GaussianProcess(gppackage; kernel = GPkernel, noise_learn = true, prediction_type = pred_type)
-    em = Emulator(gp, iopairs, (obs_noise_cov = σ2_y,); encoder_schedule = [])
+    em = Emulator(gp, iopairs, (; obs_noise_cov = σ2_y); encoder_schedule = [])
     Emulators.optimize_hyperparameters!(em)
     return em
 end
@@ -83,7 +83,7 @@ function test_gp_and_agp_1(y, σ2_y, iopairs::PairedDataContainer)
     # with observational noise
     GPkernel = SE(log(1.0), log(1.0))
     gp = GaussianProcess(gppackage; kernel = GPkernel, noise_learn = true, prediction_type = pred_type)
-    em = Emulator(gp, iopairs, (obs_noise_cov = σ2_y,); encoder_schedule = [])
+    em = Emulator(gp, iopairs, (; obs_noise_cov = σ2_y); encoder_schedule = [])
     Emulators.optimize_hyperparameters!(em)
 
     # now make agp from gp
@@ -100,7 +100,7 @@ function test_gp_and_agp_1(y, σ2_y, iopairs::PairedDataContainer)
         ) for model_params in gp_opt_params
     ]
 
-    em_agp = Emulator(agp, iopairs, (obs_noise_cov = σ2_y,); encoder_schedule = [], kernel_params = kernel_params)
+    em_agp = Emulator(agp, iopairs, (; obs_noise_cov = σ2_y); encoder_schedule = [], kernel_params = kernel_params)
 
     return em, em_agp
 end
@@ -116,7 +116,7 @@ function test_gp_2(y, σ2_y, iopairs::PairedDataContainer)
     gp = GaussianProcess(gppackage; kernel = GPkernel, noise_learn = true, prediction_type = pred_type)
     retain_var = 0.95
     encoder_schedule = [(quartile_scale(), "out"), (decorrelate_structure_mat(retain_var = retain_var), "out")]
-    em = Emulator(gp, iopairs, (obs_noise_cov = σ2_y,); encoder_schedule = encoder_schedule)
+    em = Emulator(gp, iopairs, (; obs_noise_cov = σ2_y); encoder_schedule = encoder_schedule)
     Emulators.optimize_hyperparameters!(em)
 
     return em
diff --git a/test/RandomFeature/runtests.jl b/test/RandomFeature/runtests.jl
@@ -306,9 +306,9 @@ rng = Random.MersenneTwister(seed)
         )
 
         # build emulators
-        em_srfi = Emulator(srfi, iopairs, (obs_noise_cov = obs_noise_cov,))
+        em_srfi = Emulator(srfi, iopairs, (; obs_noise_cov = obs_noise_cov))
         n_srfi = length(get_rfms(srfi))
-        em_vrfi = Emulator(vrfi, iopairs, (obs_noise_cov = obs_noise_cov,))
+        em_vrfi = Emulator(vrfi, iopairs, (; obs_noise_cov = obs_noise_cov))
         n_vrfi = length(get_rfms(vrfi))
 
         # test bad case
@@ -324,11 +324,11 @@ rng = Random.MersenneTwister(seed)
         @test_throws ArgumentError Emulator(srfi_bad, iopairs)
 
         # test under repeats
-        @test_logs (:info,) (:info,) (:warn,) Emulator(srfi, iopairs, (obs_noise_cov = obs_noise_cov,))
-        Emulator(srfi, iopairs, (obs_noise_cov = obs_noise_cov,))
+        @test_logs (:info,) (:info,) (:warn,) Emulator(srfi, iopairs, (; obs_noise_cov = obs_noise_cov))
+        Emulator(srfi, iopairs, (; obs_noise_cov = obs_noise_cov))
         @test length(get_rfms(srfi)) == n_srfi
-        @test_logs (:info,) (:info,) (:warn,) Emulator(vrfi, iopairs, (obs_noise_cov = obs_noise_cov,))
-        Emulator(vrfi, iopairs, (obs_noise_cov = obs_noise_cov,))
+        @test_logs (:info,) (:info,) (:warn,) Emulator(vrfi, iopairs, (; obs_noise_cov = obs_noise_cov))
+        Emulator(vrfi, iopairs, (; obs_noise_cov = obs_noise_cov))
         @test length(get_rfms(vrfi)) == n_vrfi
 
 
@@ -422,14 +422,14 @@ rng = Random.MersenneTwister(seed)
         # build emulators
         # svd: scalar, scalar + diag in, vector + diag out, vector
         # no-svd: vector
-        em_srfi_svd_diagin = Emulator(srfi_diagin, iopairs, (obs_noise_cov = Σ,))
-        em_srfi_svd = Emulator(srfi, iopairs, (obs_noise_cov = Σ,))
+        em_srfi_svd_diagin = Emulator(srfi_diagin, iopairs, (; obs_noise_cov = Σ))
+        em_srfi_svd = Emulator(srfi, iopairs, (; obs_noise_cov = Σ))
 
-        em_vrfi_svd_diagout = Emulator(vrfi_diagout, iopairs, (obs_noise_cov = Σ,))
-        em_vrfi_svd = Emulator(vrfi, iopairs, (obs_noise_cov = Σ,))
+        em_vrfi_svd_diagout = Emulator(vrfi_diagout, iopairs, (; obs_noise_cov = Σ))
+        em_vrfi_svd = Emulator(vrfi, iopairs, (; obs_noise_cov = Σ))
 
-        em_vrfi = Emulator(vrfi, iopairs, (obs_noise_cov = Σ,); encoder_schedule = [])
-        em_vrfi_nonsep = Emulator(vrfi_nonsep, iopairs, (obs_noise_cov = Σ,); encoder_schedule = [])
+        em_vrfi = Emulator(vrfi, iopairs, (; obs_noise_cov = Σ); encoder_schedule = [])
+        em_vrfi_nonsep = Emulator(vrfi_nonsep, iopairs, (; obs_noise_cov = Σ); encoder_schedule = [])
 
         #TODO truncated SVD option for vector (involves resizing prior)
 
@@ -464,7 +464,7 @@ rng = Random.MersenneTwister(seed)
             optimizer_options = Dict("train_fraction" => 0.7, "multithread" => "tullio"),
             rng = rng,
         )
-        em_vrfi_svd_tul = Emulator(vrfi_tul, iopairs, (obs_noise_cov = Σ,))
+        em_vrfi_svd_tul = Emulator(vrfi_tul, iopairs, (; obs_noise_cov = Σ))
         μ_vs_tul, σ²_vs_tul = Emulators.predict(em_vrfi_svd_tul, new_inputs, transform_to_real = true)
         @test isapprox.(norm(μ_vs_tul - outx), 0, atol = tol_μ)
 
