CDCgov / CDCgov/PyRenew

Document convention of preferring named arguments even for mandatory (positional) args

Open
#298 2 comments 1 reaction 1 assignee View on GitHub

@O957 is already working on this.

Since Sep 13, 2024.

discussion documentation
Dominant language
Python
Stars
29
Forks
9
Avg merge
9d 9h
Merged PRs (30d)
8

Description

Given the variety of backgrounds and experiences present across CFA and the fact that CFA members seem, at present time, to constitute most of MSRs early users, I suggest we explicitly write out the argument names for positional arguments.

Pro: The argument names provide useful information to new users of MSR, Python, and certain Python package (e.g., numpyro).

Con: Blurs the lines between required and optional arguments, as now all previously positional arguments are presented as keyword arguments.

Con: More writing for MSR developers.

Examples

I0 = InfectionInitializationProcess(
    "I0_initialization",
    DistributionalRV(dist=dist.LogNormal(2.5, 1), name="I0"),
    InitializeInfectionsZeroPad(pmf_array.size),
    t_unit=1,
)

...would change to

I0 = InfectionInitializationProcess(
    name="I0_initialization",
    I_pre_seed_rv=DistributionalRV(
        dist=dist.LogNormal(loc=2.5, scale=1), name="I0"),
    infection_seed_method=InitializeInfectionsZeroPad(
        n_timepoints=pmf_array.size),
    t_unit=1,
)

Further thoughts are welcome. I do not feel particularly strongly about this, I just believe it might help clarify things to people in the tutorials somewhat.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.