Contributing

chainladder-python welcomes volunteers for all aspects of the project. Whether you’re new to actuarial reserving, new to python, or both, feedback, questions, suggestions and, of course, contributions are all welcomed.

How Do I Contribute?

There are tons of ways to improve and shape the direction of this project.

  1. Submitting bugs or enhancements to the issue tracker.

  2. Volunteer to draft code changes for existing issues.

  3. Ask questions through the discussion forum.

  4. Improve the documents where they are unclear.

  5. Make new examples.

Why Contribute?

  1. Contributing to an open-source project is an incredibly rewarding learning experience. Whether your interests are in learning python, implementing functionality you need, software development, or gaining a deeper appreciation for how actuarial methods work, you will learn a ton.

  2. Actuarial literature has a history of being free and open source, but we’re barely scratching the surface on reproducible research or a similar level of freedom with regard to tools.

  3. It’s fun.

If you are interested in contributing. Here are a few helpful hints to make the journey enjoyable.

API Guidelines

chainladder-python by design is intended to mimic the API styles of pandas and scikit-learn. This benefits the on-going development of the package as API design is not up for debate which should eliminate many inquiries on how to write new functionality. In general,

  1. the API for any estimator/transformer must strive to follow the scikit-learn estimator API.

  2. Methods for the Triangle classes should generally follow the same name and signature as pandas if it exists, followed by numpy. Methods that are truly domain specific with no equivalency in pandas or numpy should follow PEP8 naming convention.

  3. Triangle methods should never be self-mutating by default. Mutation is allowable with an inplace argument similar to pandas.

Occasionally, there will be cases where domain-specific functionality does not fit neatly into the existing API and these should be discussed in issue.

Setting Up Development Environment

Once you’ve forked the repository, you’ll need a development environment. A conda development environment chainladder including all testing and documentation dependencies can be set up as follows:

conda config --set channel_priority strict
conda env create --file environment-dev.yaml
conda config --set channel_priority false
conda activate cl_dev

Because R’s ChainLadder package is not available through conda, you will need to install this manually in your environment.

R -e "install.packages('ChainLadder', repo='http://cran.rstudio.com')";

Lastly, set up the python chainladder package in development mode.

python setup.py develop

When you are done with development, you should exit cl_dev.

conda deactivate

Updating the Documentation

The documentation is build using jupyter-book. From your cl_dev or cl_docs conda environment, docs can be generated by navigating to the ‘/docs’ folder and running jb build . at the command line. The built site will be available in your _build\html folder.

Editing of the documentation happens in one of four places:

  1. First, the docstrings of the actual library live with the code and get hosted as part of the API reference

  2. The User Guide is written in jupyter notebooks in the ‘/docs/modules’ folder.

  3. The example gallery uses sphinx_gallery, and new examples can be added by simply adding an additional example file to the /examples folder. To show up in the gallery, the file must begin with “plot_” and the gallery thumbnails are auto-generated from the plot output of your example. You may need to install sphinx_gallery and nbsphinx first.

  4. The tutorials are jupyter notebooks stored at ‘docs/tutorials’.

Docs are a great way for newer users to get involved. New user help is especially helpful in clarifying the docs as they are the primary user of the docs.

Pull Requests

Pull requests (PR) should be tied to an issue. It’s generally a good idea to keep issues and pull requests small. Like all projects, the larger the PR, the less likely it will be merged.

All pull requests must pass existing unit tests. On occasion, existing unit tests can be in violation of the API guidelines. These unit tests should be refined to accommodate the API ethos set forth above. It is a good practice to run tests ahead of pushing changes to Github. That said, these unit tests will be run by Github.

pytest chainladder

New functionality should include new unit tests with a reasonable level of code coverage.