[docs] update docs

docs/src/build.md

@@ -2,5 +2,5 @@
 
 ```@autodocs
 Modules = [ATA]
-Pages   = ["build.jl"]
+Pages   = ["build/build.jl"]
 ```

docs/src/compact.md

@@ -0,0 +1,6 @@
+# Compact ATA
+
+```@autodocs
+Modules = [ATA]
+Pages   = ["compact_ata.jl"]
+```

docs/src/examples.md

@@ -1,120 +1,3 @@
 # Examples
 
-## Example with JuMP (0.21.3) and Cbc
-
-0\. Add and load required packages.
-```julia
-#cd("folder in which the package is saved")
-using Pkg
-Pkg.activate(".")  # required
-Pkg.instantiate()
-using ATA
-cd("examples")
-Pkg.add("JuMP@0.21.3")
-using JuMP
-Pkg.add("Cbc")
-using Cbc
-```
-
-1\. Resetting the ATA process and load settings (Needed)
-
-```julia
-ata_model = start_ata(settings_file="examples/settings_ata_maximin.jl", bank_file="examples/data/bank.csv", bank_delim=";")
-print_last_info(ata_model)
-```
-
-2\. Add friend set variables (Optional)
-
-```julia
-add_friends!(ata_model)
-print_last_info(ata_model)
-```
-
-3\. Add enemy set variables (Optional)
-
-```julia
-add_enemies!(ata_model)
-print_last_info(ata_model)
-```
-
-4\. Add constraints (Optional)
-
-```julia
-add_constraints!(
-    ata_model;
-    constraints_file = "examples/constraints.csv",
-    constraints_delim = ";",
-)
-print_last_info(ata_model)
-```
-
-5\. Add overlap maxima (Optional)
-
-```julia
-add_overlap!(ata_model; overlap_file = "examples/overlap_matrix.csv", overlap_delim = ";")
-print_last_info(ata_model)
-```
-
-6\. Add expected score constraints (Optional)
-
-```julia
-add_exp_score!(ata_model)
-print_last_info(ata_model)
-```
-
-7\. Group items by friend sets (Optional, Needed if `add_friends!(model)` has been run)
-
-```julia
-group_by_friends!(ata_model)
-print_last_info(ata_model)
-```
-
-8\. Add objective function (Optional)
-
-```julia
-add_obj_fun!(ata_model)
-print_last_info(ata_model)
-```
-
-9\. Assemble
-
-Set the solver, "siman" for simulated annealing, "jumpATA" for MILP solver.
-```julia
-solver = "jumpATA"
-```
-
-MILP (Not suggested for large scale ATA)
-Select the solver, Cbc as open-source is a good option:
-```julia
-optimizer_constructor = "Cbc"
-```
-
-Optimizer attributes:
-```julia
-optimizer_attributes = [("seconds", 100), ("logLevel", 1)]
-```
-
-```julia
-  assemble!(ata_model;
-      solver=solver,
-      optimizer_attributes = optimizer_attributes,
-      optimizer_constructor = optimizer_constructor
-  )
-```
-
-10\. Print and Plot
-
-All the settings and outputs are in the ata_model object.
-See the struct in ATA.jl to understand how to retrieve all the information.
-A summary of the resulting tests is available in <results_folder>/results.txt
-If siman is chosen, the optimality and feasibility of the best neighbourhood
-is reported in <results_folder>/results_ata.jl
-
-```julia
-print_results(ata_model; group_by_fs = true, results_folder = "results")
-```
-
-```julia
-using ATAPlot
-plot_results(ata_model; group_by_fs = true, results_folder = "plots")
-```
+The folder "examples" contains several examples of ATA models solved with ATA.jl.

docs/src/index.md

@@ -6,43 +6,55 @@ end
 ```
 # ATA.jl: Automated Test Assembly Made Easy
 
+Version 0.10.0
+
 A package for automated test assembly (ATA) written in Julia.
 Simulated Annealing algorithm is available for large scale ATA models.
 Otherwise, any MILP solver compatible with JuMP can be used.
 Interfaced with Dash or pure Julia code.
 
+## Documentation
+
+Documentation on exported functions available at [link](https://giadasp.github.io/ATA.jl/docs) (in progress).
+
 ## Objectives
+
 1. no objective;
 2. MAXIMIN TIF (minimum between multiple ability points supported);
-3. Chance-constrained MAXIMIN TIF.
+3. Chance-constrained MAXIMIN TIF;
 4. MINIMAX TIF (maximum between multiple ability points supported);
+5. custom objective function (only for siman solver)
 
 ## Constraints
+
 - parallel tests (one group of tests);
 - non-parallel tests (more than one group of tests);
 - minimum and/or maximum length;
 - minimum and/or maximum number of items with certain features (categorical constraints);
 - maximum and/or minimum sum of numerical variables (quantitative constraints);
-- maximum and/or minimum expected scores at multiple ability point;
-- minimum and/or maximum item use;
-- maximum and/or minimum mean of numerical variables (quantitative constraints); (beta)
+- maximum and/or minimum expected scores at multiple ability point; 
 - maximum and/or minimum expected score based on the IRT paradigm or by a given column in the pool dataframe;
-- maximum overlap between tests;
+- minimum and/or maximum item use;
+- maximum and/or minimum mean of numerical variables (quantitative constraints); (will be implemented soon)
+- maximum overlap between tests; (increases dramatically the size and complexity of MILP ATA models `:boom:`, we suggest to avoid this constraint if the ATA model is already very large or, alternatively, to use the siman solver `:smirk_cat:`)
 - group by units (friend sets);
 - items exclusivity (enemy sets);
 
 ## Solvers
-- for objectives 1 and 2: JuMP MILP solvers (see the list at https://jump.dev/JuMP.jl/v0.21.1/installation/). Follow the installation manuals of the solver you want to use. For open-source we suggest CBC or GLPK (default). For commercial we suggest Gurobi or CPLEX.
-- for objectives 1, 2 and 3: Simulated Annealing solver, pure Julia ATA solver.
+
+- for objectives 1, 2, and 4: JuMP MILP solvers (see the list at https://jump.dev/JuMP.jl/v0.21.1/installation/). Follow the installation manuals of the solver you want to use. We suggest CBC or GLPK (default) as open-source solvers. Also commercial solvers are supported, CPLEX and Gurobi are examples.
+- for objectives 1, 2, 3, 4 and 5 (all): Simulated Annealing solver (siman), pure Julia ATA solver.
 
 ## Report
-Summarizing features of the assembled tests and Plots of the ICFs and TIFs are available.
+
+Summarizing features of the assembled tests and plots are available.
+Add [`ATAPlot`](https://github.com/giadasp/ATAPlot.jl) to plot the Test Information Functions (TIFs) and Item Characteristic Functions (ICTs).
 
 ## How to
 
 If you want to play with this package:
 
-Install Julia-1.5.1 at `https://julialang.org/downloads/`
+Install Julia-1.6.0-rc1 at `https://julialang.org/downloads/`
 
 run `Julia.exe` and type:
 
@@ -58,16 +70,22 @@ using ATA
 
 Play with the test files in folder "examples".
 
-Set all the specifications by modifying the files in "examples" folder and run "example.jl" or "example custom objective function.jl" following the manual in the comments.
+For a quick and compact ATA instance, run the code in "example_compact.jl".
+
+If you want to dig in all the ATA building, assembly and output steps, run the code in the other files in the folder.
+The comments explain which arguments must be customized in order to solve your ATA model. 
+If you do not modify the arguments you just solve a toy ATA model with 3 non parallel groups of tests assembled starting from a 366 items bank.
+
+For an even more easier ATA experience, look at "example_dash_app.jl".
+It requires the installation of the package [`ATADash`](https://github.com/giadasp/ATADash.jl)
 
-Distributed analysis of the neighbourhoods is available, look at "examples/example parallel.jl".
+As a remind, to plot the TIFs and ICTs you must install (add) and load (using) the package [`ATAPlot`](https://github.com/giadasp/ATAPlot.jl).
 
-A Dash app is available for an even more easier experience. Look at "examples/example Dash app.jl"
 
 ## Documentation Contents
 
 ```@contents
-Pages = ["build.md", "opt.md", "print.md", "utils.md", "examples.md"]
+Pages = ["build.md", "opt.md", "compact.md", "print_and_plot.md", "structs.md", "utils.md", "examples.md"]
 Depth = 3
 ```
 

docs/src/print.md → docs/src/print_and_plot.md

@@ -2,5 +2,5 @@
 
 ```@autodocs
 Modules = [ATA]
-Pages   = ["print.jl"]
+Pages   = ["print/print.jl", plot.jl]
 ```

docs/src/structs.md

@@ -0,0 +1,6 @@
+# Structs
+
+```@autodocs
+Modules = [ATA]
+Pages   = ["structs/structs.jl"]
+```

src/ATA.jl

@@ -15,7 +15,7 @@ using Requires
 using Psychometrics
 using FileIO
 
-include("structs/ata_model.jl")
+include("structs/structs.jl")
 include("utils.jl")
 include("build/build.jl")
 include("opt.jl")

src/print/print.jl

@@ -2,3 +2,16 @@ include("print_no_obj.jl")
 include("print_info.jl")
 include("print_maximin.jl")
 include("print_cc_maximin.jl")
+
+function print_neighbourhood(x::Neighbourhood)
+    Printf.@printf("\n  f : %5.3f", x.f)
+    Printf.@printf("\n  infeas :	[")
+    map(x -> Printf.@printf(" %5.1f", x), x.infeas)
+    Printf.@printf("    ]")
+    Printf.@printf("\n  overlaps :	[")
+    map(x -> Printf.@printf("  %5.1f", x), x.ol)
+    Printf.@printf("    ]")
+    Printf.@printf("\n  item use :	[")
+    map(x -> Printf.@printf("  %5.1f", x), x.iu)
+    Printf.@printf("    ]\n")
+end