marginaleffects 0.3.2__tar.gz → 0.4.0__tar.gz

{marginaleffects-0.3.2 → marginaleffects-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: marginaleffects
-Version: 0.3.2
+Version: 0.4.0
 Summary: Predictions, counterfactual comparisons, slopes, and hypothesis tests for statistical models.
 License-Expression: GPL-3.0-or-later
 Requires-Python: >=3.10

{marginaleffects-0.3.2 → marginaleffects-0.4.0}/marginaleffects/comparisons.py

@@ -20,11 +20,7 @@ from .utils import (
     call_avg,
 )
 from ._input_utils import prepare_base_inputs
-from .docs import (
-    DocsDetails,
-    DocsParameters,
-    docstring_returns,
-)
+from .docs import doc
 
 
 def _cross_postprocess(cross):
@@ -319,6 +315,99 @@ def _collect_comparison_functions(variables):
     return comparison_functions
 
 
+@doc("""
+
+# `comparisons()`
+
+`comparisons()` and `avg_comparisons()` are functions for predicting the outcome variable at different regressor values and comparing those predictions by computing a difference, ratio, or some other function. These functions can return many quantities of interest, such as contrasts, differences, risk ratios, changes in log odds, lift, slopes, elasticities, average treatment effect (on the treated or untreated), etc.
+
+- `comparisons()`: unit-level (conditional) estimates.
+- `avg_comparisons()`: average (marginal) estimates.
+
+See the package website and vignette for examples:
+
+- https://marginaleffects.com/chapters/comparisons.html
+- https://marginaleffects.com
+
+## Parameters
+
+{param_model}
+
+{param_variables_comparison}
+
+{param_newdata_comparison}
+
+- `comparison`: (str or callable) String specifying how pairs of predictions should be compared, or a callable function to compute custom estimates. See the Comparisons section below for definitions of each transformation.
+    - Acceptable strings: difference, differenceavg, differenceavgwts, dydx, eyex, eydx, dyex, dydxavg, eyexavg, eydxavg, dyexavg, dydxavgwts, eyexavgwts, eydxavgwts, dyexavgwts, ratio, ratioavg, ratioavgwts, lnratio, lnratioavg, lnratioavgwts, lnor, lnoravg, lnoravgwts, lift, liftavg, liftavg, expdydx, expdydxavg, expdydxavgwts
+    - Callable: A function that accepts any subset of the named arguments `hi`, `lo`, `eps`, `x`, `y`, and `w`, and returns a numeric value or array. For example: `lambda hi, lo: hi / lo` for ratios, `lambda hi, lo: (hi - lo) / lo * 100` for percent changes, or a named function like `def lnor(hi, lo): return np.log((hi.mean() / (1 - hi.mean())) / (lo.mean() / (1 - lo.mean())))`.
+
+{param_by}
+
+{param_transform}
+
+{param_hypothesis}
+
+{param_wts}
+
+{param_vcov}
+
+{param_equivalence}
+
+{param_cross}
+
+{param_conf_level}
+
+{param_eps}
+
+{param_eps_vcov}
+
+{returns}
+
+## Examples
+```py
+from marginaleffects import *
+import numpy as np
+
+import statsmodels.api as sm
+import statsmodels.formula.api as smf
+data = get_dataset("thornton")
+model = smf.ols("outcome ~ distance + incentive", data=data).fit()
+
+# Basic comparisons
+comparisons(model)
+
+avg_comparisons(model)
+
+comparisons(model, hypothesis=0)
+
+avg_comparisons(model, hypothesis=0)
+
+comparisons(model, by="agecat")
+
+avg_comparisons(model, by="agecat")
+
+# Custom comparisons with functions
+# Ratio comparison using lambda
+comparisons(model, variables="distance",
+            comparison=lambda hi, lo: hi / lo)
+
+# Percent change using lambda
+comparisons(model, variables="distance",
+            comparison=lambda hi, lo: (hi - lo) / lo * 100)
+
+# Custom function with flexible signature
+def lnor(hi, lo):
+    hi = np.asarray(hi)
+    lo = np.asarray(lo)
+    return np.log((hi.mean() / (1 - hi.mean())) / (lo.mean() / (1 - lo.mean())))
+
+comparisons(model, variables="distance", comparison=lnor)
+```
+
+## Details
+{details_tost}
+
+{details_order_of_operations}""")
 def comparisons(
     model,
     variables=None,
@@ -336,13 +425,6 @@ def comparisons(
     eps_vcov=None,
     **kwargs,
 ):
-    """
-    `comparisons()` and `avg_comparisons()` are functions for predicting the outcome variable at different regressor values and comparing those predictions by computing a difference, ratio, or some other function. These functions can return many quantities of interest, such as contrasts, differences, risk ratios, changes in log odds, lift, slopes, elasticities, average treatment effect (on the treated or untreated), etc.
-
-    For more information, visit the website: https://marginaleffects.com/
-
-    Or type: `help(comparisons)`
-    """
     hypothesis = handle_deprecated_hypotheses_argument(hypothesis, kwargs, stacklevel=2)
     if kwargs:
         unexpected = ", ".join(sorted(kwargs.keys()))
@@ -620,13 +702,6 @@ def avg_comparisons(
     eps=1e-4,
     **kwargs,
 ):
-    """
-    `comparisons()` and `avg_comparisons()` are functions for predicting the outcome variable at different regressor values and comparing those predictions by computing a difference, ratio, or some other function. These functions can return many quantities of interest, such as contrasts, differences, risk ratios, changes in log odds, lift, slopes, elasticities, average treatment effect (on the treated or untreated), etc.
-
-    For more information, visit the website: https://marginaleffects.com/
-
-    Or type: `help(avg_comparisons)`
-    """
     return call_avg(
         comparisons,
         model=model,
@@ -646,90 +721,4 @@ def avg_comparisons(
     )
 
 
-docs_comparisons = (
-    """
-
-# `comparisons()`
-
-`comparisons()` and `avg_comparisons()` are functions for predicting the outcome variable at different regressor values and comparing those predictions by computing a difference, ratio, or some other function. These functions can return many quantities of interest, such as contrasts, differences, risk ratios, changes in log odds, lift, slopes, elasticities, average treatment effect (on the treated or untreated), etc.
-
-* `comparisons()`: unit-level (conditional) estimates.
-* `avg_comparisons()`: average (marginal) estimates.
-
-See the package website and vignette for examples:
-
-* https://marginaleffects.com/chapters/comparisons.html
-* https://marginaleffects.com
-
-## Parameters
-"""
-    + DocsParameters.docstring_model
-    + DocsParameters.docstring_variables("comparison")
-    + DocsParameters.docstring_newdata("comparison")
-    + """
-* `comparison`: (str or callable) String specifying how pairs of predictions should be compared, or a callable function to compute custom estimates. See the Comparisons section below for definitions of each transformation.
-
-  * Acceptable strings: difference, differenceavg, differenceavgwts, dydx, eyex, eydx, dyex, dydxavg, eyexavg, eydxavg, dyexavg, dydxavgwts, eyexavgwts, eydxavgwts, dyexavgwts, ratio, ratioavg, ratioavgwts, lnratio, lnratioavg, lnratioavgwts, lnor, lnoravg, lnoravgwts, lift, liftavg, liftavg, expdydx, expdydxavg, expdydxavgwts
-
-  * Callable: A function that takes `hi`, `lo`, `eps`, `x`, `y`, and `w` as arguments and returns a numeric array. This allows computing custom comparisons like `lambda hi, lo, eps, x, y, w: hi / lo` for ratios or `lambda hi, lo, eps, x, y, w: (hi - lo) / lo * 100` for percent changes.
-"""
-    + DocsParameters.docstring_by
-    + DocsParameters.docstring_transform
-    + DocsParameters.docstring_hypothesis
-    + DocsParameters.docstring_wts
-    + DocsParameters.docstring_vcov
-    + DocsParameters.docstring_equivalence
-    + DocsParameters.docstring_cross
-    + DocsParameters.docstring_conf_level
-    + DocsParameters.docstring_eps
-    + DocsParameters.docstring_eps_vcov
-    + docstring_returns
-    + """
-## Examples
-```py
-from marginaleffects import *
-import numpy as np
-
-import statsmodels.api as sm
-import statsmodels.formula.api as smf
-data = get_dataset("thornton")
-model = smf.ols("outcome ~ distance + incentive", data=data).fit()
-
-# Basic comparisons
-comparisons(model)
-
-avg_comparisons(model)
-
-comparisons(model, hypothesis=0)
-
-avg_comparisons(model, hypothesis=0)
-
-comparisons(model, by="agecat")
-
-avg_comparisons(model, by="agecat")
-
-# Custom comparisons with lambda functions
-# Ratio comparison using lambda
-comparisons(model, variables="distance",
-            comparison=lambda hi, lo, eps, x, y, w: hi / lo)
-
-# Percent change using lambda
-comparisons(model, variables="distance",
-            comparison=lambda hi, lo, eps, x, y, w: (hi - lo) / lo * 100)
-
-# Log ratio using lambda
-comparisons(model, variables="distance",
-            comparison=lambda hi, lo, eps, x, y, w: np.log(hi / lo))
-```
-
-## Details
-"""
-    + DocsDetails.docstring_tost
-    + DocsDetails.docstring_order_of_operations
-    + ""  # add comparisons argument functions section as in R at https://marginaleffects.com/man/r/comparisons.html
-)
-
-
-comparisons.__doc__ = docs_comparisons
-
 avg_comparisons.__doc__ = comparisons.__doc__

{marginaleffects-0.3.2 → marginaleffects-0.4.0}/marginaleffects/datagrid.py

@@ -25,11 +25,58 @@ def datagrid(
     **kwargs,
 ):
     """
+    # `datagrid()`
+
     Generate a data grid of user-specified values for use in the 'newdata' argument of the 'predictions()', 'comparisons()', and 'slopes()' functions.
 
-    For more information, visit the website: https://marginaleffects.com/
+    This is useful to define where in the predictor space we want to evaluate the quantities of interest. Ex: the predicted outcome or slope for a 37 year old college graduate.
+
+    ## Parameters
+    * model: (object, optional)
+        Model object.
+        * (one and only one of the `model` and `newdata` arguments can be used.)
+    * newdata: (DataFrame, optional)
+        Data frame used to define the predictor space.
+        * (one and only one of the `model` and `newdata` arguments can be used.)
+    * grid_type: (str, optional)
+        Determines the functions to apply to each variable. The defaults can be overridden by defining individual variables explicitly in the `**kwargs`, or by supplying a function to one of the `FUN_*` arguments.
+        * "mean_or_mode": Character, factor, logical, and binary variables are set to their modes. Numeric, integer, and other variables are set to their means.
+        * "balanced": Each unique level of character, factor, logical, and binary variables are preserved. Numeric, integer, and other variables are set to their means. Warning: When there are many variables and many levels per variable, a balanced grid can be very large. In those cases, it is better to use `grid_type="mean_or_mode"` and to specify the unique levels of a subset of named variables explicitly.
+        * "counterfactual": the entire dataset is duplicated for each combination of the variable values specified in `**kwargs`. Variables not explicitly supplied to `datagrid()` are set to their observed values in the original dataset.
+    * FUN_numeric: (Callable, optional)
+        The function to be applied to numeric variables.
+    * FUN_other: (Callable, optional)
+        The function to be applied to other variable types.
+    * **kwargs
+        * Named arguments where the name is the variable name and the value is a list of values to use in the grid. If a variable is not specified, it is set to its mean or mode depending on the `grid_type` argument.
+
+    ## Returns
+    (polars.DataFrame)
+    * DataFrame where each row corresponds to one combination of the named predictors supplied by the user. Variables which are not explicitly defined are held at their mean or mode.
 
-    Or type: `help(datagrid)`
+    ## Examples
+    ```py
+    import polars as pl
+    import statsmodels.formula.api as smf
+    from marginaleffects import *
+    data = get_dataset("thornton")
+
+    # The output only has 2 rows, and all the variables except `hp` are at their mean or mode.
+    datagrid(newdata = data, village = [43, 11])
+
+    # We get the same result by feeding a model instead of a DataFrame
+    mod = smf.ols("outcome ~ incentive + distance", data).fit()
+    datagrid(model = mod, village = [43, 11])
+
+    # Use in `marginaleffects` to compute "Typical Marginal Effects". When used in `slopes()` or `predictions()` we do not need to specify the `model` or `newdata` arguments.
+    nd = datagrid(mod, village = [43, 11])
+    slopes(mod, newdata = nd)
+
+    # The full dataset is duplicated with each observation given counterfactual values of 43 and 11 for the `village` variable.
+    # The original `thornton` includes 2884 rows, so the resulting dataset includes 5768 rows.
+    dg = datagrid(newdata = data, village = [43, 11], grid_type = "counterfactual")
+    dg.shape
+    ```
     """
 
     # allow predictions() to pass `model` argument automatically
@@ -495,59 +542,3 @@ def _datagridcf(model=None, newdata=None, by=None, **kwargs):
     result.datagrid_explicit = list(kwargs.keys())
 
     return result
-
-
-datagrid.__doc__ = """
-    # `datagrid()`
-
-    Generate a data grid of user-specified values for use in the 'newdata' argument of the 'predictions()', 'comparisons()', and 'slopes()' functions.
-
-    This is useful to define where in the predictor space we want to evaluate the quantities of interest. Ex: the predicted outcome or slope for a 37 year old college graduate.
-
-    ## Parameters
-    * model: (object, optional)
-        Model object.
-        * (one and only one of the `model` and `newdata` arguments can be used.)
-    * newdata: (DataFrame, optional)
-        Data frame used to define the predictor space.
-        * (one and only one of the `model` and `newdata` arguments can be used.)
-    * grid_type: (str, optional)
-        Determines the functions to apply to each variable. The defaults can be overridden by defining individual variables explicitly in the `**kwargs`, or by supplying a function to one of the `FUN_*` arguments.
-        * "mean_or_mode": Character, factor, logical, and binary variables are set to their modes. Numeric, integer, and other variables are set to their means.
-        * "balanced": Each unique level of character, factor, logical, and binary variables are preserved. Numeric, integer, and other variables are set to their means. Warning: When there are many variables and many levels per variable, a balanced grid can be very large. In those cases, it is better to use `grid_type="mean_or_mode"` and to specify the unique levels of a subset of named variables explicitly.
-        * "counterfactual": the entire dataset is duplicated for each combination of the variable values specified in `**kwargs`. Variables not explicitly supplied to `datagrid()` are set to their observed values in the original dataset.
-    * FUN_numeric: (Callable, optional)
-        The function to be applied to numeric variables.
-    * FUN_other: (Callable, optional)
-        The function to be applied to other variable types.
-    * **kwargs
-        * Named arguments where the name is the variable name and the value is a list of values to use in the grid. If a variable is not specified, it is set to its mean or mode depending on the `grid_type` argument.
-
-    ## Returns
-    (polars.DataFrame)
-    * DataFrame where each row corresponds to one combination of the named predictors supplied by the user. Variables which are not explicitly defined are held at their mean or mode.
-
-    ## Examples
-    ```py
-    import polars as pl
-    import statsmodels.formula.api as smf
-    from marginaleffects import *
-    data = get_dataset("thornton")
-
-    # The output only has 2 rows, and all the variables except `hp` are at their mean or mode.
-    datagrid(newdata = data, village = [43, 11])
-
-    # We get the same result by feeding a model instead of a DataFrame
-    mod = smf.ols("outcome ~ incentive + distance", data).fit()
-    datagrid(model = mod, village = [43, 11])
-
-    # Use in `marginaleffects` to compute "Typical Marginal Effects". When used in `slopes()` or `predictions()` we do not need to specify the `model` or `newdata` arguments.
-    nd = datagrid(mod, village = [43, 11])
-    slopes(mod, newdata = nd)
-
-    # The full dataset is duplicated with each observation given counterfactual values of 43 and 11 for the `village` variable. 
-    # The original `thornton` includes 2884 rows, so the resulting dataset includes 5768 rows.
-    dg = datagrid(newdata = data, village = [43, 11], grid_type = "counterfactual")
-    dg.shape
-    ```
-    """