[docs] small tweaks to examples (#666)

* small tweaks to examples

* Apply suggestions from code review

Author: ericphanson

docs/src/examples/general_examples/DCP_analysis.jl

@@ -2,6 +2,10 @@
 using Convex
 x = Variable();
 y = Variable();
-expr = quadoverlin(x - y, 1 - max(x, y));
-println("expression curvature = ", vexity(expr));
+expr = quadoverlin(x - y, 1 - max(x, y))
+
+# We can see from the printing of the expression that this `quadoverlin` (`qol`) atom
+# is convex with positive sign. We can query these programmatically using the `vexity`
+# and `sign` functions:
+println("expression convexity = ", vexity(expr));
 println("expression sign = ", sign(expr));

docs/src/examples/general_examples/basic_usage.jl

@@ -1,8 +1,10 @@
 # # Basic Usage
 
+# First we load Convex itself, LinearAlgebra to access the identity matrix `I`,
+# and two solvers: SCS and GLPK.
 using Convex
 using LinearAlgebra
-using SCS
+using SCS, GLPK
 
 # ### Linear program
 #
@@ -26,6 +28,7 @@ constraints = [A * x <= b, x >= 1, x <= 10, x[2] <= 5, x[1] + x[4] - x[2] <= 10]
 p = minimize(dot(c, x), constraints) # or c' * x
 solve!(p, SCS.Optimizer; silent_solver = true)
 
+# We can also inspect the objective value and the values of the variables at the solution:
 println(round(p.optval, digits = 2))
 println(round.(evaluate(x), digits = 2))
 println(evaluate(x[1] + x[4] - x[2]))
@@ -48,6 +51,8 @@ y = Variable()
 ## X is a 2 x 2 variable, and y is scalar. X' + y promotes y to a 2 x 2 variable before adding them
 p = minimize(norm(X) + y, 2 * X <= 1, X' + y >= 1, X >= 0, y >= 0)
 solve!(p, SCS.Optimizer; silent_solver = true)
+
+# We can also inspect the values of the variables at the solution:
 println(round.(evaluate(X), digits = 2))
 println(evaluate(y))
 p.optval
@@ -72,24 +77,21 @@ p = satisfy(
     geomean(x[3], x[4]) >= x[2],
 )
 solve!(p, SCS.Optimizer; silent_solver = true)
-println(p.status)
-evaluate(x)
 
-# ### SDP cone and Eigenvalues
+# ### PSD cone and Eigenvalues
 
 y = Semidefinite(2)
 p = maximize(eigmin(y), tr(y) <= 6)
 solve!(p, SCS.Optimizer; silent_solver = true)
-p.optval
 
 #-
 
 x = Variable()
 y = Variable((2, 2))
-## SDP constraints
+
+## PSD constraints
 p = minimize(x + y[1, 1], y ⪰ 0, x >= 1, y[2, 1] == 1)
 solve!(p, SCS.Optimizer; silent_solver = true)
-evaluate(y)
 
 # ### Mixed integer program
 #
@@ -102,9 +104,10 @@ evaluate(y)
 # ```
 #
 
-using GLPK
 x = Variable(4, IntVar)
 p = minimize(sum(x), x >= 0.5)
 solve!(p, GLPK.Optimizer; silent_solver = true)
+
+# And the value of `x` at the solution:
 evaluate(x)
 #-

docs/src/examples/general_examples/chebyshev_center.jl

@@ -30,7 +30,6 @@ constraints = [
 ]
 p = maximize(r, constraints)
 solve!(p, SCS.Optimizer; silent_solver = true)
-p.optval
 
 # Generate the figure
 x = range(-1.5, stop = 1.5, length = 100);

docs/src/examples/general_examples/dualization.jl

@@ -25,8 +25,8 @@ p = 50
 # Now we formulate and solve our primal problem:
 d = Variable(p)
 problem = maximize(sum(d), 0 ≤ d, d ≤ 1, Σ ⪰ Diagonal(d))
-@elapsed solve!(problem, SCS.Optimizer; silent_solver = true)
+@time solve!(problem, SCS.Optimizer; silent_solver = true)
 
 # To solve the dual problem instead, we simply call `dual_optimizer` on our
 # optimizer function:
-@elapsed solve!(problem, dual_optimizer(SCS.Optimizer); silent_solver = true)
+@time solve!(problem, dual_optimizer(SCS.Optimizer); silent_solver = true)

docs/src/examples/general_examples/huber_regression.jl

@@ -22,8 +22,8 @@ v = randn(number_samples);
 
 #-
 
-## Generate data for different values of p.
-## Solve the resulting problems.
+# Generate data for different values of p.
+# Solve the resulting problems.
 using Convex, SCS, Distributions
 lsq_data = zeros(number_tests);
 huber_data = zeros(number_tests);

docs/src/examples/general_examples/lasso_regression.jl

@@ -8,23 +8,19 @@
 
 using DelimitedFiles, LinearAlgebra, Statistics, Plots, Convex, SCS
 
-# # Loading Data
+# ## Loading Data
 #
 # We use the diabetes data from Efron et al, downloaded from https://web.stanford.edu/~hastie/StatLearnSparsity_files/DATA/diabetes.html and then converted from a tab to a comma delimited file.
 #
 # All data series are standardised (see below) to have zero means and unit standard deviation, which improves the numerical stability. (Efron et al do not standardise the scale of the response variable.)
 
 x, header =
     readdlm(joinpath(@__DIR__, "aux_files/diabetes.csv"), ',', header = true)
-#display(header)
-#display(x)
+x = (x .- mean(x, dims = 1)) ./ std(x, dims = 1) # standardise
+(Y, X) = (x[:, end], x[:, 1:end-1]); # to get traditional names
+xNames = header[1:end-1]
 
-x = (x .- mean(x, dims = 1)) ./ std(x, dims = 1)          #standardise
-
-(Y, X) = (x[:, end], x[:, 1:end-1]);                  #to get traditional names
-xNames = header[1:end-1];
-
-# # Lasso, Ridge and Elastic Net Regressions
+# ## Lasso, Ridge and Elastic Net Regressions
 #
 # (a)  The regression is $Y = Xb + u$,
 # where $Y$ and $u$ are $T \times 1$, $X$ is $T \times K$, and $b$ is the $K$-vector of regression coefficients.
@@ -64,12 +60,14 @@ function LassoEN(Y, X, γ, λ = 0)
     L4 = sumsquares(b)            #sum(b^2)
 
     if λ > 0
-        Sol = minimize(L1 - 2 * L2 + γ * L3 + λ * L4)      #u'u/T + γ*sum(|b|) + λ*sum(b^2), where u = Y-Xb
+        ## u'u/T + γ*sum(|b|) + λ*sum(b^2), where u = Y-Xb
+        problem = minimize(L1 - 2 * L2 + γ * L3 + λ * L4)
     else
-        Sol = minimize(L1 - 2 * L2 + γ * L3)               #u'u/T + γ*sum(|b|) where u = Y-Xb
+        ## u'u/T + γ*sum(|b|) where u = Y-Xb
+        problem = minimize(L1 - 2 * L2 + γ * L3)
     end
-    solve!(Sol, SCS.Optimizer; silent_solver = true)
-    Sol.status == Convex.MOI.OPTIMAL ? b_i = vec(evaluate(b)) : b_i = NaN
+    solve!(problem, SCS.Optimizer; silent_solver = true)
+    problem.status == Convex.MOI.OPTIMAL ? b_i = vec(evaluate(b)) : b_i = NaN
 
     return b_i, b_ls
 end
@@ -82,7 +80,7 @@ K = size(X, 2)
 (b, b_ls) = LassoEN(Y, X, γ)
 
 println("OLS and Lasso coeffs (with γ=$γ)")
-display([["" "OLS" "Lasso"]; xNames b_ls b])
+println([["" "OLS" "Lasso"]; xNames b_ls b])
 
 # # Redo the Lasso Regression with Different Gamma Values
 #
@@ -111,7 +109,7 @@ plot(
     size = (600, 400),
 )
 
-# # Ridge Regression
+# ## Ridge Regression
 #
 # We use the same function to do a ridge regression. Alternatively, do `b = inv(X'X/T + λ*I)*X'Y/T`.
 

docs/src/examples/general_examples/max_entropy.jl

@@ -24,7 +24,6 @@ b = rand(m, 1);
 x = Variable(n);
 problem = maximize(entropy(x), sum(x) == 1, A * x <= b)
 solve!(problem, SCS.Optimizer; silent_solver = true)
-problem.optval
 
 #-
 

docs/src/examples/general_examples/robust_approx_fitting.jl

@@ -39,23 +39,28 @@ B = B / norm(B);
 b = randn(m, 1);
 x = Variable(n)
 
-# Case 1: nominal optimal solution
+# ## Case 1: nominal optimal solution
 p = minimize(norm(A * x - b, 2))
 solve!(p, SCS.Optimizer; silent_solver = true)
+#-
 x_nom = evaluate(x)
 
-# Case 2: stochastic robust approximation
+# ## Case 2: stochastic robust approximation
 P = 1 / 3 * B' * B;
 p = minimize(square(pos(norm(A * x - b))) + quadform(x, Symmetric(P)))
 solve!(p, SCS.Optimizer; silent_solver = true)
+#-
 x_stoch = evaluate(x)
 
-# Case 3: worst-case robust approximation
+# ## Case 3: worst-case robust approximation
 p = minimize(max(norm((A - B) * x - b), norm((A + B) * x - b)))
 solve!(p, SCS.Optimizer; silent_solver = true)
+
+#-
 x_wc = evaluate(x)
 
-# Plot residuals:
+# ## Plots
+# Here we plot the residuals.
 parvals = range(-2, stop = 2, length = 100);
 
 errvals(x) = [norm((A + parvals[k] * B) * x - b) for k in eachindex(parvals)]

docs/src/examples/general_examples/trade_off_curves.jl

@@ -1,4 +1,6 @@
-# # Trade-off curves
+# # Regularized least-squares
+# Here we solve some constrained least-squares problems with 1-norm regularization,
+# and plot how the solution changes with increasing regularization.
 using Random
 Random.seed!(1)
 m = 25;

docs/src/examples/general_examples/worst_case_analysis.jl

@@ -19,6 +19,7 @@ ret = dot(r, w);
 risk = sum(quadform(w, Sigma_nom));
 problem = minimize(risk, [sum(w) == 1, ret >= 0.1, norm(w, 1) <= 2])
 solve!(problem, SCS.Optimizer; silent_solver = true)
+#-
 wval = vec(evaluate(w))
 
 #-
@@ -37,6 +38,7 @@ problem = maximize(
     ],
 );
 solve!(problem, SCS.Optimizer; silent_solver = true)
+#-
 println(
     "standard deviation = ",
     round(sqrt(wval' * Sigma_nom * wval), sigdigits = 2),