Merge pull request #44 from JuliaDecisionFocusedLearning/rename-datasample-fields

Rename DataSample fields

Author: BatyLeo

docs/src/benchmark_interfaces.md

@@ -11,14 +11,14 @@ All benchmarks work with [`DataSample`](@ref) objects that encapsulate the data
 
 ```julia
 @kwdef struct DataSample{I,F,S,C}
-    x::F = nothing           # Input features  
-    θ_true::C = nothing      # True cost/utility parameters
-    y_true::S = nothing      # True optimal solution
-    instance::I = nothing    # Problem instance object/additional data
+    x::F = nothing       # Input features of the policy
+    θ::C = nothing       # Intermediate cost/utility parameters
+    y::S = nothing       # Output solution
+    info::I = nothing    # Additional data information (e.g., problem instance)
 end
 ```
 
-The `DataSample` provides flexibility - not all fields need to be populated depending on the benchmark type and use case.
+The `DataSample` provides flexibility, not all fields need to be populated depending on the benchmark type and use.
 
 ### Benchmark Type Hierarchy
 

docs/src/tutorials/warcraft_tutorial.jl

@@ -21,16 +21,16 @@ dataset = generate_dataset(b, 50);
 # Subdatasets can be created through regular slicing:
 train_dataset, test_dataset = dataset[1:45], dataset[46:50]
 
-# And getting an individual sample will return a [`DataSample`](@ref) with four fields: `x`, `instance`, `θ`, and `y`:
+# And getting an individual sample will return a [`DataSample`](@ref) with four fields: `x`, `info`, `θ`, and `y`:
 sample = test_dataset[1]
 # `x` correspond to the input features, i.e. the input image (3D array) in the Warcraft benchmark case:
 x = sample.x
-# `θ_true` correspond to the true unknown terrain weights. We use the opposite of the true weights in order to formulate the optimization problem as a maximization problem:
-θ_true = sample.θ_true
-# `y_true` correspond to the optimal shortest path, encoded as a binary matrix:
-y_true = sample.y_true
-# `instance` is not used in this benchmark, therefore set to nothing:
-isnothing(sample.instance)
+# `θ` correspond to the true unknown terrain weights. We use the opposite of the true weights in order to formulate the optimization problem as a maximization problem:
+θ_true = sample.θ
+# `y` correspond to the optimal shortest path, encoded as a binary matrix:
+y_true = sample.y
+# `info` is not used in this benchmark, therefore set to nothing:
+isnothing(sample.info)
 
 # For some benchmarks, we provide the following plotting method [`plot_data`](@ref) to visualize the data:
 plot_data(b, sample)
@@ -50,7 +50,7 @@ maximizer = generate_maximizer(b; dijkstra=true)
 # In the case o fthe Warcraft benchmark, the method has an additional keyword argument to chose the algorithm to use: Dijkstra's algorithm or Bellman-Ford algorithm.
 y = maximizer(θ)
 # As we can see, currently the pipeline predicts random noise as cell weights, and therefore the maximizer returns a straight line path.
-plot_data(b, DataSample(; x, θ_true=θ, y_true=y))
+plot_data(b, DataSample(; x, θ, y))
 # We can evaluate the current pipeline performance using the optimality gap metric:
 starting_gap = compute_gap(b, test_dataset, model, maximizer)
 
@@ -70,7 +70,7 @@ opt_state = Flux.setup(Adam(1e-3), model)
 loss_history = Float64[]
 for epoch in 1:50
     val, grads = Flux.withgradient(model) do m
-        sum(loss(m(x), y_true) for (; x, y_true) in train_dataset) / length(train_dataset)
+        sum(loss(m(x), y) for (; x, y) in train_dataset) / length(train_dataset)
     end
     Flux.update!(opt_state, model, grads[1])
     push!(loss_history, val)
@@ -85,7 +85,7 @@ final_gap = compute_gap(b, test_dataset, model, maximizer)
 #
 θ = model(x)
 y = maximizer(θ)
-plot_data(b, DataSample(; x, θ_true=θ, y_true=y))
+plot_data(b, DataSample(; x, θ, y))
 
 using Test #src
 @test final_gap < starting_gap #src

src/Argmax/Argmax.jl

@@ -76,9 +76,9 @@ function Utils.generate_sample(
 )
     (; instance_dim, nb_features, encoder) = bench
     features = randn(rng, Float32, nb_features, instance_dim)
-    costs = encoder(features)
-    noisy_solution = one_hot_argmax(costs + noise_std * randn(rng, Float32, instance_dim))
-    return DataSample(; x=features, θ_true=costs, y_true=noisy_solution)
+    θ_true = encoder(features)
+    noisy_y_true = one_hot_argmax(θ_true + noise_std * randn(rng, Float32, instance_dim))
+    return DataSample(; x=features, θ=θ_true, y=noisy_y_true)
 end
 
 """

src/Argmax2D/Argmax2D.jl

@@ -62,7 +62,7 @@ function Utils.generate_sample(bench::Argmax2DBenchmark, rng::AbstractRNG)
     θ_true ./= 2 * norm(θ_true)
     instance = build_polytope(rand(rng, polytope_vertex_range); shift=rand(rng))
     y_true = maximizer(θ_true; instance)
-    return DataSample(; x=x, θ_true=θ_true, y_true=y_true, instance=instance)
+    return DataSample(; x=x, θ=θ_true, y=y_true, info=instance)
 end
 
 """
@@ -88,11 +88,11 @@ function Utils.generate_statistical_model(
     return model
 end
 
-function Utils.plot_data(::Argmax2DBenchmark; instance, θ, kwargs...)
+function Utils.plot_data(::Argmax2DBenchmark; info, θ, kwargs...)
     pl = init_plot()
-    plot_polytope!(pl, instance)
+    plot_polytope!(pl, info)
     plot_objective!(pl, θ)
-    return plot_maximizer!(pl, θ, instance, maximizer)
+    return plot_maximizer!(pl, θ, info, maximizer)
 end
 
 """
@@ -101,13 +101,9 @@ $TYPEDSIGNATURES
 Plot the data sample for the [`Argmax2DBenchmark`](@ref).
 """
 function Utils.plot_data(
-    bench::Argmax2DBenchmark,
-    sample::DataSample;
-    instance=sample.instance,
-    θ=sample.θ_true,
-    kwargs...,
+    bench::Argmax2DBenchmark, sample::DataSample; info=sample.info, θ=sample.θ, kwargs...
 )
-    return Utils.plot_data(bench; instance, θ, kwargs...)
+    return Utils.plot_data(bench; info, θ, kwargs...)
 end
 
 export Argmax2DBenchmark

src/DynamicAssortment/DynamicAssortment.jl

@@ -83,7 +83,7 @@ Outputs a data sample containing an [`Instance`](@ref).
 function Utils.generate_sample(
     b::DynamicAssortmentBenchmark, rng::AbstractRNG=MersenneTwister(0)
 )
-    return DataSample(; instance=Instance(b, rng))
+    return DataSample(; info=Instance(b, rng))
 end
 
 """

src/DynamicVehicleScheduling/DynamicVehicleScheduling.jl

@@ -63,7 +63,7 @@ function Utils.generate_dataset(b::DynamicVehicleSchedulingBenchmark, dataset_si
     dataset_size = min(dataset_size, length(files))
     return [
         DataSample(;
-            instance=Instance(
+            info=Instance(
                 read_vsp_instance(files[i]);
                 max_requests_per_epoch,
                 Δ_dispatch,

src/DynamicVehicleScheduling/anticipative_solver.jl

@@ -222,7 +222,7 @@ function anticipative_solver(
             compute_features(state, env.instance)
         end
 
-        return DataSample(; instance=(; state, reward), y_true, x)
+        return DataSample(; info=(; state, reward), y=y_true, x)
     end
 
     return obj, dataset

src/DynamicVehicleScheduling/plot.jl

@@ -208,9 +208,9 @@ The returned dictionary contains:
 This lets plotting code build figures without depending on plotting internals.
 """
 function build_plot_data(data_samples::Vector{<:DataSample})
-    state_data = [build_state_data(sample.instance.state) for sample in data_samples]
-    rewards = [sample.instance.reward for sample in data_samples]
-    routess = [sample.y_true for sample in data_samples]
+    state_data = [build_state_data(sample.info.state) for sample in data_samples]
+    rewards = [sample.info.reward for sample in data_samples]
+    routess = [sample.y for sample in data_samples]
     return [
         (; state..., reward, routes) for
         (state, reward, routes) in zip(state_data, rewards, routess)
@@ -273,8 +273,8 @@ function plot_epochs(
     # Create subplots
     plots = map(1:n_epochs) do i
         sample = data_samples[i]
-        state = sample.instance.state
-        reward = sample.instance.reward
+        state = sample.info.state
+        reward = sample.info.reward
 
         common_kwargs = Dict(
             :xlims => xlims,
@@ -292,7 +292,7 @@ function plot_epochs(
         if plot_routes_flag
             fig = plot_routes(
                 state,
-                sample.y_true;
+                sample.y;
                 reward=reward,
                 show_route_labels=false,
                 common_kwargs...,
@@ -351,7 +351,7 @@ function animate_epochs(
     kwargs...,
 )
     pd = build_plot_data(data_samples)
-    epoch_costs = [-sample.instance.reward for sample in data_samples]
+    epoch_costs = [-sample.info.reward for sample in data_samples]
 
     # Calculate global xlims and ylims from all states
     x_min = minimum(min(data.x_depot, minimum(data.x_customers)) for data in pd)
@@ -393,12 +393,12 @@ function animate_epochs(
     anim = @animate for frame_idx in 1:total_frames
         epoch_idx, frame_type = frame_plan[frame_idx]
         sample = data_samples[epoch_idx]
-        state = sample.instance.state
+        state = sample.info.state
 
         if frame_type == :routes
             fig = plot_routes(
                 state,
-                sample.y_true;
+                sample.y;
                 xlims=xlims,
                 ylims=ylims,
                 clims=clims,

src/FixedSizeShortestPath/FixedSizeShortestPath.jl

@@ -121,11 +121,11 @@ function Utils.generate_sample(
     else
         rand(rng, Uniform{type}(1 - ν, 1 + ν), E)
     end
-    costs = -(1 .+ (3 .+ B * features ./ type(sqrt(p))) .^ deg) .* ξ
+    θ_true = -(1 .+ (3 .+ B * features ./ type(sqrt(p))) .^ deg) .* ξ
 
     maximizer = Utils.generate_maximizer(bench)
-    solution = maximizer(costs)
-    return DataSample(; x=features, θ_true=costs, y_true=solution)
+    y_true = maximizer(θ_true)
+    return DataSample(; x=features, θ=θ_true, y=y_true)
 end
 
 """

src/PortfolioOptimization/PortfolioOptimization.jl

@@ -94,12 +94,12 @@ function Utils.generate_sample(
     features = randn(rng, type, p)
     B = rand(rng, Bernoulli(0.5), d, p)
     c̄ = (0.05 / type(sqrt(p)) .* B * features .+ 0.1^(1 / deg)) .^ deg
-    costs = c̄ .+ L * f .+ 0.01 * ν * randn(rng, type, d)
+    θ_true = c̄ .+ L * f .+ 0.01 * ν * randn(rng, type, d)
 
     maximizer = Utils.generate_maximizer(bench)
-    solution = maximizer(costs)
+    y_true = maximizer(θ_true)
 
-    return DataSample(; x=features, θ_true=costs, y_true=solution)
+    return DataSample(; x=features, θ=θ_true, y=y_true)
 end
 
 """