Practices when porting over variable names from papers

[genedan]

I ran into this issue when trying to do a Ruff fix on core/correlation.py:

# I is the number of development periods in the triangle
I = len(triangle.development)

The variable name needed to be changed because it was capitalized. Yet it can't just be "i" because it clashes with the indexing variable in the paper's various summations:

I've changed "I" to n_dev_periods, and changed the comment to say that this is the same as the capital I from the paper. This made me wonder whether we should have some guidelines in our docs on how to port over variables and formulae.

I'm thinking we should retain variable names when we can, but when we can't we should make sure to document in a comment which variable in the paper the new name refers to (A previous comment also refers to formula G4):

# n_dev_periods is the number of development periods in the triangle ("I" in the Mack 97).
n_dev_periods = len(triangle.development)

[genedan]

I'm probably going to add rule N806 soon since it's a PEP-8 convention. The big Python packages do have exceptions though (scikit-learn being the most obvious one with capital X). When we run into these cases, I believe API parity should take precedence, so we can bypass Ruff in these cases with # noqa and a simple explanation.

Another case where it makes sense to depart from PEP-8 is when doing matrix operations (which scipy does) as this would match mathematical notation found in textbooks.

So I would propose that we follow PEP-8 when naming variables, with the following exceptions:

• API parity with pandas, scikit-learn, etc.
• When matching mathematical variable names in papers
• When doing matrix operations

Tagging @casact/chainladder-maintainers to see if anyone has anything to say about the subject. One question I have is what about fitted estimator attributes that might not have a consistent naming convention between papers? Particularly something like credibility, Z. Most papers I see use a capital Z, so something like model.Z_ would match most papers, but it might not match all of them. Do we go with upper or lowercase?

[henrydingliu]

just add it here.