search

pymc-devs / pymc

Bayesian Modeling and Probabilistic Programming in Python
https://docs.pymc.io/
Other
8.7k stars 2.01k forks source link

Solid draft of documentation #346

Closed jsalvatier closed 9 years ago

jsalvatier commented 11 years ago

There's a skeleton already, but needs to be filled out.

jsalvatier commented 11 years ago

@fonnesbeck We should put together a plan for getting the docs done. First off, who's taking the lead? Is this something you're planning on tackling? Or should I take it on?

I feel a bit intimidated by the idea of writing the docs, but that might just mean it would be a good learning experience.

fonnesbeck commented 11 years ago

I'm comfortable writing documentation, but will not be able to get to it until late November, since I have a heavy teaching load right now. So, if you have the time, feel free to get started, otherwise I will pick it up in a couple months.

fonnesbeck commented 11 years ago

One thing the docs are going to have to have is a pretty extensive Theano tutorial. The one on deeplearning.net is not very good. Having data interact with PyMC objects is not straightforward; For example, making linear combinations of values of data with values of distributions for use in other parts of the model. This aspect of PyMC will be the biggest learning hurdle for folks coming across from PyMC 2.

twiecki commented 10 years ago

Maybe we can start by adapting the pymc2 documentation which is pretty good. Things like the disaster model are already ported so parts like the tutorial should be trivial.

twiecki commented 10 years ago

Another idea would be to use @camdavidsonpilon's Probabilistic Programming for Hackers book which could be ported to pymc3 without too much effort and already covers most of the bases.

https://github.com/CamDavidsonPilon/Probabilistic-Programming-and-Bayesian-Methods-for-Hackers/issues/155

jsalvatier commented 10 years ago

Very clever, I like it. We should ask the Cam, though.

That seems like it might annoy him and/or violate his copyrights.

jsalvatier commented 10 years ago

@fonnesbeck What's the best way for me to contribute to working on the docs?

fonnesbeck commented 10 years ago

I think borrowing chunks of the PPH book is a good idea, but there are big sections of the book that probably would not work as part of a user's guide. It also does not touch on one of the biggest aspects of PYMC 3, which is the gradient-based MC.

@jsalvatier I would pick a section in the existing skeleton and start fleshing it out. That skeleton is based entirely on PyMC 2, so it is not exactly what we need. For example, we need an entire Theano section, since it is such a central part of the new version.

One choice we need to make is whether to stick with reStructuredText/Sphinx or move to some flavor of Markdown. The world seems to be moving toward the latter, but there are advantages to reST in a Python context.

CamDavidsonPilon commented 10 years ago

I have plans to convert the book to PyMC3 already, but I agree with @fonnesbeck that the book is currently too broad to be used as specific documentation for PyMC3. Power users of PyMC2/3 would find the text too high level for their needs too.

fonnesbeck commented 10 years ago

I'm also working on a book for Springer that will be geared towards advanced statistical applications, and include a fair bit of theoretical background. So between Cam's book and mine there should be a fair quantity of "extended documentation" for those who are interested. That should allow us to keep the docs focused as mostly a technical reference and quick start for users.

jsalvatier commented 10 years ago

Writing the documentation, I'm noticing that our language of FreeRV and ObservedRV is pretty different than Stochastic. I wonder if we can bring the language closer.

I also notice that a Potential is not longer a class, but just a function. We should probably make it a class that inherits from Factor just to make it consistent with PyMC2

twiecki commented 10 years ago

Different how? Isn't FreeRV == stochastic and ObservedRV == observed?

jsalvatier commented 10 years ago

Well we didn't have Observed in PyMC2, stochastic referred to both Free and Observed, but maybe we should have Stochastic refer to just Free?

On Mon, Mar 3, 2014 at 6:37 AM, Thomas Wiecki notifications@github.comwrote:

Different how? Isn't FreeRV == stochastic and ObservedRV == observed?

Reply to this email directly or view it on GitHubhttps://github.com/pymc-devs/pymc/issues/346#issuecomment-36515246 .

twiecki commented 10 years ago

For me the current distinction makes intuitive sense. Having Free refer to Stochastic also makes sense.

twiecki commented 9 years ago

Current draft lives at http://pymc-devs.github.io/pymc3/.