Skip to content

DOC: Make the option docstrings consistent across iv, panel, system a… - #834

Merged
bashtage merged 2 commits into
mainfrom
lm71-ds4-docstring-consistency
Oct 14, 2026
Merged

bashtage merged 2 commits into
mainfrom
lm71-ds4-docstring-consistency

Conversation

@bashtage

Copy link
Copy Markdown
Owner

…nd asset pricing

Docstrings only. With the docstrings removed, the code is identical to the base.

The three docstring sweeps of the areas were done independently and left the
documentation of the options with fixed values in different layouts. This makes
them one set.

Options with fixed values

  • Short lists stay in the type line with braces, {"a", "b"}, with plain quoted
    values. Long lists, where the brace line would be longer than the 99 columns
    of flake8, use "str, optional" and list every accepted name, aliases included,
    in the description as bullets. A name comes first, then its aliases, in the
    same order everywhere: the kernels are "bartlett", "newey-west"; "parzen",
    "gallant"; "qs", "quadratic-spectral", "andrews".
  • The lists of the kernels, of cov_type and of weight_type now have one layout
    in iv, panel, system and asset_pricing. Lists that were in Notes
    (KernelWeightMatrix, DriscollKraay, ACCovariance) or in prose (the panel fit
    methods, FamaMacBeth, the Kleibergen-Paap functions) are in the description of
    the parameter. FamaMacBeth.fit and the asset pricing fit methods use braces,
    because their lists fit on a line.
  • Every option is shown in lower case, including the names of the classes that
    cov_type accepts ("homoskedasticcovariance", "kernelcovariance", ...).
  • Each option with named values says "The names are not case sensitive.": cov_type,
    weight_type, kernel, method, group and precision, and the kernel of the
    cov_config and weight_config. dummy_matrix is case sensitive and does not.
    Every name in the lists was checked against the code, in lower, upper and title case.

extra_df

  • The fit of IV2SLS and IVLIML accepts the key extra_df in cov_config and passes
    it to the covariance estimator, which scales by n / (n - k - extra_df) if
    debiased is True. It is documented now.
  • AbsorbingLS.fit accepts it too, but replaces it with the number of absorbed
    effects if debiased is True and does not use it otherwise, so it is not
    documented as an option there.

Raises

  • The ten fit methods that had a second ValueError entry for a key of cov_config
    that the covariance estimator does not accept (IV2SLS and IVLIML, IVGMM,
    IVGMMCUE, IVJIVE, AbsorbingLS, SUR and IV3SLS, IVSystemGMM, TradedFactorModel,
    LinearFactorModel and LinearFactorModelGMM) have one ValueError entry that
    lists all the conditions, as the panel fit methods do.

…nd asset pricing

Docstrings only. With the docstrings removed, the code is identical to the base.

The three docstring sweeps of the areas were done independently and left the
documentation of the options with fixed values in different layouts. This makes
them one set.

Options with fixed values
- Short lists stay in the type line with braces, {"a", "b"}, with plain quoted
  values. Long lists, where the brace line would be longer than the 99 columns
  of flake8, use "str, optional" and list every accepted name, aliases included,
  in the description as bullets. A name comes first, then its aliases, in the
  same order everywhere: the kernels are "bartlett", "newey-west"; "parzen",
  "gallant"; "qs", "quadratic-spectral", "andrews".
- The lists of the kernels, of cov_type and of weight_type now have one layout
  in iv, panel, system and asset_pricing. Lists that were in Notes
  (KernelWeightMatrix, DriscollKraay, ACCovariance) or in prose (the panel fit
  methods, FamaMacBeth, the Kleibergen-Paap functions) are in the description of
  the parameter. FamaMacBeth.fit and the asset pricing fit methods use braces,
  because their lists fit on a line.
- Every option is shown in lower case, including the names of the classes that
  cov_type accepts ("homoskedasticcovariance", "kernelcovariance", ...).
- Each option with named values says "The names are not case sensitive.": cov_type,
  weight_type, kernel, method, group and precision, and the kernel of the
  cov_config and weight_config. dummy_matrix is case sensitive and does not.
  Every name in the lists was checked against the code, in lower, upper and title case.

extra_df
- The fit of IV2SLS and IVLIML accepts the key extra_df in cov_config and passes
  it to the covariance estimator, which scales by n / (n - k - extra_df) if
  debiased is True. It is documented now.
- AbsorbingLS.fit accepts it too, but replaces it with the number of absorbed
  effects if debiased is True and does not use it otherwise, so it is not
  documented as an option there.

Raises
- The ten fit methods that had a second ValueError entry for a key of cov_config
  that the covariance estimator does not accept (IV2SLS and IVLIML, IVGMM,
  IVGMMCUE, IVJIVE, AbsorbingLS, SUR and IV3SLS, IVSystemGMM, TradedFactorModel,
  LinearFactorModel and LinearFactorModelGMM) have one ValueError entry that
  lists all the conditions, as the panel fit methods do.
The cov_config of IV2SLS, IVLIML and AbsorbingLS mentioned that a center key
is accepted and ignored, but not kappa, which fit replaces with the kappa of
the model, nor extra_df in AbsorbingLS, which fit replaces with the degrees
of freedom of the absorbed effects. The error for a key that is not accepted
lists all three, so the docstrings now say what happens to each.
@bashtage
bashtage merged commit 249845c into main Oct 14, 2026
9 of 10 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant