Docstrings for plotting.py

[snilsn]

This PR contains revised docstrings for the plotting.py functions I've gotten to work so far.

Unfortunately, this time there are more functions which are not covered yet. To keep track of that I use this table

I created a notebook of my experiments with the functions that are marked as 'broken?'. I suspect some of them to have bugs, maybe resulting from changes in other parts of tobac. Others I perhaps use in the wrong way. None of these I saw in use in any of the examples.

This is probably worth a separate issue, like suggested in #146. We should discuss whether they should still be included in this PR.

• Have you followed our guidelines in CONTRIBUTING.md?
• Have you self-reviewed your code and corrected any misspellings?
• Have you written documentation that is easy to understand?
• Have you written descriptive commit messages?
• Have you formatted your code using black?
• Have all tests passed in your local clone?
• Have you kept your pull request small and limited so that it is easy to review?
• Have the newest changes from this branch been merged?

Not needed:

• Have you added NumPy docstrings for newly added functions?
• If you have introduced a new functionality, have you added adequate unit tests?
• If you have introduced a new functionality, have you added an example notebook?

[codecov]

Codecov Report

Merging #155 (6807a98) into RC_v1.4.0 (3ee91cc) will decrease coverage by 0.04%.
The diff coverage is n/a.

@@              Coverage Diff              @@
##           RC_v1.4.0     #155      +/-   ##
=============================================
- Coverage      32.23%   32.19%   -0.05%     
=============================================
  Files             11       11              
  Lines           2072     2050      -22     
=============================================
- Hits             668      660       -8     
+ Misses          1404     1390      -14     

Flag	Coverage Δ
unittests	32.19% <ø> (-0.05%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

Impacted Files	Coverage Δ
tobac/plotting.py	3.08% <ø> (+<0.01%)	⬆️
tobac/segmentation.py	75.24% <0.00%> (+6.39%)	⬆️

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 3ee91cc...6807a98. Read the comment docs.

[freemansw1]

Thanks Nils! I've requested @JuliaKukulies and myself for review. I'll try to get this reviewed before the developers' meeting. Agreed that we should discuss the plotting.py functions; I had no idea that this many of them were broken. I'm happy for you to open the issue, or I can do that!

[JuliaKukulies]

Thank you @snilsn for these comprehensive documentation improvements! This was for sure not an easy task, and based on your notebooks it seems like the plotting functions need some general revisions (good idea to open an issue for that!), which probably will require some update of these docstrings at a later point. I would, however, be happy to get these changes in for v1.4 as these are a nice complement to your PR #138. Again, just a few comments and suggestions, mainly typos and some clarifications

[snilsn]

Thanks for your feedback, @JuliaKukulies, most of your suggestions should be covered by the last commit.

[JuliaKukulies]

All right, approved from my side! Thanks for the changes @snilsn

I guess we can see over that codecov fails here - maybe discuss later how to set the threshold for accepted decrease in coverage.

[freemansw1]

Just a minor comment. Great work again.

[freemansw1]

OK- I've opened a new issue for the broken functions (#158).

[freemansw1]

Now that we have two approvals and this is passing non-coverage tests (see #159), I'm happy to merge this if you are happy for it to be merged @snilsn .

[snilsn]

Yes all good, please go ahead @freemansw1