API Reference Examples

[genedan]

Latest Status:

Domain	Module	Status
Core Data Structures	Triangle	@EKtheSage
Core Data Structures	minimum	Unassigned
Core Data Structures	maximum	Unassigned
Deterministic Reserving Models	Chainladder	Done ✅
Deterministic Reserving Models	BornhuetterFerguson	Done ✅
Deterministic Reserving Models	Benktander	Done ✅
Deterministic Reserving Models	CapeCod	Done ✅
Deterministic Reserving Models	ExpectedLoss	Done ✅
Development Pattern Estimators	Development	@kennethshsu
Development Pattern Estimators	DevelopmentCorrelation	Unassigned
Development Pattern Estimators	ValuationCorrelation	Unassigned
Development Pattern Estimators	DevelopmentConstant	Unassigned
Development Pattern Estimators	MunichAdjustment	Unassigned
Development Pattern Estimators	IncrementalAdditive	Unassigned
Development Pattern Estimators	ClarkLDF	Unassigned
Development Pattern Estimators	CaseOutstanding	Unassigned
Development Pattern Estimators	TweedieGLM	Unassigned
Development Pattern Estimators	DevelopmentML	Unassigned
Development Pattern Estimators	BarnettZehnwirth	Unassigned
Operational / Trend / Exposure Tools	BerquistSherman	Unassigned
Operational / Trend / Exposure Tools	Trend	Unassigned
Operational / Trend / Exposure Tools	ParallelogramOLF	Done ✅
Stochastic / Simulation	MackChainladder	Unassigned
Stochastic / Simulation	BootstrapODPSample	Unassigned
Tail Factor Models	TailConstant	Done ✅
Tail Factor Models	TailCurve	Unassigned
Tail Factor Models	TailBondy	Unassigned
Tail Factor Models	TailClark	Unassigned
Utility Functions	load_sample	Done ✅
Utility Functions	read_pickle	Unassigned
Utility Functions	read_json	Unassigned
Utility Functions	concat	Unassigned
Workflow / Pipeline Infrastructure	Pipeline	Unassigned
Workflow / Pipeline Infrastructure	VotingChainladder	Unassigned
Workflow / Pipeline Infrastructure	GridSearch	Unassigned
Workflow / Pipeline Infrastructure	PatsyFormula	Unassigned

Template:

    Examples
    --------

    words

    ..  testsetup::

        import chainladder as cl

    ..  testcode::



    ..  testoutput::

Original thread:

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.

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 "...."?