Clean up docstring argument and return types

Author: kbattocchi

azure-pipelines.yml

@@ -78,6 +78,7 @@ jobs:
         displayName: 'Build documentation'
 
       - publish: 'build/sphinx/html'
+        condition: 'succeededOrFailed()'
         artifact: 'Documentation'
         displayName: 'Publish documentation as artifact'
 

doc/conf.py

@@ -52,7 +52,18 @@
                                bgcolor='"#ffffff"', center='true', style='solid')
 inheritance_node_attrs = dict(shape='ellipse', fontsize=12,
                               fontname="monspace", height=0.75)
+
 napoleon_use_param = False
+# TODO: enable type aliases
+# napoleon_preprocess_types = True  # needed for type aliases to work
+# napoleon_type_aliases = {
+#     "array_like": ":term:`array_like`",
+#     "ndarray": "~numpy.ndarray",
+#     "RandomState": ":class:`~numpy.random.RandomState`",
+#     "DataFrame": ":class:`~pandas.DataFrame`",
+#     "Series": ":class:`~pandas.Series`",
+# }
+
 autosummary_generate = True
 autodoc_default_options = {'members': None,
                            'show-inheritance': None,
@@ -76,7 +87,7 @@
 templates_path = ['_templates']
 
 # The suffix(es) of source filenames.
-# You can specify multiple suffix as a list of string:
+# You can specify multiple suffix as a list of strings:
 #
 # source_suffix = ['.rst', '.md']
 source_suffix = '.rst'
@@ -215,11 +226,12 @@
 
 # Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {'python': ('https://docs.python.org/3', None),
-                       'numpy': ('https://docs.scipy.org/doc/numpy/', None),
+                       'numpy': ('https://numpy.org/doc/stable/', None),
                        'sklearn': ('https://scikit-learn.org/stable/', None),
-                       'matplotlib': ('https://matplotlib.org/', None),
+                       'matplotlib': ('https://matplotlib.org/stable/', None),
                        'shap': ('https://shap.readthedocs.io/en/stable/', None),
-                       'dowhy': ('https://py-why.github.io/dowhy/v0.8/', None)}
+                       'dowhy': ('https://www.pywhy.org/dowhy/v0.8/', None),
+                       'statsmodels': ('https://www.statsmodels.org/stable/', None)}
 
 
 # -- Options for todo extension ----------------------------------------------

doc/spec/api.rst

@@ -97,10 +97,10 @@ The base class of all the methods in our API has the following signature:
             Parameters:
             Y: (n × d_y) matrix of outcomes for each sample
             T: (n × d_t) matrix of treatments for each sample
-            X: optional (n × d_x) matrix of features for each sample
-            W: optional (n × d_w) matrix of controls for each sample
-            Z: optional (n × d_z) matrix of instruments for each sample
-            inference: optional string, `Inference` instance, or None
+            X: (n × d_x) matrix of features for each sample, optional
+            W: (n × d_w) matrix of controls for each sample, optional
+            Z: (n × d_z) matrix of instruments for each sample, optional
+            inference: str or `Inference` instance, optional
                 Method for performing inference.  All estimators support 'bootstrap'
                 (or an instance of `BootstrapInference`), some support other methods as well.
             '''
@@ -112,7 +112,7 @@ The base class of all the methods in our API has the following signature:
             Parameters:
             T0: (m × d_t) matrix of base treatments for each sample
             T1: (m × d_t) matrix of target treatments for each sample
-            X: optional (m × d_x) matrix of features for each sample
+            X:  (m × d_x) matrix of features for each sample, optional
         
             Returns:
             tau: (m × d_y) matrix of heterogeneous treatment effects on each outcome
@@ -125,7 +125,7 @@ The base class of all the methods in our API has the following signature:
         
             Parameters:
             T: (m × d_t) matrix of base treatments for each sample
-            X: optional (m × d_x) matrix of features for each sample
+            X:  (m × d_x) matrix of features for each sample, optional
         
             Returns:
             grad_tau: (m × d_y × d_t) matrix of heterogeneous marginal effects on each outcome
@@ -137,10 +137,10 @@ The base class of all the methods in our API has the following signature:
             Available only when inference is not None, when calling the fit method.
 
             Parameters:
-            X: optional (m, d_x) matrix of features for each sample
-            T0: optional (m, d_t) matrix of base treatments for each sample
-            T1: optional (m, d_t) matrix of target treatments for each sample
-            alpha: optional float in [0, 1] of the (1-alpha) level of confidence
+            X:  (m, d_x) matrix of features for each sample, optional
+            T0: (m, d_t) matrix of base treatments for each sample, optional
+            T1: (m, d_t) matrix of target treatments for each sample, optional
+            alpha: float in [0, 1] of the (1-alpha) level of confidence, optional
 
             Returns:
             lower, upper : tuple of the lower and the upper bounds of the confidence interval 
@@ -153,8 +153,8 @@ The base class of all the methods in our API has the following signature:
 
             Parameters:
             T: (m, d_t) matrix of base treatments for each sample
-            X: optional (m, d_x) matrix of features for each sample
-            alpha: optional float in [0, 1] of the (1-alpha) level of confidence
+            X: (m, d_x) matrix of features for each sample, optional
+            alpha: float in [0, 1] of the (1-alpha) level of confidence, optional
 
             Returns:
             lower, upper : tuple of the lower and the upper bounds of the confidence interval 
@@ -236,7 +236,7 @@ and constant marginal CATE interval at any target feature vector :math:`\vec{x}`
             features on a set of m test samples {X_i}
         
             Parameters:
-            X: optional (m × d_x) matrix of features for each sample
+            X: (m × d_x) matrix of features for each sample, optional
         
             Returns:
             theta: (m × d_y × d_f_t) matrix of constant marginal CATE of each treatment on each outcome	
@@ -249,8 +249,8 @@ and constant marginal CATE interval at any target feature vector :math:`\vec{x}`
             Available only when inference is not None, when calling the fit method.
 
             Parameters:
-            X: optional (m, d_x) matrix of features for each sample
-            alpha: optional float in [0, 1] of the (1-alpha) level of confidence
+            X: (m, d_x) matrix of features for each sample, optional
+            alpha: float in [0, 1] of the (1-alpha) level of confidence, optional
 
             Returns:
             lower, upper : tuple of the lower and the upper bounds of the confidence interval 

doc/spec/estimation/dml.rst

@@ -331,7 +331,7 @@ Usage FAQs
     potential approach one could take is simply run a big linear regression, regressing :math:`Y` on
     :math:`T, X, W` and then looking at the coefficient associated with the :math:`T` variable and
     the corresponding confidence interval (e.g. using statistical packages like
-    :class:`~statsmodels.api.OLS`). However, this will not work if:
+    :class:`~statsmodels.regression.linear_model.OLS`). However, this will not work if:
 
         1) The number of control variables :math:`X, W` that you have is large and comparable
         to the number of samples. This could for instance arise if one wants to control for