API Reference Examples

[genedan]

This issue governs the initiative to populate the API Reference with examples. Having a richly-populated API reference will help:

1. Make it easier to find examples per class/method/function rather than search through the tutorials
2. Improve the library's ranking in Google search
3. Drive adoption of the package and expand the userbase

As a reference for what this should look like, please refer to the Pandas documentation on the DataFrame, in the Examples section.

Instructions

An example is placed within the docstring of a class, method, or function. Below is an example for the Triangle class. We'll adopt the pattern of using the .. testsetup::, .. testcode::, .. testoutput:: pattern, which you can read more about here. When the documentation is published, examples within the docstring will automatically populate the API reference and will be tested for correctness.

Examples
--------

Constructing a Triangle from a Pandas DataFrame.

..  testsetup::

    import chainladder as cl

..  testcode::

    import pandas as pd

    df = pd.DataFrame(
        data={
            'origin': [1981, 1981, 1981, 1981, 1982, 1982, 1982, 1983, 1983, 1984],
            'development': [1981, 1982, 1983, 1984, 1982, 1983, 1984, 1983, 1984, 1984],
            'reported': [5012, 8269, 10907, 11805, 106, 4285, 5396, 3410, 8992, 5655]
        }
    )
    tr = cl.Triangle(
        data=df,
        origin='origin',
        development='development',
        columns=['reported'],
        cumulative=True
    )
    print(tr)

    .. testoutput::

              12      24       36       48
    1981  5012.0  8269.0  10907.0  11805.0
    1982   106.0  4285.0   5396.0      NaN
    1983  3410.0  8992.0      NaN      NaN
    1984  5655.0     NaN      NaN      NaN

Tracking

The current plan is to have one person assigned per module. All you have to do to participate is respond to this thread with the module you'd like to work on, and it'll be assigned to you.

The status states will be: Unassigned, In-progress, and Complete. In order to be complete, we should have:

• Each parameter to a class constructor, method, or function should have at least one example demonstrating its usage.
• If a parameter has several options, we should have more examples covering the most important variations. This would involve the judgment of the PR reviewers, since some parameters may have an infinite number of possible values. In this case we may suggest some extra examples, but not an exhaustive number of them since that wouldn't be possible.

Module	Assignee	Status
Triangle	@EKtheSage	In-progress
DevelopmentCorrelation		Unassigned
ValuationCorrelation		Unassigned
DevelopmentConstant		Unassigned
MunichAdjustment		Unassigned
IncrementalAdditive		Unassigned
ClarkLDF		Unassigned
CaseOutstanding		Unassigned
TweedieGLM		Unassigned
DevelopmentML		Unassigned
BarnettZehnwirth		Unassigned
TailConstant	@priyam0k	In-Progress
TailCurve		Unassigned
TailBondy		Unassigned
TailClark		Unassigned
Chainladder		Unassigned
MackChainladder		Unassigned
BornhuetterFerguson		Unassigned
Benktander		Unassigned
CapeCod		Unassigned
BootstrapODPSample		Unassigned
BerquistSherman		Unassigned
Trend		Unassigned
ParallelogramOLF		Unassigned
Pipeline		Unassigned
VotingChainladder		Unassigned
GridSearch		Unassigned
load_sample	@kennethshsu	In-progress
read_pickle		Unassigned
minimum		Unassigned
maximum		Unassigned
PatsyFormula		Unassigned

Other oustanding tasks

Increase the toctree level of the API reference to be one level deeper, since for large classes we should have separate pages for each method.

[genedan]

@EKtheSage, you're up for the Triangle class

[kennethshsu]

I think we should come up with a standard for the format, or follow a more popular project.

[kennethshsu]

I'll also be happy to take some of these. How about load_sample?

[genedan]

@kennethshsu you got it, I've assigned you. BTW it's possible to remove the import statements and prompts like you requested. This requires us to use the the directives .. testsetup::, .. testcode::, and .. testoutput. These can then be tested just like unit tests to make sure that the examples are correct each time we rebuild the docs. I do recommend that we add doctest as another GitHub actions workflow, since otherwise we'd risk having errors in the examples.

For example, rewriting what's been done in Triangle will be like:

  Examples
  --------
  
  Constructing a Triangle from a Pandas DataFrame.
    .. testsetup::

        import chainladder as cl
        import pandas as pd

    .. testcode::

        df = pd.DataFrame(
            data={
                'origin': [1981, 1981, 1981, 1981, 1982, 1982, 1982, 1983, 1983, 1984],
                'development': [1981, 1982, 1983, 1984, 1982, 1983, 1984, 1983, 1984, 1984],
                'reported': [5012, 8269, 10907, 11805, 106, 4285, 5396, 3410, 8992, 5655]
            }
        )
        tr = cl.Triangle(
            data=df,
            origin='origin',
            development='development',
            columns=['reported'],
            cumulative=True
        )
        print(tr)

    .. testoutput::

                  12      24       36       48
        1981  5012.0  8269.0  10907.0  11805.0
        1982   106.0  4285.0   5396.0      NaN
        1983  3410.0  8992.0      NaN      NaN
        1984  5655.0     NaN      NaN      NaN

And looks like:

The main downside is that you have to use the print(tr) in order to get the tests to pass. You can't just have tr at the bottom of the testcode block.

An alternative is to use the .. doctest:: directive. This allows us to avoid using print, but we would have to go back to displaying the prompt (>>>), which you found to be undesirable.

[kennethshsu]

I see, ok I don't know if what I have proposed is best anymore, sorry!

What is your recommendation? It seems like you've done quite a bit of research.

I don't feel very strongly about the imports or the ">>>", but I do think we need to be consistent.

[kennethshsu]

Another thing is the leading whitespaces or tabs, are they suppose to be "...."?