pysyncon

https://sdfordham.github.io/pysyncon/
Admin
pysyncon is a Python package providing methods for synthetic control analysis, including the...
Tokens:17,921
Snippets:127
Trust Score:9.7
Update:5 months ago
Show doc for...
Tokens:
Raw
### Dataprep Class Initialization

Source: https://sdfordham.github.io/pysyncon/dataprep.html

Initializes the Dataprep class with panel data and study setup parameters.

```APIDOC
## Dataprep Class

### Description
This class defines all the information necessary for the synthetic control study. It takes in as argument a pandas.DataFrame foo containing the panel data, a list of predictors, special predictors, the statistical operation to apply to the predictors over the selected time frame, the dependant variable, the columns denoting the unit labels, the label denoting the control units, the label denoting the treated unit, the time period to carry out the optimisation procedure over and the time period to apply the statistical operation to the predictors.

### Parameters
* **foo** (_pandas.DataFrame_) – 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_) – The columns of `foo` to use as predictors
* **predictors_op** (_"mean"__|__"std"__|__"median"__|__"sum"__|__"count"__|__"max"__|__"min"__|__"var"_) – The statistical operation to use on the predictors - the time range that the operation is applied to is `time_predictors_prior`
* **dependent** (_Any_) – The column of `foo` to use as the dependent variable
* **unit_variable** (_Any_) – The column of `foo` that contains the unit labels
* **time_variable** (_Any_) – The column of `foo` that contains the time period
* **treatment_identifier** (_Any_) – The unit label that denotes the treated unit
* **controls_identifier** (_Iterable_) – 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] | None, optional) – An iterable of special predictors which are additional predictors 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`, `time-range`, and `operator`.

### Raises
* **TypeError** – if `foo` is not of type `pandas.DataFrame`
* **ValueError** – if `predictor` is not a column of `foo`
* **ValueError** – if `predictor_op` is not one of “mean”, “std”, “median”, “sum”, “count”, “max”, “min” or “var”.
* **ValueError** – if `dependent` is not a column of `foo`
* **ValueError** – if `unit_variable` is not a column of `foo`
* **ValueError** – if `time_variable` is not a column of `foo`
* **ValueError** – if `treatment_identifier` is not present in `foo['unit_variable']`
* **TypeError** – if `controls_identifier` is not of type `Iterable`
* **ValueError** – if `treatment_identifier` is in the list of controls
* **ValueError** – if any of the controls is not in `foo['unit_variable']`
* **ValueError** – if any element of `special_predictors` is not an Iterable of length 3
* **ValueError** – if a predictor in an element of `special_predictors` is not a column of foo
* **ValueError** – if one of the operators in an element of `special_predictors` is not one of “mean”, “std”, “median”, “sum”, “count”, “max”, “min” or “var”.
```

--------------------------------

### Synth.fit

Source: https://sdfordham.github.io/pysyncon/synth.html

Fit the model/calculate the weights. Either a `Dataprep` object should be provided or otherwise matrices (X0, X1, Z0, Z1) should be provided.

```APIDOC
## fit

### Description
Fit the model/calculate the weights. Either a `Dataprep` object should be provided or otherwise matrices (X0, X1, Z0, Z1) should be provided (using the notation of Abadie & Gardeazabal [AG03]).

### Parameters
#### Path Parameters
None
#### Query Parameters
None
#### Request Body
None

### Parameters
* **dataprep** (_Dataprep_ _,__optional_) – `Dataprep` object containing data to model, by default None.
* **X0** (_pd.DataFrame_ _,__shape_ _(__m_ _,__c_ _)__,__optional_) – Matrix with each column corresponding to a control unit and each row is covariates, by default None.
* **X1** (_pandas.Series_ _,__shape_ _(__m_ _,__1_ _)__,__optional_) – Column vector giving the covariate values for the treated unit, by default None.
* **Z0** (_pandas.DataFrame_ _,__shape_ _(__n_ _,__c_ _)__,__optional_) – A matrix of the time series of the outcome variable with each column corresponding to a control unit and the rows are the time steps; the columns correspond with the columns of X0, by default None.
* **Z1** (_pandas.Series_ _,__shape_ _(__n_ _,__1_ _)__,__optional_) – Column vector giving the outcome variable values over time for the treated unit, by default None.
* **custom_V** (_numpy.ndarray_ _,__shape_ _(__c_ _,__c_ _)__,__optional_) – Provide a V matrix (using the notation of the Abadie, Diamond & Hainmueller paper), the optimisation problem will only then be solved for the weight matrix W, by default None.
* **optim_method** (_str_ _,__optional_) – Optimisation method to use for the outer optimisation, can be any of the valid options for scipy minimize that do not require a jacobian matrix, namely
    * ’Nelder-Mead’
    * ’Powell’
    * ’CG’
    * ’BFGS’
    * ’L-BFGS-B’
    * ’TNC’
    * ’COBYLA’
    * ’trust-constr’
By default ‘Nelder-Mead’.
* **optim_initial** (_str_ _,__optional_) – Starting value for the outer optimisation, possible starting values are
    * ’equal’, where the weights are all equal,
    * ’ols’, which uses a starting value obtained for fitting a regression.
This is the same argument as in the fit method, by default ‘equal’.

### Returns
A pandas.DataFrame indexed by post_periods, with 3 columns: value that gives the calculated treatment effect, lower_ci that gives the value defining the lower-end of the confidence interval, upper_ci that gives the value defining the upper-end of the confidence interval.

### Return type
pd.DataFrame

### Raises
* **ValueError** – If there is no `Dataprep` object set or (X0, X1, Z0, Z1) is not supplied or self.dataprep is not set.
* **TypeError** – if (X1, Z1) are not of type pandas.Series.
* **ValueError** – if dataprep is not set and pre-periods is not set.
* **ValueError** – if an invalid option for method is given, currently only conformal is supported.
```

--------------------------------

### Dataprep Class Initialization

Source: https://sdfordham.github.io/pysyncon/_sources/dataprep.rst.txt

Initializes the Dataprep class with all the necessary arguments for a synthetic control study. This includes panel data, predictor variables, the dependent variable, unit identifiers, control/treated unit labels, and relevant time periods for optimization and application.

```APIDOC
## Dataprep Class

### Description
Initializes the Dataprep class with all the necessary arguments for a synthetic control study. This includes panel data, predictor variables, the dependent variable, unit identifiers, control/treated unit labels, and relevant time periods for optimization and application.

### Parameters

- **foo** (pandas.DataFrame) - Required - DataFrame containing the panel data.
- **predictors** (list) - Required - List of predictor variables.
- **special_predictors** (list) - Optional - List of special predictor variables.
- **statistical_operation** (str) - Required - Statistical operation to apply to predictors (e.g., 'mean', 'sum').
- **dependent_variable** (str) - Required - The dependent variable.
- **unit_variable** (str) - Required - The column name denoting the unit labels.
- **control_units_label** (str) - Required - The label denoting the control units.
- **treated_unit_label** (str) - Required - The label denoting the treated unit.
- **time_period_for_optimization** (tuple) - Required - The time period (start, end) for the optimization procedure.
- **time_period_for_statistical_operation** (tuple) - Required - The time period (start, end) for applying the statistical operation to predictors.
```

--------------------------------

### PlaceboTest.fit

Source: https://sdfordham.github.io/pysyncon/placebo.html

Runs the placebo tests. This method is multi-process and by default will use all available processors. Use the max_workers option to change this behavior.

```APIDOC
## Method: fit

### Description
Run the placebo tests. This method is multi-process and by default will use all available processors. Use the max_workers option to change this behaviour.

### Parameters
* **dataprep** (_Dataprep_) – `Dataprep` object containing data to model, by default None.
* **scm** (_Synth_ or _AugSynth_) – Synthetic control study to use
* **scm_options** (_dict_, optional) – Options to provide to the fit method of the synthetic control study, valid options are any valid option that the scm_type takes, by default {{}}
* **max_workers** (_Optional[int]_, optional) – Maximum number of processes to use, if not provided then will use all available, by default None
* **verbose** (_bool_, optional) – Whether or not to output progress, by default True
```

--------------------------------

### weights

Source: https://sdfordham.github.io/pysyncon/robust.html

Returns a pandas.Series of the weights for each control unit.

```APIDOC
## weights

### Description
Return a `pandas.Series` of the weights for each control unit.

### Method
`weights(round: int = 3, threshold: float | None = None) -> Series`

### Parameters
- **round** (_int_, optional) – Round the weights to given number of places, by default 3
- **threshold** (_float_, optional) – None

### Response
#### Success Response (pandas.Series)
Weights for each control unit.
```

--------------------------------

### weights

Source: https://sdfordham.github.io/pysyncon/penalized.html

Calculates and returns the weights for each control unit, with options to round the weights and filter by a threshold.

```APIDOC
## weights

### Description
Return a `pandas.Series` of the weights for each control unit.

### Parameters
#### round
- **round** (int) - Optional - Round the weights to given number of places, by default 3
#### threshold
- **threshold** (float) - Optional - If supplied, will only show weights above this value, by default None

### Returns
The weights computed

### Return type
pandas.Series

### Raises
**ValueError** – If there is no weight matrix available
```

--------------------------------

### summary

Source: https://sdfordham.github.io/pysyncon/synth.html

Generates a pandas DataFrame containing summary data, including V matrix values, mean values of predictors for treated and synthetic units, and the sample mean across control units.

```APIDOC
## summary

### Description
Generates a `pandas.DataFrame` with summary data. In particular, it will show the values of the V matrix for each predictor, then the next column will show the mean value of each predictor over the time period `time_predictors_prior` for the treated unit and the synthetic unit and finally there will be a column ‘sample mean’ that shows the mean value of each predictor over the time period `time_predictors_prior` across all the control units, i.e. this will be the same as a synthetic control where all the weights are equal.

### Parameters
* **round** (int, optional) – Round the numbers to given number of places, by default 3
* **X0** (pd.DataFrame, shape (n_cov, n_controls), optional) – Matrix with each column corresponding to a control unit and each row is a covariate. If no dataprep is set, then this must be supplied along with X1, by default None.
* **X1** (pd.Series, shape (n_cov, 1), optional) – Column vector giving the covariate values for the treated unit. If no dataprep is set, then this must be supplied along with Z1, by default None.

### Returns
Summary data.

### Return type
pandas.DataFrame

### Raises
* **ValueError** – If there is no V matrix available
* **ValueError** – If there is no `Dataprep` object set or (Z0, Z1) is not supplied
* **ValueError** – If there is no weight matrix available
```

--------------------------------

### RobustSynth Class

Source: https://sdfordham.github.io/pysyncon/_sources/robust.rst.txt

The RobustSynth class implements the robust control method. It is designed to be used after creating a Dataprep object.

```APIDOC
## Class: RobustSynth

### Description
Implements the robust synthetic control method.

### Usage
Instantiate a `Dataprep` object first, then use it as input to `RobustSynth`.

### Methods
(Members inherited from `pysyncon.RobustSynth`)

### See Also
- `pysyncon.Dataprep`
- Examples folder in the repository for usage illustrations.
```

--------------------------------

### summary

Source: https://sdfordham.github.io/pysyncon/robust.html

Generates a pandas.DataFrame with summary data, comparing predictor values for treated and synthetic units.

```APIDOC
## summary

### Description
Generates a `pandas.DataFrame` with summary data. The first column will show the mean value of each predictor over the time period `time_predictors_prior` for the treated unit and the second column the case of the synthetic unit and finally there will be a column ‘sample mean’ that shows the mean value of each predictor over the time period `time_predictors_prior` across all the control units, i.e. this will be the same as a synthetic control where all the weights are equal.

### Method
`summary(round: int = 3, X0: DataFrame | None = None, X1: Series | None = None) -> DataFrame`

### Parameters
- **round** (_int_, optional) – Round the table values to the given number of places, by default 3
- **X0** (_pd.DataFrame_, shape (n_cov, n_controls), optional) – Matrix with each column corresponding to a control unit and each row is a covariate. If no dataprep is set, then this must be supplied along with X1, by default None.
- **X1** (_pandas.Series_, shape (n_cov, 1), optional) – Column vector giving the covariate values for the treated unit. If no dataprep is set, then this must be supplied along with Z1, by default None.

### Response
#### Success Response (pandas.DataFrame)
Summary data.

### Raises
- **ValueError** – If there is no weight matrix available
- **ValueError** – If there is no `Dataprep` object set or (Z0, Z1) is not supplied
```

--------------------------------

### AugSynth.fit

Source: https://sdfordham.github.io/pysyncon/augsynth.html

Fits the model by calculating the weights for the synthetic control.

```APIDOC
## AugSynth.fit

### Description
Fit the model/calculate the weights.

### Parameters
* **dataprep** (Dataprep, optional) – `Dataprep` object containing data to model.
* **lambda** (float, optional) – Ridge parameter to use. If not supplied, then it is obtained by cross-validation.

### Returns
None
```

--------------------------------

### AugSynth Class Method

Source: https://sdfordham.github.io/pysyncon/augsynth.html

This method computes weights, optionally filtering by a threshold. It returns a pandas Series representing the computed weights.

```APIDOC
## AugSynth Class

### Parameters
#### Optional Parameters
- **threshold** (float) - If supplied, will only show weights above this value, by default None

### Returns
- The weights computed.

### Return Type
- pandas.Series

### Raises
- **ValueError**: If there is no weight matrix available
```

--------------------------------

### summary

Source: https://sdfordham.github.io/pysyncon/penalized.html

Generates a pandas DataFrame containing summary statistics for predictor variables, comparing the treated unit, the synthetic unit, and the average across control units over a specified prior time period.

```APIDOC
## summary

### Description
Generates a `pandas.DataFrame` with summary data. The first column will show the mean value of each predictor over the time period `time_predictors_prior` for the treated unit and the second column the case of the synthetic unit and finally there will be a column ‘sample mean’ that shows the mean value of each predictor over the time period `time_predictors_prior` across all the control units, i.e. this will be the same as a synthetic control where all the weights are equal.

### Parameters
* **round** (_int_ _,__optional_) – Round the table values to the given number of places, by default 3
* **X0** (_pd.DataFrame_ _,__shape_ _(__n_cov_ _,__n_controls_ _)__,__optional_) – Matrix with each column corresponding to a control unit and each row is a covariate. If no dataprep is set, then this must be supplied along with X1, by default None.
* **X1** (_pd.DataFrame_ _,__shape_ _(__n_cov_ _,__1_ _)__,__optional_) – Matrix with each column corresponding to the treated unit and each row is a covariate. If no dataprep is set, then this must be supplied along with X0, by default None.

### Returns
A pandas DataFrame with summary data.

### Return type
DataFrame
```

--------------------------------

### Synth.confidence_interval

Source: https://sdfordham.github.io/pysyncon/synth.html

Calculates confidence intervals using test-inversion, with p-values obtained from adjusted refits of the data.

```APIDOC
## Synth.confidence_interval

### Description
Confidence intervals obtained from test-inversion, where the p-values are obtained by adjusted refits of the data following Chernozhukov et al. [VCZ21].

### Parameters
#### alpha
- **alpha** (float) - The required significance level, e.g. alpha = 0.05 will yield a confidence level of 100 * (1 - alpha) = 95%.
#### time_periods
- **time_periods** (list) - The time-periods to calculate confidence intervals for.
#### tol
- **tol** (float) - The required tolerance (accuracy) required when calculating the lower/upper cut-off point of the confidence interval. The search will try to obtain this tolerance level but will not exceed max_iter iterations trying to achieve that.
#### pre_periods
- **pre_periods** (list | None) - Optional - The time-periods to use for the optimization when refitting the data with the adjusted outcomes, optional.
#### dataprep
- **dataprep** (Dataprep | None) - Optional - Dataprep object defining the study data, if this is not supplied then either self.dataprep must be set or else (X0, X1, Z0, Z1) must all be supplied.
#### X0
- **X0** (DataFrame) - Optional - Matrix with each column corresponding to a control unit and each row is covariates, if this is not supplied then either dataprep must be supplied or self.dataprep must be set.
#### X1
- **X1** (Series) - Optional - Column vector giving the covariate values for the treated unit, if this is not supplied then either dataprep must be supplied or self.dataprep must be set.
#### Z0
- **Z0** (DataFrame) - Optional - A matrix of the time series of the outcome variable with each column corresponding to a control unit and the rows are the time steps; the columns correspond with the columns of X0, if this is not supplied then either dataprep must be supplied or self.dataprep must be set.
#### Z1
- **Z1** (Series) - Optional - Column vector giving the outcome variable values over time for the treated unit, if this is not supplied then either dataprep must be supplied or self.dataprep must be set.
#### custom_V
- **custom_V** (ndarray) - Optional - Provide a V matrix (using the notation of the Abadie, Diamond & Hainmueller paper), the optimisation problem will only then be solved for the weight matrix W. This is the same argument as in the fit method.
#### optim_method
- **optim_method** (Literal['Nelder-Mead', 'Powell', 'CG', 'BFGS', 'L-BFGS-B', 'TNC', 'COBYLA', 'trust-constr'] | None) - Optional - 
#### optim_initial
- **optim_initial** (Literal['equal', 'ols'] | None) - Optional - 
#### optim_options
- **optim_options** (dict | None) - Optional - 
#### method
- **method** (Literal['conformal']) - Default: 'conformal' - 
#### max_iter
- **max_iter** (int) - Default: 50 - 
#### step_sz
- **step_sz** (float | None) - Optional - 
#### step_sz_div
- **step_sz_div** (float) - Default: 20.0 - 
#### verbose
- **verbose** (bool) - Default: True - 

### Returns
- **DataFrame** - Confidence intervals
```

--------------------------------

### summary

Source: https://sdfordham.github.io/pysyncon/augsynth.html

Generates a pandas DataFrame containing summary data for predictor values across treated and control units.

```APIDOC
## summary

### Description
Generates a `pandas.DataFrame` with summary data. The first column will show the mean value of each predictor over the time period `time_predictors_prior` for the treated unit and the second column the case of the synthetic unit and finally there will be a column ‘sample mean’ that shows the mean value of each predictor over the time period `time_predictors_prior` across all the control units, i.e. this will be the same as a synthetic control where all the weights are equal.

### Method
summary(round: int = 3, X0: DataFrame | None = None, X1: Series | None = None) -> DataFrame

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **round** (int, optional) – Round the table values to the given number of places, by default 3
- **X0** (pd.DataFrame, shape (n_cov, n_controls), optional) – Matrix with each column corresponding to a control unit and each row is a covariate. If no dataprep is set, then this must be supplied along with X1, by default None.
- **X1** (pandas.Series, shape (n_cov, 1), optional) – Column vector giving the covariate values for the treated unit. If no dataprep is set, then this must be supplied along with Z1, by default None.

### Request Example
None

### Response
#### Success Response (200)
- **Summary data** (pandas.DataFrame) - Summary data.

#### Response Example
None

### Raises
- **ValueError** – If there is no weight matrix available
- **ValueError** – If there is no `Dataprep` object set or (Z0, Z1) is not supplied
```

--------------------------------

### PenalizedSynth Class

Source: https://sdfordham.github.io/pysyncon/_sources/penalized.rst.txt

The `PenalizedSynth` class in `pysyncon` implements the penalized synthetic control method. It is designed to be used after creating a `Dataprep` object, which defines the study data. The `Dataprep` object is then passed as input to a `PenalizedSynth` object.

```APIDOC
## class pysyncon.PenalizedSynth

Implements the penalized synthetic control method.

### Usage

```python
from pysyncon import Dataprep, PenalizedSynth

# Assuming 'data' is your prepared dataset
dataprep_obj = Dataprep(data=data, 
                        time_period='your_time_period_column', 
                        unit_variable='your_unit_column', 
                        treatment_variable='your_treatment_column', 
                        outcome_variable='your_outcome_column')

penalized_synth_obj = PenalizedSynth(dataprep_obj)
penalized_synth_obj.fit()
```

### Methods

(Members inherited from parent classes are also included. Refer to the source for a complete list of inherited members.)

- **fit()**: Fits the penalized synthetic control model.
- **predict()**: Predicts outcomes using the fitted model.
- **plot()**: Generates plots for the synthetic control results.
```

--------------------------------

### RobustSynth Class

Source: https://sdfordham.github.io/pysyncon/robust.html

The RobustSynth class computes weights. It accepts an optional threshold parameter to filter weights.

```APIDOC
## RobustSynth Class

### Description
Computes and returns weights, with an option to filter by a threshold.

### Parameters
#### Optional Parameters
- **threshold** (float) - If supplied, will only show weights above this value, by default None.

### Returns
- **pandas.Series** - The computed weights.

### Raises
- **ValueError** - If there is no weight matrix available.
```

--------------------------------

### Synth Class

Source: https://sdfordham.github.io/pysyncon/_sources/synth.rst.txt

The Synth class implements the synthetic control method. It takes a Dataprep object as input to define the study data.

```APIDOC
## Class: pysyncon.Synth

### Description
Implements the synthetic control method. It is designed to be used after creating a `Dataprep` object.

### Usage
```python
from pysyncon import Dataprep, Synth

# Assuming 'data' is a pandas DataFrame prepared by Dataprep
dataprep_obj = Dataprep(foo=data, ...) 
# ... other Dataprep parameters
synth_obj = Synth(dataprep_obj)
```

### Methods
(Members are inherited and documented by the base class or other relevant modules.)
```

--------------------------------

### RobustSynth.fit

Source: https://sdfordham.github.io/pysyncon/robust.html

Fits the synthetic control model by calculating the weights. This method must be called before other methods that rely on the fitted model.

```APIDOC
## RobustSynth.fit

### Description
Fit the model/calculate the weights.

### Parameters
#### Path Parameters
- **dataprep** (Dataprep) - Required - `Dataprep` object containing data to model.
- **lambda** (float) - Required - Ridge parameter to use.
- **threshold** (float) - Optional - Remove singular values that are less than this threshold.
- **sv_count** (int) - Optional - Keep this many of the largest singular values when reducing the outcome matrix
```

--------------------------------

### AugSynth Class

Source: https://sdfordham.github.io/pysyncon/_sources/augsynth.rst.txt

The AugSynth class implements the Ridge Augmented Synthetic Control Method. It takes a Dataprep object as input and is designed to produce results comparable to the R augsynth package.

```APIDOC
## Class: AugSynth

### Description
Implements the Ridge Augmented Synthetic Control Method.

### Usage
Create a `Dataprep` object and use it as input to an `AugSynth` object.

### Inheritance
Inherits from `pysyncon.Synth` (implicitly, based on typical class structure, though not explicitly stated as a parent class in the provided text).

### Members
(Details of members are not provided in the source text, but the `:members:` directive suggests they are documented elsewhere.)
```

--------------------------------

### PlaceboTest Class

Source: https://sdfordham.github.io/pysyncon/_sources/placebo.rst.txt

The `PlaceboTest` class provides functionality for conducting placebo tests in synthetic control studies. It allows users to assess the significance of their study by iterating through control units as if they were the treated unit.

```APIDOC
## Class: PlaceboTest

### Description
Provides functionality for conducting placebo tests in synthetic control studies. It allows users to assess the significance of their study by iterating through control units as if they were the treated unit.

### Members
This class has various members that can be invoked directly by users. Refer to the source code for detailed method signatures and parameters.
```

--------------------------------

### path_plot

Source: https://sdfordham.github.io/pysyncon/penalized.html

Generates a plot visualizing the outcome variable over time for both the treated unit and its synthetic control. Allows customization of the time period, treatment time marker, grid display, and plot aesthetics.

```APIDOC
## path_plot

### Description
Plot the outcome variable over time for the treated unit and the synthetic control.

### Parameters
* **time_period** (_Iterable_ _|__pandas.Series_ _|__dict_ _,__optional_) – Time range to plot, if none is supplied then the time range used is the time period over which the optimisation happens, by default None
* **treatment_time** (_int_ _,__optional_) – If supplied, plot a vertical line at the time period that the treatment time occurred, by default None
* **grid** (_bool_ _,__optional_) – Whether or not to plot a grid, by default True
* **Z0** (_pandas.DataFrame_ _,__shape_ _(__n_ _,__c_ _)__,__optional_) – The matrix of the time series of the outcome variable for the control units. If no dataprep is set, then this must be supplied along with Z1, by default None.
* **Z1** (_pandas.Series_ _,__shape_ _(__n_ _,__1_ _)__,__optional_) – The matrix of the time series of the outcome variable for the treated unit. If no dataprep is set, then this must be supplied along with Z0, by default None.
* **plot_args** (_dict_ _[__str_ _,__Any_ _]__,__optional_) – 
Argument to include axis and title for the plot. For instance can do: labels = {
> ”title”: “My Plot Title”, “xlabel”: “X-axis Label”, “ylabel”: “Y-axis Label”
}

### Returns
Returns a tuple with the figure and axis if the user wishes to modify the resulting plot.

### Return type
tuple[plt.Figure, plt.Axis]

### Raises
* **ValueError** – If there is no weight matrix available
* **ValueError** – If there is no `Dataprep` object set or (Z0, Z1) is not supplied
```

--------------------------------

### PlaceboTest.pvalue

Source: https://sdfordham.github.io/pysyncon/placebo.html

Calculates the p-value for the null hypothesis of no effect of treatment using Abadie et al.’s version of Fisher’s exact hypothesis test.

```APIDOC
## Method: pvalue

### Description
Calculate p-value of Abadie et al.’s version of Fisher’s exact hypothesis test for no effect of treatment null, see also section 2.2. of [FP18].

### Parameters
* **treatment_time** (_int_) – The time period that the treatment time occurred

### Returns
p-value for null hypothesis of no effect of treatment

### Return type
float

### Raises
* **ValueError** – if no placebo test has been run yet
```

--------------------------------

### Synth.att

Source: https://sdfordham.github.io/pysyncon/synth.html

Computes the average treatment effect on the treated unit (ATT) and its standard error over a specified time period.

```APIDOC
## Synth.att

### Description
Computes the average treatment effect on the treated unit (ATT) and the standard error to the value over the chosen time-period.

### Parameters
#### time_period
- **time_period** (Iterable | Series | dict) - Optional - Time period to compute the ATT over.
#### Z0
- **Z0** (DataFrame) - Optional - The matrix of the time series of the outcome variable for the control units. If no dataprep is set, then this must be supplied along with Z1.
#### Z1
- **Z1** (Series) - Optional - The matrix of the time series of the outcome variable for the treated unit. If no dataprep is set, then this must be supplied along with Z0.

### Returns
- **dict** - A dictionary with the ATT value and the standard error to the ATT.

### Raises
- **ValueError** - If there is no weight matrix available
- **ValueError** - If there is no `Dataprep` object set or (Z0, Z1) is not supplied
```

--------------------------------

### RobustSynth.att

Source: https://sdfordham.github.io/pysyncon/robust.html

Computes the average treatment effect on the treated unit (ATT) and its standard error over a specified time period.

```APIDOC
## RobustSynth.att

### Description
Computes the average treatment effect on the treated unit (ATT) and the standard error to the value over the chosen time-period.

### Parameters
#### Path Parameters
- **time_period** (Iterable | Series | dict) - Optional - Time period to compute the ATT over.
- **Z0** (DataFrame) - Optional - The matrix of the time series of the outcome variable for the control units. If no dataprep is set, then this must be supplied along with Z1, by default None.
- **Z1** (Series) - Optional - The matrix of the time series of the outcome variable for the treated unit. If no dataprep is set, then this must be supplied along with Z0, by default None.

### Returns
A dictionary with the ATT value and the standard error to the ATT.

### Return Type
dict

### Raises
- **ValueError** - If there is no weight matrix available
- **ValueError** - If there is no `Dataprep` object set or (Z0, Z1) is not supplied
```

--------------------------------

### mape

Source: https://sdfordham.github.io/pysyncon/penalized.html

Calculates the mean absolute percentage error (MAPE) between the synthetic control and the treated unit over the optimization time period. It requires either a pre-set Dataprep object or the Z0 and Z1 data to be supplied.

```APIDOC
## mape

### Description
Returns the mean absolute percentage error in the fit of the synthetic control versus the treated unit over the optimization time-period.

### Parameters
* **Z0** (_pandas.DataFrame_ _,__shape_ _(__n_ _,__c_ _)__,__optional_) – The matrix of the time series of the outcome variable for the control units. If no dataprep is set, then this must be supplied along with Z1, by default None.
* **Z1** (_pandas.Series_ _,__shape_ _(__n_ _,__1_ _)__,__optional_) – The matrix of the time series of the outcome variable for the treated unit. If no dataprep is set, then this must be supplied along with Z0, by default None.

### Returns
Mean absolute percentage error

### Return type
float

### Raises
* **ValueError** – If the fit method has not been run (no weights available.)
* **ValueError** – If there is no `Dataprep` object set or (Z0, Z1) is not supplied
```

--------------------------------

### PenalizedSynth.fit

Source: https://sdfordham.github.io/pysyncon/penalized.html

Fits the penalized synthetic control model by calculating the optimal weights.

```APIDOC
## PenalizedSynth.fit

### Description
Fit the model/calculate the weights.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Method
`fit(_dataprep : Dataprep | None = None_, _X0 : DataFrame | None = None_, _X1 : Series | DataFrame | None = None_, _lambda_ : float | None = 0.01_, _custom_V : ndarray | None = None_)

### Endpoint
N/A (Method within a class)

### Parameters
* **dataprep** (_Dataprep_ _,__optional_) – `Dataprep` object containing data to model, by default None.
* **X0** (_pd.DataFrame_ _,__shape_ _(__c_ _,__m_ _)__,__optional_) – Matrix with each column corresponding to a control unit and each row is a covariate value, by default None.
* **X1** (_pandas.Series_ _,__shape_ _(__c_ _,__1_ _)__,__optional_) – Column vector giving the covariate values for the treated unit, by default None.
* **lambda** (_float_ _,__optional_) – Ridge parameter to use, default 0.01
* **custom_V** (_numpy.ndarray_ _,__shape_ _(__c_ _,__c_ _)__,__optional_) – Provide a V matrix (using the notation of the Abadie, Diamond & Hainmueller paper, this matrix is denoted by Γ in the Abadie and L’Hour paper), if not provided then the identity matrix is used (equal importance to all covariates).

### Returns
None

### Return Type
NoneType

### Raises
**ValueError** – if neither a Dataprep object nor all of (X0, X1) are supplied.
```

--------------------------------

### mape

Source: https://sdfordham.github.io/pysyncon/synth.html

Calculates and returns the mean absolute percentage error between the synthetic control fit and the treated unit over the optimization time period. Requires the fit method to have been run.

```APIDOC
## mape

### Description
Returns the mean absolute percentage error in the fit of the synthetic control versus the treated unit over the optimization time-period.

### Parameters
- **Z0** (pandas.DataFrame, shape (n, c), optional) – The matrix of the time series of the outcome variable for the control units. If no dataprep is set, then this must be supplied along with Z1, by default None.
- **Z1** (pandas.Series, shape (n, 1), optional) – The matrix of the time series of the outcome variable for the treated unit. If no dataprep is set, then this must be supplied along with Z0, by default None.

### Returns
Mean absolute percentage error (float)

### Raises
- **ValueError** – If the fit method has not been run (no weights available.)
- **ValueError** – If there is no `Dataprep` object set or (Z0, Z1) is not supplied
```

--------------------------------

### RobustSynth.gaps_plot

Source: https://sdfordham.github.io/pysyncon/robust.html

Generates a plot visualizing the gap between the treated unit and the synthetic control unit over time.

```APIDOC
## RobustSynth.gaps_plot

### Description
Plots the gap between the treated unit and the synthetic unit over time.

### Parameters
#### Path Parameters
- **time_period** (Iterable | Series | dict | None) - Optional - Time range to plot, if none is supplied then the time range used is the time period over which the optimisation happens, by default None
- **treatment_time** (int) - Optional - If supplied, plot a vertical line at the time period that the treatment time occurred, by default None
- **grid** (bool) - Optional - Whether or not to plot a grid, by default True
- **Z0** (DataFrame) - Optional - The matrix of the time series of the outcome variable for the control units. If no dataprep is set, then this must be supplied along with Z1, by default None.
- **Z1** (Series) - Optional - The matrix of the time series of the outcome variable for the treated unit. If no dataprep is set, then this must be supplied along with Z0, by default None.

### Raises
- **ValueError** - If there is no weight matrix available
- **ValueError** - If there is no `Dataprep` object set or (Z0, Z1) is not supplied
```

--------------------------------

### AugSynth.att

Source: https://sdfordham.github.io/pysyncon/augsynth.html

Computes the average treatment effect on the treated unit (ATT) and its standard error over a specified time period.

```APIDOC
## AugSynth.att

### Description
Computes the average treatment effect on the treated unit (ATT) and the standard error to the value over the chosen time-period.

### Parameters
* **time_period** (Iterable | Series | dict, optional) – Time period to compute the ATT over.
* **Z0** (DataFrame, optional) – The matrix of the time series of the outcome variable for the control units. If no dataprep is set, then this must be supplied along with Z1.
* **Z1** (Series, optional) – The matrix of the time series of the outcome variable for the treated unit. If no dataprep is set, then this must be supplied along with Z0.

### Returns
A dictionary with the ATT value and the standard error to the ATT.

### Return type
dict

### Raises
* **ValueError** – If there is no weight matrix available
* **ValueError** – If there is no `Dataprep` object set or (Z0, Z1) is not supplied
```

--------------------------------

### PenalizedSynth

Source: https://sdfordham.github.io/pysyncon/penalized.html

Represents a penalized synthesis model. It requires covariate values for the treated unit if no dataprep is set.

```APIDOC
## PenalizedSynth

### Description
Represents a penalized synthesis model. It requires covariate values for the treated unit if no dataprep is set.

### Parameters
#### X1
- **X1** (pandas.Series) - Optional - Column vector giving the covariate values for the treated unit. If no dataprep is set, then this must be supplied along with Z1, by default None.

### Returns
Summary data.

### Return type
pandas.DataFrame

### Raises
- **ValueError** – If there is no weight matrix available
- **ValueError** – If there is no `Dataprep` object set or (Z0, Z1) is not supplied
```

--------------------------------

### RobustSynth.mae

Source: https://sdfordham.github.io/pysyncon/robust.html

Calculates the mean absolute error between the synthetic control and the treated unit over the optimization time period.

```APIDOC
## RobustSynth.mae

### Description
Returns the mean absolute error in the fit of the synthetic control versus the treated unit over the optimization time-period.

### Parameters
#### Path Parameters
- **Z0** (DataFrame) - Optional - The matrix of the time series of the outcome variable for the control units. If no dataprep is set, then this must be supplied along with Z1, by default None.
- **Z1** (Series) - Optional - The matrix of the time series of the outcome variable for the treated unit. If no dataprep is set, then this must be supplied along with Z0, by default None.

### Returns
Mean absolute error

### Return Type
float

### Raises
- **ValueError** - If the fit method has not been run (no weights available.)
- **ValueError** - If there is no `Dataprep` object set or (Z0, Z1) is not supplied
```

--------------------------------

### path_plot

Source: https://sdfordham.github.io/pysyncon/synth.html

Plots the outcome variable over time for the treated unit and the synthetic control. Allows customization of the time period, treatment time marker, grid display, and input data for control and treated units. It also accepts plot arguments for titles and labels.

```APIDOC
## path_plot

### Description
Plot the outcome variable over time for the treated unit and the synthetic control.

### Parameters
* **time_period** (Iterable | pandas.Series | dict, optional) – Time range to plot, if none is supplied then the time range used is the time period over which the optimisation happens, by default None
* **treatment_time** (int, optional) – If supplied, plot a vertical line at the time period that the treatment time occurred, by default None
* **grid** (bool, optional) – Whether or not to plot a grid, by default True
* **Z0** (pandas.DataFrame, shape (n, c), optional) – The matrix of the time series of the outcome variable for the control units. If no dataprep is set, then this must be supplied along with Z1, by default None.
* **Z1** (pandas.Series, shape (n, 1), optional) – The matrix of the time series of the outcome variable for the treated unit. If no dataprep is set, then this must be supplied along with Z0, by default None.
* **plot_args** (dict[str, Any], optional) – Argument to include axis and title for the plot. For instance can do: labels = {
  "title": "My Plot Title", "xlabel": "X-axis Label", "ylabel": "Y-axis Label"
}

### Returns
Returns a tuple with the figure and axis if the user wishes to modify the resulting plot.

### Return type
tuple[plt.Figure, plt.Axis]

### Raises
* **ValueError** – If there is no weight matrix available
* **ValueError** – If there is no `Dataprep` object set or (Z0, Z1) is not supplied
```

--------------------------------

### PenalizedSynth.att

Source: https://sdfordham.github.io/pysyncon/penalized.html

Computes the average treatment effect on the treated unit (ATT) and its standard error over a specified time period.

```APIDOC
## PenalizedSynth.att

### Description
Computes the average treatment effect on the treated unit (ATT) and the standard error to the value over the chosen time-period.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Method
`att(_time_period : Iterable | Series | dict_, _Z0 : DataFrame | None = None_, _Z1 : Series | None = None_)`

### Endpoint
N/A (Method within a class)

### Parameters
* **time_period** (_Iterable_ _|__pandas.Series_ _|__dict_ _,__optional_) – Time period to compute the ATT over.
* **Z0** (_pandas.DataFrame_ _,__shape_ _(__n_ _,__c_ _)__,__optional_) – The matrix of the time series of the outcome variable for the control units. If no dataprep is set, then this must be supplied along with Z1, by default None.
* **Z1** (_pandas.Series_ _,__shape_ _(__n_ _,__1_ _)__,__optional_) – The matrix of the time series of the outcome variable for the treated unit. If no dataprep is set, then this must be supplied along with Z0, by default None.

### Returns
A dictionary with the ATT value and the standard error to the ATT.

### Return Type
dict

### Raises
* **ValueError** – If there is no weight matrix available
* **ValueError** – If there is no `Dataprep` object set or (Z0, Z1) is not supplied
```
Tokens:
Raw