documenation with full objective function formulations

[ricschuster]

@jeffreyhanson, do you think it would be useful to add a vignette/help page to the prioritizr website that would show the full objective function formulation for different objective function and constraint/penalty formulations? Would be even cooler if there would be a way to make this interactive (i.e. user picks a combination of things and the mathematical formulation is generated), but I don't know if that's easy to do.

[jeffreyhanson]

Yeah, I think something like this would be really valuable.

I think the number of combinations of different penalties/objectives/constraints means that we would be looking at over 30 different ILP formulations in total, so I think they will need to be dynamically generated. I like the idea of an interactive app (perhaps we could use MathJax to handle the math symbols). What do you think about having some function that takes a problem object and somehow outputs the mathematical formulation of the problem? Perhaps it might be useful to have the ability to export the maths as a latex/docx/html format so that users could just copy and paste (and slightly modify to avoid plagiarism) the output and embed it into their supporting information when writing scientific articles?

More broadly though, I don't know if this functionality would really address the issues of users not really understanding the different objectives/penalties/constraints? I feel like the documentation for the objective functions contains the "math explanation" but my impression is that many users have a hard time understanding what this means (based on the users that email me for help -- but this may not be representative of the majority of users)?

Also, I feel like this might be suggesting the same stuff as in #61 (but I can't remember exactly what #61 was and I didn't include much detail in the issue when creating it)? Do you think so? If so, then we can close #61 to reduce duplicate issues.

[ricschuster]

I really like the idea of a function that takes a problem object and somehow outputs the mathematical formulation of the problem. I think that would be really handy. And yes to the latex/docx/html format output, that would be awesome!

I think you are right, that this might not really address the issue of not really understanding the different parameters. Maybe adding something that's more tangible to the documentation would help? I'm not sure how to best do that though. Do you have any ideas?

I think you are right re: #61. I went ahead and closed it.

[jeffreyhanson]

Yeah, I don't really have any ideas on how to make the documentation easier to understand (without loosing important details) for individuals that don't understand the maths formulations. I suppose one approach would be to provide some example data in the documentation (e.g. examples matrices) and show what the objective values would be?

[ricschuster]

It's a tough one for sure. Maybe examples would help, but those will get fairly complex pretty quickly, once one adds constraints and penalties. Thinking about very small example might not be a bad idea though.