search

sympy / sympy

A computer algebra system written in pure Python
https://sympy.org/
Other
13.01k stars 4.45k forks source link

Improving the landing page of `sympy.stats` on SymPy docs #19951

Open czgdp1807 opened 4 years ago

czgdp1807 commented 4 years ago

https://docs.sympy.org/dev/modules/stats.html contains some nice examples for different features of the stats module but I, as an end user, would like to see some uses and applications at the top of the page. In addition, some information regarding sampling using external libraries can also be added and how stats module is compatible with other libraries having numerical computation capabilities.

May be, we can comment what all should be there like applications and examples of where users can use it in their work.

@Upabjojr @Smit-create

Upabjojr commented 4 years ago

Maybe adding a tutorial first, the API later.

czgdp1807 commented 4 years ago

Agreed. How the tutorial should look like? Some examples from books/papers solved/imitated using sympy.stats?

Smit-create commented 4 years ago

Can we create Notebooks with all the distributions in the ordered fashion as following?

  1. Title and pdf of the Distribution
  2. plot of pdf and CDF
  3. Analytical functions like variance, moment, kurtosis and skewness of the distribution
  4. References
czgdp1807 commented 4 years ago

Are there any existing notebooks for other SymPy modules? If yes, then we can create for stats as well but not entirely focusing on distributions, for stochastic processes as well. I would suggest to show some problem solving(real ones preferred) using stats module rather than some made up examples.

Smit-create commented 4 years ago

Are there any existing notebooks for other SymPy modules?

I see a bunch of notebooks here https://github.com/sympy/scipy-2016-tutorial. Maybe @Sc0rpi0n101 was working as I saw an email on the mailing list EDIT: Might be related https://github.com/sympy/scipy-2016-tutorial/issues/5

Upabjojr commented 4 years ago

Documentation is way better than notebooks. Users usually read the documentation, not the notebooks.

Smit-create commented 4 years ago

Documentation is way better than notebooks.

Yeah, but we can design something like scipy.stats. I think they also have somewhat followed this fashion https://github.com/sympy/sympy/issues/19951#issuecomment-671893584

Sc0rpi0n101 commented 4 years ago

I see a bunch of notebooks here https://github.com/sympy/scipy-2016-tutorial. Maybe @Sc0rpi0n101 was working as I saw an email on the mailing list EDIT: Might be related sympy/scipy-2016-tutorial#5

I am working on collecting all the notebooks and moving them to https://github.com/sympy/sympy-notebooks. If you are planning to create new notebooks, I would ask you to add your notebooks to this repo too.

Also, I agree with @Upabjojr. Notebooks might be a good idea to assist the users along with the documentation. But the users will mostly only read the documentation, and that too only the part they require.

czgdp1807 commented 4 years ago

Adding notebooks is a different issue. For the landing page of sympy.stats, I would suggest the following.

  1. Examples - This section contains some introduction and examples. For the introduction, I think current is a bit incomplete and doesn't highlight much on the uses of the module. https://www.wolframalpha.com/examples/mathematics/statistics/ starts with what statistics actually is and how Wolfram is useful to the people involved in the area. Something similar should be done with this section. We should start with definition of statistics and then one or two problems from some popular books or some popular problems in statistics solved using sympy.stats.

  2. Random Variable Types - Actually this doesn't seem really good for a title IMO. We should change it to something like, Supported Concepts or Features and under it the details of following can be listed,

  1. API Reference - This should contain the details of sympy.stats public API.

  2. Mechanics - This section should be for developers and should describe the design and working of sympy.stats in detail.

Regarding notebooks, they can be added for sure in the repository but that should be discussed in a different issue for clarity.

Looking forward to feedbacks. A PR can be started after some discussions.

asmeurer commented 4 years ago

There are ways to include notebooks in Sphinx docs, but it would require a bit to set up. We would need to make sure that they are properly doctested, for example, and also that the committed notebooks don't have large binary blobs. Unless someone wants to work on setting that up, we should just focus on writing normal documents.

Something that I would suggest doing is having a clear separation between tutorials and the API reference. See https://documentation.divio.com/