Contributing to lifelib#

lifelib is an open source project and welcomes your contribution. There are various ways to contribute to lifelib:

  • Play around with lifelib and blog about it or post feedbacks on the Discussion page.

  • Ask questions about lifelib on the Issue page. Others may also have the issues you have, and asking for the solutions may help others having the same issues.

  • Give enhancement ideas on the Discussion page.

  • Help improve the documentation of lifelib. Find and report typos, dead links, outdated or unclear descriptions by submitting issues. The lifelib site is generated by Sphinx, a widely used documentation generator, from the makedocs/source directory in the lifelib repository and from the docstrings of models, spaces and cells in lifelib models.

  • Report bugs by submitting issues on the Issue page if you find any.

  • Write examples using lifelib models. See the Writing examples section below for more details.

  • Add a new library to lifelib. See the Adding a new library section below for more details.

Important notes#

Your contribution must be your original work or based on other open-source projects released under any permissive open source licenses. Note that GPL is not a permissive open source license. If your contribution includes code modified from other open source projects, cite the fact appropriately. If sample data accompanies your contribution, check the terms of use of the data and make sure the inclusion of the data does not violate the terms of use.

Writing examples#

You can contribute to lifelib by writing an example using a model in a lifelib library. Before submitting a pull request, open an issue or start a discussion about your work to ask for review.

There are two formats for an example file to be included in a library:

  • Jupyter notebook

  • Python script for sphinx-gallery

You can write an example in Jupyter notebook. The notebook is rendered as part of the lifelib documentation and linked from the library’s page, and also from the Notebooks page. See 1. Simple Stochastic Example for example. This example is written as a Jupyter notebook, named savings_example1.ipynb, and included in the savings library. In case your example uses a custom model modified from the original model included in a lifelib library, the custom model is to be included in the library in addition to the example notebook. In the case of 1. Simple Stochastic Example, a custom model named CashValue_ME_EX1 is included in the savings library for the example.

In stead of, or in addition to an example in Jupyter notebook, you can write a Python script to plot a graph by matplotlib. The script is rendered as part of the lifelib documentation and linked from the library’s page, and also from the Gallery page. To be auto-generated by Sphinx-Gallery, a Sphinx extension for building a gallery of examples, the script’s name must be prepended by plot_. See Account value paths for example. This example is named plot_ex1_av_paths.py, and included in the savings library.

Adding a new library#

A library contains at least one model and its documentation, and tests for the model should also be provided. Creating a new library takes a lot of time and effort, so before staring on building a new library, ask the lifelib community on the Discussion page whether the model you plan to develop deserves a new library. Here are some preferable characteristics desired for libraries.

  • General models without country specific implementations are more preferable than country specific models. In case of country specific models, applicable requirements and standards should be documented.

  • Practical models are more preferable than illustrative models.

  • Names of cells, refs, spaces, models, model folders should follow the same naming convention as the basiclife and savings models.

  • The type of models in a library should not overlap with those in another library. For example, cashflow models of protection and savings products are covered by the basiclife and savings models, so if you wants to develop the cashflow models, consider extending the basiclife and savings models, instead of proposing a brand new library.

Libraries are located in the lifelib/libraries path in the lifelib repository, and their documents are located in makedocs/source/libraries path in the repo.

The docstrings of all the space and the cells in the model should be well-documented.