Improve documentation and introduce simple synthetic examples

[slwu89]

Hi @thevolatilebit this is a draft PR to address some of the documentation topics we discussed in the enterprise internal repo. As a reminder, what I would eventually like this PR to include is:

• Move duplicated theoretical parts out of the existing tutorials into 2 separate tutorials based on introducing the theory/mathematical preliminaries behind static and generative designs.
• Make simple examples for static and generative designs based on synthetic data that may be used to show just the theory and potentially in our tests to speed up tests, which currently take some time to run.

The synthetic example for static designs works great and is producing expected results with the input data.

That all being said, I am having trouble getting synthetic examples with known properties to work for the generative designs. In this file https://github.com/Merck/CEED.jl/blob/8786d768198bad2f1d5b77013019c93291760c05/tutorials/SimpleGenerative.jl I have attempted to set up an example with both a continuous and discrete outcome. However, for both cases, the MDP solution is always the empty set, despite the features contributing information to predicting the outcome, by construction. @thevolatilebit I am wondering if you can help me look at those 2 examples to figure out why this is the case, I am very curious why I cannot get different actions proposed.

[thevolatilebit]

Thanks, @slwu89, for the fantastic tutorials.

Two reasons explain why other designs were not displayed: Firstly, even after running experiments e1 to e4, the uncertainty still exceeds the threshold, resulting in a "bigM" penalty: https://github.com/Merck/CEED.jl/blob/b803dfddd818d3844f33b3967201dd1c7535e1ef/src/GenerativeDesigns/UncertaintyReductionMDP.jl#L153-L155

Secondly, a filter for "degenerate" designs with too high cost existed in: https://github.com/Merck/CEED.jl/blob/6d932f6a69bdb7906ae8c1dd82c9a1008c336010/src/fronts.jl#L108-L110

I have now removed this condition.

[thevolatilebit]

It would be great to eventually feature the Mahalanobis distance (#7) in the synthetic examples as well.

[slwu89]

@thevolatilebit, I've included Mahalanobis distance (#7) in the generative tutorial now. Still need to spend more time on the explanatory text before it's ready for your review.

[slwu89]

@thevolatilebit can you help me take a look at tutorials/SimpleGenerative.jl and tutorials/SimpleStatic.jl and make sure that they are set up correctly with the rest of the Project.toml files and things, for building docs? When I run the docs/make.jl file I get errors of the sort pasted below from the new tutorial files. For example, Distributions is in tutorials/Project.toml but not in docs/Project.toml, and I am not sure if it is supposed to be there too. Thanks!

┌ Warning: failed to run `@example` block in src/tutorials/SimpleGenerative.md:148-156
│ ```@example SimpleGenerative
│ using CEEDesigns, CEEDesigns.GenerativeDesigns
│ using DataFrames
│ using ScientificTypes
│ import Distributions
│ using Copulas
│ using POMDPs, POMDPTools, MCTS
│ using Plots, StatsPlots, StatsBase
│ ```
│   value =
│    ArgumentError: Package Distributions not found in current path.
│    - Run `import Pkg; Pkg.add("Distributions")` to install the Distributions package.
└ @ Documenter.Expanders ~/.julia/packages/Documenter/bYYzK/src/Utilities/Utilities.jl:34

[thevolatilebit]

@thevolatilebit can you help me take a look at tutorials/SimpleGenerative.jl and tutorials/SimpleStatic.jl and make sure that they are set up correctly with the rest of the Project.toml files and things, for building docs? When I run the docs/make.jl file I get errors of the sort pasted below from the new tutorial files. For example, Distributions is in tutorials/Project.toml but not in docs/Project.toml, and I am not sure if it is supposed to be there too. Thanks!

┌ Warning: failed to run `@example` block in src/tutorials/SimpleGenerative.md:148-156
│ ```@example SimpleGenerative
│ using CEEDesigns, CEEDesigns.GenerativeDesigns
│ using DataFrames
│ using ScientificTypes
│ import Distributions
│ using Copulas
│ using POMDPs, POMDPTools, MCTS
│ using Plots, StatsPlots, StatsBase
│ ```
│   value =
│    ArgumentError: Package Distributions not found in current path.
│    - Run `import Pkg; Pkg.add("Distributions")` to install the Distributions package.
└ @ Documenter.Expanders ~/.julia/packages/Documenter/bYYzK/src/Utilities/Utilities.jl:34

@slwu89 Yeah, it is necessary to add all the dependencies to docs/Project.toml as well. Should be fixed now.

[slwu89]

Thanks.

[thevolatilebit]

Excellent job, thank you, @slwu89 !