Merge pull request #27 from sdfordham/improve-docs

Improve docs

doc/source/augsynth.rst

@@ -2,28 +2,38 @@
 Augmented Synthetic Control Method
 ==================================
 
-The augmented synthetic control method is due to
-`Ben-Michael, Feller & Rothstein <http://doi.org/10.3386/w28885>`_.
-This method constructs a vector of weights :math:`w_ = (w_1, w_2, \dots, w_k)`
+The *Augmented Synthetic Control Method* is due to
+`Ben-Michael, Feller & Rothstein <http://doi.org/10.3386/w28885>`_ and adapts
+the :doc:`Synthetic Control Method <synth>` in an
+effort to adjust for poor pre-treatment fit.
+
+The authors do this by adjusting the Synthetic Control Method estimate by adding
+a term that is an imbalance in a particular function of the pre-treatment outcomes.
+In the *Ridge Augmented Synthetic Control Method* this function is
+linear in the pre-treatment outcomes and fit by ridge regression of the control
+post-treatment outcomes against pre-treatment outcomes.
+
+In particular, the method constructs a vector of weights :math:`w = (w_1, w_2, \dots, w_k)`
 such that
 
 .. math::
    w = w_\mathrm{scm} + w_\mathrm{aug},
 
 where :math:`w_\mathrm{scm}` are the weights obtained from the standard
-synthetic control method and :math:`w_\mathrm{aug}` are augmentations that are
-included when the treated unit lies outside the convex hull defined by the
-control units. The weights may be negative and larger than 1, the degree of
-extrapolation is controlled by the ridge parameter :math:`\lambda`.
+:doc:`Synthetic Control Method <synth>` and :math:`w_\mathrm{aug}` are
+augmentations that are included when the treated unit lies outside the
+convex hull defined by the control units. The weights may be negative and
+larger than 1, the degree of extrapolation is controlled by a ridge
+parameter :math:`\lambda`.
 
 In general, this method will obtain weights at least as good as the synthetic
 control method in terms of pre-treatment fit.
 
 The :class:`AugSynth` class
 ***************************
 
-The :class:`AugSynth <pysyncon.AugSynth>` class implements the augmented synthetic
-control method. The expected way to use the class is to first create a
+The :class:`AugSynth <pysyncon.AugSynth>` class implements the Ridge Augmented
+Synthetic Control Method. The expected way to use the class is to first create a
 :class:`Dataprep <pysyncon.Dataprep>` object that defines the study data and
 then use it as input to a :class:`AugSynth <pysyncon.Synth>` object. See the
 `examples folder <https://github.com/sdfordham/pysyncon/tree/main/examples>`_

doc/source/dataprep.rst

@@ -13,8 +13,7 @@ the label denoting the treated unit, the time period to carry out the optimisati
 procedure over and the time period to apply the statistical operation to the
 predictors. See below for further details about each individual argument, and also see
 the `examples folder <https://github.com/sdfordham/pysyncon/tree/main/examples>`_
-of the repository to see how this class is set up in the context of three real
-research contexts.
+of the repository to see how this class is set up in three real research contexts.
 
 The principal difference between the function signature here and the one in
 the ``R`` ``synth`` package is that whereas there are two arguments `unit.variable`

doc/source/penalized.rst

@@ -2,10 +2,12 @@ Penalized Synthetic Control Method
 ==================================
 
 The penalized synthetic control method is due to
-`Abadie & L'Hour <https://www.jmlr.org/papers/volume19/17-777/17-777.pdf>`_.
+`Abadie & L'Hour <https://economics.mit.edu/sites/default/files/publications/A%20Penalized%20Synthetic%20Control%20Estimator%20for%20Disagg.pdf>`_.
 
-This version of the synthetic control adds a penalization term to the loss
-function that has the effect of serving to reduce the interpolation bias.
+This version of the synthetic control method adds a penalization term to the loss
+function that has the effect of serving to reduce the interpolation bias. It does this
+by penalizing pairwise discrepancies in any unit contributing to the synthetic control
+and the treated unit.
 
 The :class:`PenalizedSynth` class
 *********************************
@@ -19,4 +21,4 @@ of the repository for examples illustrating usage.
 
 .. autoclass:: pysyncon.PenalizedSynth
    :members:
-   :inherited-members:
+   :inherited-members:

doc/source/robust.rst

@@ -1,11 +1,15 @@
 Robust Synthetic Control Method
 ===============================
 
-The robust synthetic control method is due to
+The Robust Synthetic Control Method is due to
 `Amjad, Shah & Shen <https://www.jmlr.org/papers/volume19/17-777/17-777.pdf>`_.
 
-This method denoises the data matrix of the control units by
-applying a threshold to the singular values of the matrix.
+This method de-noises the data matrix of the control units by
+applying a threshold to the singular values of the observation matrix
+and then fits a linear model using ridge regression of the de-noised control
+post-treatment outcomes against pre-treatment outcomes. Similarly to the
+:doc:`Ridge Agumented Synthetic Control Method <augsynth>` the weights here
+may be negative or larger than 1.
 
 The :class:`RobustSynth` class
 ******************************
@@ -19,4 +23,4 @@ of the repository for examples illustrating usage.
 
 .. autoclass:: pysyncon.RobustSynth
    :members:
-   :inherited-members:
+   :inherited-members:

doc/source/synth.rst

@@ -1,9 +1,20 @@
 Synthetic Control Method
 ========================
 
+Overview
+********
+
 The synthetic control method is due to
 `Abadie, Diamond & Hainmueller <http://dx.doi.org/10.1198/jasa.2009.ap08746>`_.
-This method constructs a vector of non-negative weights
+This method constructs a weighted combination of the control units that
+most resembles the selected characteristics of the treated unit in a time period
+prior to the treatment time. This so-constructed "synthetic control unit" can then be
+compared with the treated unit to investigate the causal effect of the treatment.
+
+Details
+*******
+
+In particular, this method constructs a vector of non-negative weights
 :math:`w = (w_1, w_2, \dots, w_k)` whose sum is 1 and :math:`k` is the number
 of control units that minimizes
 

pysyncon/dataprep.py

@@ -20,37 +20,39 @@ class Dataprep:
     Parameters
     ----------
     foo : pandas.DataFrame
-        Panel data where the columns are predictor/outcome variables and
-        each row is a time-step for some unit
+        A pandas DataFrame containing the panel data where the columns are
+        predictor/outcome variables and each row is a time-step for some unit
     predictors : Axes
-        Columns of ``foo`` to use as predictors
+        The columns of ``foo`` to use as predictors
     predictors_op : "mean" | "std" | "median"
-        The statistical operation to use on the predictors
+        The statistical operation to use on the predictors - the time range that
+        the operation is applied to is ``time_predictors_prior``
     dependent : Any
-        Column of ``foo`` to use as the dependent variable.
+        The column of ``foo`` to use as the dependent variable
     unit_variable : Any
-        Column of ``foo`` that gives the unit labels
+        The column of ``foo`` that contains the unit labels
     time_variable : Any
-        Column of ``foo`` that gives the time variable
+        The column of ``foo`` that contains the time period
     treatment_identifier : Any
-        The unit label indicating the treated unit
+        The unit label that denotes the treated unit
     controls_identifier : Iterable
-        The unit labels indicating the control units
-    time_predictors_prior : Iterable | pandas.Series | dict
-        The time range over which to average the predictors
-    time_optimize_ssr : Iterable | pandas.Series | dict
+        The unit labels denoting the control units
+    time_predictors_prior : Iterable
+        The time range over which to apply the statistical operation to the
+        predictors (see ``predictors_op`` argument)
+    time_optimize_ssr : Iterable
         The time range over which the loss function should be minimised
     special_predictors : Iterable[SpecialPredictor_t], optional
         An iterable of special predictors which are additional predictors
-        that should be averaged over a custom time period and using a possibly
-        different statistical operator. In particular a special operator
+        that should be averaged over a custom time period and an indicated
+        statistical operator. In particular, a special predictor
         consists of a triple of:
 
-            - column: the column of ``foo`` to use,
-            - time-range: the time range to apply the operator over, should
+            - ``column``: the column of ``foo`` containing the predictor to use,
+            - ``time-range``: the time range to apply ``operator`` over - it should
               have the same type as ``time_predictors_prior`` or ``time_optimize_ssr``
-            - operator: the operator to apply, should be the same type as
-              ``predictors_op``
+            - ``operator``: the statistical operator to apply to ``column`` - it should
+              have the same type as ``predictors_op``
 
         by default None