JOSS: Emulator docstring and warning (#299)

* emulator updates

* emulator API

* update test_logs

* test fix

* another test_logs...

* API again...

* rm func

* try

* typo

* need to upd docs in another PR

* try

* final push, docs in next PR

src/Emulator.jl

@@ -81,6 +81,20 @@ end
 get_machine_learning_tool(emulator::Emulator) = emulator.machine_learning_tool
 
 # Constructor for the Emulator Object
+"""
+$(DocStringExtensions.TYPEDSIGNATURES)
+
+Positional Arguments
+ - `machine_learning_tool` ::MachineLearningTool,
+ - `input_output_pairs` ::PairedDataContainer
+Keyword Arguments 
+ - `obs_noise_cov`: A matrix/uniform scaling to provide the observational noise covariance of the data - used for data processing (default `nothing`),
+ - `normalize_inputs`: Normalize the inputs to be unit Gaussian, in the smallest full-rank space of the data (default `true`),
+ - `standardize_outputs`: Standardize outputs with by dividing by a vector of provided factors (default `false`),
+ - `standardize_outputs_factors`: If standardizing, the provided dim_output-length vector of factors,
+ - `decorrelate`: Apply (truncated) SVD to the outputs. Predictions are returned in the decorrelated space, (default `true`)
+ - `retained_svd_frac`: The cumulative sum of singular values retained after output SVD truncation (default 1.0 - no truncation)
+"""
 function Emulator(
     machine_learning_tool::MachineLearningTool,
     input_output_pairs::PairedDataContainer{FT};
@@ -102,6 +116,8 @@ function Emulator(
     if obs_noise_cov !== nothing
         err2 = "obs_noise_cov must be of size ($output_dim, $output_dim), got $(size(obs_noise_cov))"
         size(obs_noise_cov) == (output_dim, output_dim) || throw(ArgumentError(err2))
+    else
+        @warn "The covariance of the observational noise (a.k.a obs_noise_cov) is useful for data processing. Large approximation errors can occur without it. If possible, please provide it using the keyword obs_noise_cov."
     end
 
 

test/GaussianProcess/runtests.jl

@@ -72,7 +72,7 @@ using CalibrateEmulateSample.DataContainers
         retained_svd_frac = 1.0,
     )
 
-    @test_logs (:warn,) Emulator(
+    @test_logs (:warn,) (:warn,) Emulator(
         gp1,
         iopairs,
         obs_noise_cov = nothing,
@@ -139,7 +139,7 @@ using CalibrateEmulateSample.DataContainers
         retained_svd_frac = 1.0,
     )
 
-    @test_logs (:warn,) Emulator(
+    @test_logs (:warn,) (:warn,) Emulator(
         gp3,
         iopairs,
         obs_noise_cov = nothing,