Update predict api docs (#414)

* rm transform_to_real from exaples

* rm transform_to_real from docs examples

* update docstring

* format

* typo

Author: odunbar

docs/src/data_processing.md

@@ -7,8 +7,9 @@ The framework works as follows
 - An `encoder_schedule` defines the type of processing to be applied to input and/or output spaces
 - The `encoder_schedule` is passed into the `Emulator` where it is initialized and stored. Sometimes it will require additional information, passed in as `encoder_kwargs`. 
 - The encoder will be used automatically to encode training data, covariance matrices, and predictions within the Emulate and Sample routines.
+- Users can predict to/from encoded space with `predict(...; encode=X)` with `X` being `"in"`, `"out"`, or `"in_and_out"` if needed. 
 
-An external API is also available using the `encode_data`, and `encode_structure_matrix` methods if needed.
+An external API is also available using the `encode_data`, and `encode_structure_matrix` methods if needed to encode new data, or new covariance-type matrices.
 
 ## Defaults and recommendations
 ### Default schedule (no explicit dimension reduction)

docs/src/emulate.md

@@ -33,9 +33,16 @@ optimize_hyperparameters!(emulator)
 For some machine learning packages however, this may be completed during construction automatically, and for others this will not. If automatic construction took place, the `optimize_hyperparameters!` line does not perform any new task, so may be safely called. In the Lorenz example, this line learns the hyperparameters of the Gaussian process, which depend on the choice of [kernel](https://clima.github.io/CalibrateEmulateSample.jl/dev/GaussianProcessEmulator/#kernels), and the choice of GP package.
 Predictions at new inputs can then be made using
 ```julia
-y, cov = Emulator.predict(emulator, new_inputs)
+em_mean, em_cov = Emulator.predict(emulator, new_inputs)
+```
+This returns both a mean value and a covariance. The emulator is subject to encoding (see [Data processing and Dimension reduction](@ref data-proc)), and so we provide the `encode` and `add_obs_noise_cov` to enable users to predict in different spaces, and with different inflation.
+```julia
+# produce output in encoded space
+em_mean_enc, em_cov_enc = Emulator.predict(emulator, new_inputs; encode="out")
+
+# given encoded inputs, produce outputs in real space, and inflate the emulator uncertainty with observational noise
+em_mean, em_and_obs_noise_cov = Emulator.predict(emulator, new_encoded_inputs; encode="in", add_obs_noise_cov=true) 
 ```
-This returns both a mean value and a covariance.
 
 ## [Modular interface](@id modular-interface)
 

docs/src/examples/Cloudy_example.md

@@ -417,8 +417,7 @@ on them).
 # Check how well the emulator predicts on the true parameters
 y_mean, y_var = Emulators.predict(
     emulator,
-    reshape(θ_true, :, 1);
-    transform_to_real = true
+    reshape(θ_true, :, 1)
 )
 
 println("Emulator ($(case)) prediction on true parameters: ")

docs/src/examples/emulators/global_sens_analysis.md

@@ -127,11 +127,11 @@ optimize_hyperparameters!(emulator) # (only needed for some Emulator packages)
 
 ### Results and plots
 
-We validate the emulator by evaluating it on the entire Sobol sequence, and calculating the Sobol indices (presenting mean and std if using multiple repeats.
+We validate the emulator by evaluating it on the entire Sobol sequence, and calculating the Sobol indices (presenting mean and std if using multiple repeats).
 
 ```julia
 # predict on all Sobol points with emulator (example)    
-y_pred, y_var = predict(emulator, samples', transform_to_real = true)
+y_pred, y_var = predict(emulator, samples')
 
 # obtain emulated Sobol indices
 result_pred = analyze(data, y_pred')

docs/src/examples/emulators/lorenz_integrator_3d_3d.md

@@ -151,7 +151,7 @@ u_test_tmp = zeros(3, length(xspan_test))
 u_test_tmp[:, 1] = sol_test.u[1] # initialize at the final-time solution of the training period
 
 for i in 1:(length(xspan_test) - 1)
-    rf_mean, _ = predict(emulator, u_test_tmp[:, i:i], transform_to_real = true) # 3x1 matrix
+    rf_mean, _ = predict(emulator, u_test_tmp[:, i:i]) # 3x1 matrix
     u_test_tmp[:, i + 1] = rf_mean
 end
 ```

docs/src/examples/emulators/regression_2d_2d.md

@@ -139,9 +139,9 @@ x2 = range(0.0, stop = 2 * π, length = n_pts)
 X1, X2 = meshgrid(x1, x2)
 inputs = permutedims(hcat(X1[:], X2[:]), (2, 1))
 ```
-We predict using the emulators at the new inputs, and `transform_to_real` inverts the data processing back to physical values
+We predict using the emulators at the new inputs, 
 ```julia
-em_mean, em_cov = predict(emulator, inputs, transform_to_real = true)
+em_mean, em_cov = predict(emulator, inputs)
 ```
 We then plot the predicted mean and pointwise variances, and calculate the errors from the three highlighted cases:
 

docs/src/examples/lorenz_example.md

@@ -230,8 +230,8 @@ The emulator is checked for accuracy by evaluating its predictions on the true p
 ```julia
 # Check how well the Gaussian Process regression predicts on the
 # true parameters
-y_mean, y_var = Emulators.predict(emulator, reshape(truth_params, :, 1), transform_to_real = true)
-y_mean_test, y_var_test = Emulators.predict(emulator, get_inputs(input_output_pairs_test), transform_to_real = true)
+y_mean, y_var = Emulators.predict(emulator, reshape(truth_params, :, 1))
+y_mean_test, y_var_test = Emulators.predict(emulator, get_inputs(input_output_pairs_test))
 
 println("ML prediction on true parameters: ")
 println(vec(y_mean))

examples/Cloudy/Cloudy_emulate_sample.jl

@@ -181,8 +181,8 @@ function main()
         optimize_hyperparameters!(emulator)
 
         # Check how well the emulator predicts on the true parameters
-        y_mean, y_var = Emulators.predict(emulator, reshape(θ_true, :, 1); transform_to_real = true)
-        y_mean_test, y_var_test = Emulators.predict(emulator, get_inputs(test_pairs); transform_to_real = true)
+        y_mean, y_var = Emulators.predict(emulator, reshape(θ_true, :, 1))
+        y_mean_test, y_var_test = Emulators.predict(emulator, get_inputs(test_pairs))
         println("Emulator ($(case)) prediction on true parameters: ")
         println(vec(y_mean))
         println("true data: ")

examples/Darcy/emulate_sample.jl

@@ -105,9 +105,8 @@ function main()
         # Check how well the Gaussian Process regression predicts on the
         # true parameters
         #if retained_svd_frac==1.0
-        y_mean, y_var = Emulators.predict(emulator, reshape(truth_params, :, 1), transform_to_real = true)
-        y_mean_test, y_var_test =
-            Emulators.predict(emulator, get_inputs(input_output_pairs_test), transform_to_real = true)
+        y_mean, y_var = Emulators.predict(emulator, reshape(truth_params, :, 1))
+        y_mean_test, y_var_test = Emulators.predict(emulator, get_inputs(input_output_pairs_test))
 
         println("ML prediction on true parameters: ")
         println(vec(y_mean))

examples/EDMF_data/emulator-rank-test.jl

@@ -268,15 +268,15 @@ function main()
             # error of emulator on the training points: (no denoised training data)
             train_err_tmp = [0.0]
             for i in 1:size(train_inputs, 2)
-                train_mean, _ = Emulators.predict(emulator, train_inputs[:, i:i], transform_to_real = true) # 3x1
+                train_mean, _ = Emulators.predict(emulator, train_inputs[:, i:i]) # 3x1
                 train_err_tmp[1] += norm(train_mean - train_outputs[:, i])
             end
             train_err[rank_id, rep_idx] = 1 / size(train_inputs, 2) * train_err_tmp[1]
 
             # error of emulator on test points: 
             test_err_tmp = [0.0]
             for i in 1:size(test_inputs, 2)
-                test_mean, _ = Emulators.predict(emulator, test_inputs[:, i:i], transform_to_real = true) # 3x1
+                test_mean, _ = Emulators.predict(emulator, test_inputs[:, i:i]) # 3x1
                 test_err_tmp[1] += norm(test_mean - test_outputs[:, i])
             end
             test_err[rank_id, rep_idx] = 1 / size(test_inputs, 2) * test_err_tmp[1]