### Fit Synth Model and Get Weights

Source: https://context7.com/sdfordham/pysyncon/llms.txt

Instantiate the Synth class and fit the model using a prepared Dataprep object. The fit method allows specifying optimization methods and initial conditions. The weights method can filter for significant control units.

```python
from pysyncon import Dataprep, Synth

# Prepare data (assuming dataprep is already created)
synth = Synth()

# Fit the synthetic control model
synth.fit(
    dataprep=dataprep,
    optim_method="Nelder-Mead",    # Optimization method (also: Powell, BFGS, L-BFGS-B, etc.)
    optim_initial="equal",         # Starting weights: "equal" or "ols"
    optim_options={"maxiter": 1000}  # Scipy minimize options
)

# Get computed weights for control units
weights = synth.weights(round=3, threshold=0.01)  # Only show weights > 0.01
print(weights)
# Output:
# Cataluna                        0.851
# Madrid (Comunidad De)           0.149
# Name: weights, dtype: float64

# Get summary comparing treated, synthetic, and sample mean
summary = synth.summary(round=3)
print(summary)
# Output shows V matrix values, treated unit values, synthetic values, and sample means
```

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

### Fit Synthetic Control model and get weights

Source: https://github.com/sdfordham/pysyncon/blob/main/examples/factor-model.ipynb

Initialize the Synth class, fit the model using generated data, and calculate synthetic control weights, filtering those below a threshold.

```python
synth = Synth()
synth.fit(X0=X0, X1=X1, Z0=Z0, Z1=Z1)

synth.weights(threshold=0.01)
```

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

### Fit Synthetic Control Model

Source: https://github.com/sdfordham/pysyncon/blob/main/examples/basque.ipynb

Instantiate a Synth object and fit the synthetic control model using the prepared data. The optimization uses the Nelder-Mead method with an 'equal' starting point for weights. Note that weights can be sensitive to the optimization scheme and starting point.

```python
synth = Synth()
synth.fit(dataprep=dataprep, optim_method="Nelder-Mead", optim_initial="equal")

synth.weights()
```

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

### Fit Synthetic Control Model

Source: https://github.com/sdfordham/pysyncon/blob/main/examples/texas.ipynb

Instantiate a Synth object and fit it to the prepared data using the BFGS optimization method with OLS as the initial starting point. Note that weights can be sensitive to the optimization scheme and starting point.

```python
synth = Synth()
synth.fit(dataprep=dataprep, optim_method="BFGS", optim_initial="ols")

synth.weights(threshold=0.01)
```

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

### Get synthetic control weights

Source: https://github.com/sdfordham/pysyncon/blob/main/examples/robust/basque_robust.ipynb

Retrieve the calculated weights for each control unit in the synthetic control group. These weights determine the contribution of each control unit to the synthetic control.

```python
robust.weights()
```

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

### fit(dataprep, X0, X1, Z0, Z1, custom_V, optim_method, optim_initial, optim_options)

Source: https://github.com/sdfordham/pysyncon/blob/main/doc/source/synth.md

Fit the model and calculate weights using either a Dataprep object or raw data matrices.

```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.

### Parameters
#### Request Body
- **dataprep** (Dataprep) - Optional - Dataprep object containing data to model.
- **X0** (pd.DataFrame) - Optional - Matrix with each column corresponding to a control unit and each row is covariates.
- **X1** (pandas.Series) - Optional - Column vector giving the covariate values for the treated unit.
- **Z0** (pd.DataFrame) - Optional - A matrix of the time series of the outcome variable with each column corresponding to a control unit.
- **Z1** (pandas.Series) - Optional - Column vector giving the outcome variable values over time for the treated unit.
- **custom_V** (numpy.ndarray) - Optional - Provide a V matrix; the optimisation problem will only then be solved for the weight matrix W.
- **optim_method** (str) - Optional - Optimisation method to use (e.g., 'Nelder-Mead', 'Powell', 'CG', 'BFGS', 'L-BFGS-B', 'TNC', 'COBYLA', 'trust-constr'). Default: 'Nelder-Mead'.
- **optim_initial** (str) - Optional - Starting value for the outer optimisation ('equal' or 'ols'). Default: 'equal'.
- **optim_options** (dict) - Optional - Options to provide to the outer part of the optimisation. Default: {'maxiter': 1000}.

### Response
#### Success Response (200)
- **None** (NoneType) - Returns None.
```

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

### Prepare data and fit PenalizedSynth

Source: https://github.com/sdfordham/pysyncon/blob/main/examples/penalized/basque_penalized.ipynb

Configure the Dataprep object with predictors and fit the PenalizedSynth model.

```python
df = pd.read_csv("../../data/basque.csv")

dataprep = Dataprep(
    foo=df,
    predictors=[
        "school.illit",
        "school.prim",
        "school.med",
        "school.high",
        "school.post.high",
        "invest",
    ],
    predictors_op="mean",
    time_predictors_prior=range(1964, 1970),
    special_predictors=[
        ("gdpcap", range(1960, 1970), "mean"),
        ("sec.agriculture", range(1961, 1970, 2), "mean"),
        ("sec.energy", range(1961, 1970, 2), "mean"),
        ("sec.industry", range(1961, 1970, 2), "mean"),
        ("sec.construction", range(1961, 1970, 2), "mean"),
        ("sec.services.venta", range(1961, 1970, 2), "mean"),
        ("sec.services.nonventa", range(1961, 1970, 2), "mean"),
        ("popdens", [1969], "mean"),
    ],
    dependent="gdpcap",
    unit_variable="regionname",
    time_variable="year",
    treatment_identifier="Basque Country (Pais Vasco)",
    controls_identifier=[
        "Aragon",
        "Baleares (Islas)",
        "Andalucia",
        "Canarias",
        "Cantabria",
        "Castilla Y Leon",
        "Castilla-La Mancha",
        "Cataluna",
        "Comunidad Valenciana",
        "Extremadura",
        "Galicia",
        "Madrid (Comunidad De)",
        "Murcia (Region de)",
        "Navarra (Comunidad Foral De)",
        "Principado De Asturias",
        "Rioja (La)",
        "Spain (Espana)",
    ],
    time_optimize_ssr=range(1960, 1970),
)

pen = PenalizedSynth()
pen.fit(dataprep, lambda_=0.01)
```

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

### Import necessary libraries

Source: https://github.com/sdfordham/pysyncon/blob/main/examples/factor-model.ipynb

Import the Synth class and the LinearFactorModel generator from the pysyncon library.

```python
from pysyncon import Synth
from pysyncon.generator import LinearFactorModel
```

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

### Prepare Data for Synthetic Control Study

Source: https://github.com/sdfordham/pysyncon/blob/main/examples/texas.ipynb

Initialize a Dataprep object with study data, predictor variables, time ranges, and control units. This object defines the parameters for the synthetic control model. Ensure the data file '../data/texas.csv' is accessible.

```python
df = pd.read_csv("../data/texas.csv")

dataprep = Dataprep(
    foo=df,
    predictors=["income", "ur", "poverty"],
    predictors_op="mean",
    time_predictors_prior=range(1985, 1994),
    special_predictors=[
        ("bmprison", [1988], "mean"),
        ("bmprison", [1990], "mean"),
        ("bmprison", [1991], "mean"),
        ("bmprison", [1992], "mean"),
        ("alcohol", [1990], "mean"),
        ("aidscapita", [1990], "mean"),
        ("aidscapita", [1991], "mean"),
        ("black", [1990], "mean"),
        ("black", [1991], "mean"),
        ("black", [1992], "mean"),
        ("perc1519", [1990], "mean"),
    ],
    dependent="bmprison",
    unit_variable="state",
    time_variable="year",
    treatment_identifier="Texas",
    controls_identifier=[
        "Alabama",
        "Alaska",
        "Arizona",
        "Arkansas",
        "California",
        "Colorado",
        "Connecticut",
        "Delaware",
        "District of Columbia",
        "Florida",
        "Georgia",
        "Hawaii",
        "Idaho",
        "Illinois",
        "Indiana",
        "Iowa",
        "Kansas",
        "Kentucky",
        "Louisiana",
        "Maine",
        "Maryland",
        "Massachusetts",
        "Michigan",
        "Minnesota",
        "Mississippi",
        "Missouri",
        "Montana",
        "Nebraska",
        "Nevada",
        "New Hampshire",
        "New Jersey",
        "New Mexico",
        "New York",
        "North Carolina",
        "North Dakota",
        "Ohio",
        "Oklahoma",
        "Oregon",
        "Pennsylvania",
        "Rhode Island",
        "South Carolina",
        "South Dakota",
        "Tennessee",
        "Utah",
        "Vermont",
        "Virginia",
        "Washington",
        "West Virginia",
        "Wisconsin",
        "Wyoming",
    ],
    time_optimize_ssr=range(1985, 1994),
)

print(dataprep)
```

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

### Constructor: pysyncon.Dataprep

Source: https://github.com/sdfordham/pysyncon/blob/main/doc/source/dataprep.md

Initializes the Dataprep object with panel data and study configuration parameters.

```APIDOC
## Constructor: pysyncon.Dataprep

### Description
Initializes the Dataprep class, which processes panel data and prepares the necessary matrices for synthetic control optimization methods.

### Parameters
#### Request Body
- **foo** (pandas.DataFrame) - Required - The panel data where columns are variables and rows are time-steps.
- **predictors** (Axes) - Required - Columns of foo to use as predictors.
- **predictors_op** (string) - Required - Statistical operation (mean, std, median, sum, count, max, min, var) applied to predictors over time_predictors_prior.
- **dependent** (Any) - Required - The column of foo to use as the dependent variable.
- **unit_variable** (Any) - Required - The column of foo containing unit labels.
- **time_variable** (Any) - Required - The column of foo containing time periods.
- **treatment_identifier** (Any) - Required - The unit label for the treated unit.
- **controls_identifier** (Iterable) - Required - The unit labels for control units.
- **time_predictors_prior** (Iterable) - Required - Time range to apply the statistical operation to predictors.
- **time_optimize_ssr** (Iterable) - Required - Time range over which the loss function is minimized.
- **special_predictors** (Iterable, optional) - Optional - Additional predictors averaged over custom time periods with specific operators.
```

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

### Import necessary libraries

Source: https://github.com/sdfordham/pysyncon/blob/main/examples/robust/basque_robust.ipynb

Import pandas for data manipulation and Dataprep and RobustSynth from pysyncon.

```python
import pandas as pd
from pysyncon import Dataprep, RobustSynth
```

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

### Configuring Dataprep and fitting AugSynth

Source: https://github.com/sdfordham/pysyncon/blob/main/examples/augsynth/basque_augsynth.ipynb

Prepare the dataset and fit the Augmented Synthetic Control model using specified predictors and identifiers.

```python
df = pd.read_csv("../../data/basque.csv")

dataprep = Dataprep(
    foo=df,
    predictors=[
        "school.illit",
        "school.prim",
        "school.med",
        "school.high",
        "school.post.high",
        "invest",
    ],
    predictors_op="mean",
    time_predictors_prior=range(1964, 1970),
    special_predictors=[
        ("gdpcap", range(1960, 1970), "mean"),
        ("sec.agriculture", range(1961, 1970, 2), "mean"),
        ("sec.energy", range(1961, 1970, 2), "mean"),
        ("sec.industry", range(1961, 1970, 2), "mean"),
        ("sec.construction", range(1961, 1970, 2), "mean"),
        ("sec.services.venta", range(1961, 1970, 2), "mean"),
        ("sec.services.nonventa", range(1961, 1970, 2), "mean"),
        ("popdens", [1969], "mean"),
    ],
    dependent="gdpcap",
    unit_variable="regionname",
    time_variable="year",
    treatment_identifier="Basque Country (Pais Vasco)",
    controls_identifier=[
        "Andalucia",
        "Aragon",
        "Baleares (Islas)",
        "Canarias",
        "Cantabria",
        "Castilla-La Mancha",
        "Castilla Y Leon",
        "Cataluna",
        "Comunidad Valenciana",
        "Extremadura",
        "Galicia",
        "Madrid (Comunidad De)",
        "Murcia (Region de)",
        "Navarra (Comunidad Foral De)",
        "Principado De Asturias",
        "Rioja (La)",
        "Spain (Espana)",
    ],
    time_optimize_ssr=range(1960, 1970),
)

augsynth = AugSynth()
augsynth.fit(dataprep=dataprep)
```

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

### Prepare data and fit RobustSynth model

Source: https://github.com/sdfordham/pysyncon/blob/main/examples/robust/basque_robust.ipynb

Load data using pandas, prepare it for synthetic control analysis using Dataprep, and then fit a RobustSynth model. The `Dataprep` class requires specifying predictor variables, a dependent variable, unit and time variables, and identifiers for the treatment and control groups. The `RobustSynth` model is then fitted to this prepared data.

```python
df = pd.read_csv("../../data/basque.csv")

dataprep = Dataprep(
    foo=df,
    predictors=[
        "school.illit",
        "school.prim",
        "school.med",
        "school.high",
        "school.post.high",
        "invest",
    ],
    predictors_op="mean",
    time_predictors_prior=range(1964, 1970),
    special_predictors=[
        ("gdpcap", range(1960, 1970), "mean"),
        ("sec.agriculture", range(1961, 1970, 2), "mean"),
        ("sec.energy", range(1961, 1970, 2), "mean"),
        ("sec.industry", range(1961, 1970, 2), "mean"),
        ("sec.construction", range(1961, 1970, 2), "mean"),
        ("sec.services.venta", range(1961, 1970, 2), "mean"),
        ("sec.services.nonventa", range(1961, 1970, 2), "mean"),
        ("popdens", [1969], "mean"),
    ],
    dependent="gdpcap",
    unit_variable="regionname",
    time_variable="year",
    treatment_identifier="Basque Country (Pais Vasco)",
    controls_identifier=[
        "Aragon",
        "Baleares (Islas)",
        "Andalucia",
        "Canarias",
        "Cantabria",
        "Castilla Y Leon",
        "Castilla-La Mancha",
        "Cataluna",
        "Comunidad Valenciana",
        "Extremadura",
        "Galicia",
        "Madrid (Comunidad De)",
        "Murcia (Region de)",
        "Navarra (Comunidad Foral De)",
        "Principado De Asturias",
        "Rioja (La)",
        "Spain (Espana)",
    ],
    time_optimize_ssr=range(1960, 1970),
)

robust = RobustSynth()
robust.fit(dataprep, lambda_=0.1, sv_count=2)
```

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

### Prepare Study Data with Dataprep

Source: https://github.com/sdfordham/pysyncon/blob/main/examples/basque.ipynb

Initialize a Dataprep object to define the parameters for the synthetic control study, including predictor variables, dependent variable, and control units. This mirrors the functionality of the 'dataprep' method in the R 'synth' package.

```python
df = pd.read_csv("../data/basque.csv")

dataprep = Dataprep(
    foo=df,
    predictors=[
        "school.illit",
        "school.prim",
        "school.med",
        "school.high",
        "school.post.high",
        "invest",
    ],
    predictors_op="mean",
    time_predictors_prior=range(1964, 1970),
    special_predictors=[
        ("gdpcap", range(1960, 1970), "mean"),
        ("sec.agriculture", range(1961, 1970, 2), "mean"),
        ("sec.energy", range(1961, 1970, 2), "mean"),
        ("sec.industry", range(1961, 1970, 2), "mean"),
        ("sec.construction", range(1961, 1970, 2), "mean"),
        ("sec.services.venta", range(1961, 1970, 2), "mean"),
        ("sec.services.nonventa", range(1961, 1970, 2), "mean"),
        ("popdens", [1969], "mean"),
    ],
    dependent="gdpcap",
    unit_variable="regionname",
    time_variable="year",
    treatment_identifier="Basque Country (Pais Vasco)",
    controls_identifier=[
        "Spain (Espana)",
        "Andalucia",
        "Aragon",
        "Principado De Asturias",
        "Baleares (Islas)",
        "Canarias",
        "Cantabria",
        "Castilla Y Leon",
        "Castilla-La Mancha",
        "Cataluna",
        "Comunidad Valenciana",
        "Extremadura",
        "Galicia",
        "Madrid (Comunidad De)",
        "Murcia (Region de)",
        "Navarra (Comunidad Foral De)",
        "Rioja (La)",
    ],
    time_optimize_ssr=range(1960, 1970),
)

print(dataprep)
```

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

### Import pysyncon modules

Source: https://github.com/sdfordham/pysyncon/blob/main/examples/penalized/basque_penalized.ipynb

Initial imports required for synthetic control analysis.

```python
import pandas as pd
from pysyncon import Dataprep, PenalizedSynth, Synth
```

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

### Visualize Synthetic Control Results with Path and Gaps Plots

Source: https://context7.com/sdfordham/pysyncon/llms.txt

Generate path plots showing the treated unit vs. synthetic control and gaps plots illustrating the difference over time. These visualizations require a fitted Synth or PenalizedSynth object.

```python
from pysyncon import Dataprep, Synth

# Fit model (assuming dataprep is created)
synth = Synth()
synth.fit(dataprep=dataprep)

# Path plot: treated unit vs synthetic control over time
fig, ax = synth.path_plot(
    time_period=range(1955, 1998),    # Time range to plot
    treatment_time=1975,               # Draw vertical line at treatment
    grid=True,                         # Show grid
    plot_args={
        "title": "Basque Country vs Synthetic Control",
        "xlabel": "Year",
        "ylabel": "GDP per capita"
    }
)

# Gaps plot: difference between treated and synthetic over time
synth.gaps_plot(
    time_period=range(1955, 1998),
    treatment_time=1975,
    grid=True
)

# Plots can also use custom matrices instead of dataprep
synth.path_plot(Z0=Z0_custom, Z1=Z1_custom, treatment_time=1975)
synth.gaps_plot(Z0=Z0_custom, Z1=Z1_custom, treatment_time=1975)
```

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

### Import Libraries for Pysyncon

Source: https://github.com/sdfordham/pysyncon/blob/main/examples/basque.ipynb

Import necessary libraries including pandas for data manipulation, and Dataprep, Synth, and PlaceboTest from pysyncon for synthetic control analysis.

```python
import pandas as pd
from pysyncon import Dataprep, Synth
from pysyncon.utils import PlaceboTest
```

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

### Visualize path and gaps

Source: https://github.com/sdfordham/pysyncon/blob/main/examples/penalized/basque_penalized.ipynb

Generate plots to visualize the synthetic control path and the gaps between treated and synthetic units.

```python
pen.path_plot(time_period=range(1955, 1998), treatment_time=1975)
```

```python
pen.gaps_plot(time_period=range(1955, 1998), treatment_time=1975)
```

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

### Importing pysyncon modules

Source: https://github.com/sdfordham/pysyncon/blob/main/examples/augsynth/basque_augsynth.ipynb

Initial imports required to access Dataprep and AugSynth classes.

```python
import pandas as pd
from pysyncon import Dataprep, AugSynth
```

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

### Prepare Panel Data with Dataprep

Source: https://context7.com/sdfordham/pysyncon/llms.txt

Use the Dataprep class to describe study data, including predictors, outcome variables, and unit/time identifiers. This class automatically generates matrices for optimization and plotting. Ensure all necessary columns and time ranges are correctly specified.

```python
import pandas as pd
from pysyncon import Dataprep

# Load panel data
df = pd.read_csv("basque.csv")

# Create Dataprep object describing the study
dataprep = Dataprep(
    foo=df,                                    # Panel data as DataFrame
    predictors=[
        "school.illit",
        "school.prim",
        "school.med",
        "school.high",
        "school.post.high",
        "invest",
    ],
    predictors_op="mean",                      # Aggregation operation for predictors
    time_predictors_prior=range(1964, 1970),   # Time range for predictor aggregation
    special_predictors=[
        ("gdpcap", range(1960, 1970), "mean"),
        ("sec.agriculture", range(1961, 1970, 2), "mean"),
        ("sec.energy", range(1961, 1970, 2), "mean"),
        ("sec.industry", range(1961, 1970, 2), "mean"),
        ("popdens", [1969], "mean"),
    ],
    dependent="gdpcap",                         # Outcome variable column
    unit_variable="regionname",                 # Column identifying units
    time_variable="year",                       # Column identifying time periods
    treatment_identifier="Basque Country (Pais Vasco)",  # Treated unit label
    controls_identifier=[
        "Cataluna",
        "Madrid (Comunidad De)",
        "Andalucia",
        "Aragon",
        "Castilla Y Leon",
        "Galicia",
    ],
    time_optimize_ssr=range(1960, 1970),        # Time range for optimization
)

print(dataprep)
# Output:
# Dataprep
# Treated unit: Basque Country (Pais Vasco)
# Dependent variable: gdpcap
# Control units: Cataluna, Madrid (Comunidad De), ...
# Time range in data: 1955.0 - 1997.0
# Time range for loss minimization: range(1960, 1970)
# Time range for predictors: range(1964, 1970)
```

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

### Display model summary

Source: https://github.com/sdfordham/pysyncon/blob/main/examples/robust/basque_robust.ipynb

Generate a summary table comparing the treated unit's values for predictor variables with those of the synthetic control and the sample mean. This helps evaluate the pre-intervention fit.

```python
robust.summary()
```

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

### Import Libraries for Pysyncon

Source: https://github.com/sdfordham/pysyncon/blob/main/examples/texas.ipynb

Import pandas for data manipulation and Dataprep and Synth from pysyncon for synthetic control analysis.

```python
import pandas as pd
from pysyncon import Dataprep, Synth
```

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

### Recover traditional synthetic control weights

Source: https://github.com/sdfordham/pysyncon/blob/main/examples/penalized/basque_penalized.ipynb

Use the Synth class to calculate the V matrix and apply it to PenalizedSynth with lambda=0.

```python
synth = Synth()
synth.fit(dataprep=dataprep)

pen.fit(dataprep=dataprep, lambda_=0.0, custom_V=synth.V)
pen.weights()
```

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

### Visualization Methods

Source: https://github.com/sdfordham/pysyncon/blob/main/examples/texas.ipynb

Methods for visualizing the synthetic control path and the gaps between the treated unit and the synthetic control.

```APIDOC
## synth.path_plot

### Description
Plots the path of the treated unit and the synthetic control over a specified time period.

### Parameters
#### Query Parameters
- **time_period** (range) - Required - The range of years to plot.
- **treatment_time** (int) - Required - The year the treatment occurred.

## synth.gaps_plot

### Description
Shows the gaps (the difference between the treated unit and the synthetic control) over time.

### Parameters
#### Query Parameters
- **time_period** (range) - Required - The range of years to plot.
- **treatment_time** (int) - Required - The year the treatment occurred.
```

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

### Summarizing model fit

Source: https://github.com/sdfordham/pysyncon/blob/main/examples/augsynth/basque_augsynth.ipynb

Display a summary table comparing treated and synthetic unit characteristics.

```python
augsynth.summary()
```

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

### Define simulation parameters

Source: https://github.com/sdfordham/pysyncon/blob/main/examples/factor-model.ipynb

Set parameters for data generation, including random seed, number of units, covariates, and time periods.

```python
seed = 123456

n_units = 20
n_observable = 7
n_unobservable = 17
n_periods_pre = 50
n_periods_post = 10

effect_dist = (20, 30)
```

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

### fit() Method

Source: https://github.com/sdfordham/pysyncon/blob/main/doc/source/penalized.md

Fits the penalized synthetic control model and calculates weights using a Dataprep object or raw covariate matrices.

```APIDOC
## fit(dataprep=None, X0=None, X1=None, lambda_=0.01, custom_V=None)

### Description
Fit the model and calculate the weights for the penalized synthetic control method.

### Parameters
- **dataprep** (Dataprep) - Optional - Dataprep object containing data to model.
- **X0** (pd.DataFrame) - Optional - Matrix with each column corresponding to a control unit and each row is a covariate value.
- **X1** (pd.Series) - Optional - Column vector giving the covariate values for the treated unit.
- **lambda_** (float) - Optional - Ridge parameter to use, default 0.01.
- **custom_V** (numpy.ndarray) - Optional - Provide a V matrix (Γ in Abadie and L’Hour paper); if not provided, the identity matrix is used.

### Response
- **Returns** (NoneType) - None
```

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

### Calculate ATT and Fit Metrics

Source: https://context7.com/sdfordham/pysyncon/llms.txt

Calculate the average treatment effect on the treated and various fit quality metrics after fitting a synthetic control model.

```python
att_result = synth.att(time_period=range(1975, 1998))
print(att_result)
# Output: {'att': -0.699, 'se': 0.071}

# Calculate fit quality metrics
mspe = synth.mspe()  # Mean squared prediction error
mape = synth.mape()  # Mean absolute percentage error
mae = synth.mae()    # Mean absolute error
```

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

### Configure training Dataprep object

Source: https://github.com/sdfordham/pysyncon/blob/main/examples/germany.ipynb

Defines the Dataprep object for the initial optimization period (1981-1991).

```python
df = pd.read_csv("../data/germany.csv")

dataprep_train = Dataprep(
    foo=df,
    predictors=["gdp", "trade", "infrate"],
    predictors_op="mean",
    time_predictors_prior=range(1971, 1981),
    special_predictors=[
        ("industry", range(1971, 1981), "mean"),
        ("schooling", [1970, 1975], "mean"),
        ("invest70", [1980], "mean"),
    ],
    dependent="gdp",
    unit_variable="country",
    time_variable="year",
    treatment_identifier="West Germany",
    controls_identifier=[
        "USA",
        "UK",
        "Austria",
        "Belgium",
        "Denmark",
        "France",
        "Italy",
        "Netherlands",
        "Norway",
        "Switzerland",
        "Japan",
        "Greece",
        "Portugal",
        "Spain",
        "Australia",
        "New Zealand",
    ],
    time_optimize_ssr=range(1981, 1991),
)

print(dataprep_train)
```

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

### Generate summary of synthetic control fit

Source: https://github.com/sdfordham/pysyncon/blob/main/examples/factor-model.ipynb

Calculate and display a summary table comparing observable covariates for the treated unit, synthetic control unit, and sample means. Requires covariate matrices X0 and X1.

```python
synth.summary(X0=X0, X1=X1)
```

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

### Calculate Confidence Intervals with Synth

Source: https://context7.com/sdfordham/pysyncon/llms.txt

Calculates 95% confidence intervals using conformal inference for specified post-treatment periods. Requires prior model fitting. Custom optimization options can be provided.

```python
from pysyncon import Dataprep, Synth

# Fit model first
synth = Synth()
synth.fit(dataprep=dataprep, optim_method="Nelder-Mead", optim_initial="equal")

# Calculate 95% confidence intervals for specific post-treatment periods
ci_results = synth.confidence_interval(
    alpha=0.05,                         # Significance level (95% CI)
    time_periods=[1976, 1977, 1978],    # Post-treatment periods for CIs
    tol=0.01,                           # Tolerance for CI bounds
    pre_periods=list(range(1955, 1975)), # Pre-treatment periods (optional)
    max_iter=50,                         # Max iterations for root search
    step_sz_div=20.0,                    # Step size divisor for search
    verbose=True                         # Print progress
)
# Output:
# (1/3) Calculating confidence interval for time-period t=1976...
#     95.0% CI: [-0.168, 0.192]
# (2/3) Calculating confidence interval for time-period t=1977...
#     95.0% CI: [-0.301, 0.084]
# ...

print(ci_results)
#           value  lower_ci  upper_ci
# time
# 1976.0  0.012256 -0.167881  0.192394
# 1977.0 -0.121307 -0.301444  0.084389
# 1978.0 -0.234512 -0.412345  0.023456

# Can also specify custom V matrix and optimization options
ci_results = synth.confidence_interval(
    alpha=0.05,
    time_periods=[1976],
    tol=0.05,
    optim_method="Powell",
    optim_initial="ols",
    verbose=False
)
```

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

### Run Placebo Test

Source: https://github.com/sdfordham/pysyncon/blob/main/examples/basque.ipynb

Executes a placebo test using the PlaceboTest class with specified optimization options.

```python
placebo_test = PlaceboTest()
placebo_test.fit(
    dataprep=dataprep,
    scm=synth,
    scm_options={"optim_method": "Nelder-Mead", "optim_initial": "equal"},
)
```

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

### Fit Synthetic Control with Custom Matrices

Source: https://context7.com/sdfordham/pysyncon/llms.txt

Use pre-computed covariate and outcome matrices instead of a Dataprep object, with optional custom importance weights.

```python
import pandas as pd
import numpy as np
from pysyncon import Synth

# X0: Covariate matrix for control units (predictors x controls)
X0 = pd.DataFrame({
    "Control_A": [0.5, 0.3, 0.2],
    "Control_B": [0.4, 0.4, 0.2],
    "Control_C": [0.6, 0.2, 0.2],
}, index=["predictor1", "predictor2", "predictor3"])

# X1: Covariate vector for treated unit
X1 = pd.Series([0.45, 0.35, 0.2], index=["predictor1", "predictor2", "predictor3"], name="Treated")

# Z0: Outcome time series for control units (time x controls)
Z0 = pd.DataFrame({
    "Control_A": [100, 102, 105, 108, 110],
    "Control_B": [95, 98, 100, 103, 106],
    "Control_C": [90, 93, 97, 100, 104],
}, index=[2015, 2016, 2017, 2018, 2019])

# Z1: Outcome time series for treated unit
Z1 = pd.Series([98, 101, 103, 107, 109], index=[2015, 2016, 2017, 2018, 2019], name="Treated")

synth = Synth()
synth.fit(X0=X0, X1=X1, Z0=Z0, Z1=Z1)

# Optionally provide custom V matrix (diagonal importance weights for predictors)
custom_V = np.array([0.5, 0.3, 0.2])  # Weights for each predictor
synth.fit(X0=X0, X1=X1, Z0=Z0, Z1=Z1, custom_V=custom_V)

print(synth.weights())
```

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

### Visualize synthetic control path

Source: https://github.com/sdfordham/pysyncon/blob/main/examples/germany.ipynb

Generates a plot comparing the treated unit and the synthetic control.

```python
synth.path_plot(time_period=range(1960, 2004), treatment_time=1990)
```

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

### PlaceboTest.fit

Source: https://github.com/sdfordham/pysyncon/blob/main/doc/source/placebo.md

Executes the placebo tests by running a synthetic control study using each control unit as a treated unit.

```APIDOC
## fit(dataprep, scm, scm_options, max_workers, verbose)

### Description
Runs the placebo tests using multi-processing to evaluate the significance of the synthetic control model.

### Parameters
#### Request Body
- **dataprep** (Dataprep) - Required - Dataprep object containing data to model.
- **scm** (BaseSynth) - Required - Synthetic control study to use (Synth or AugSynth).
- **scm_options** (dict) - Optional - Options to provide to the fit method of the synthetic control study.
- **max_workers** (int) - Optional - Maximum number of processes to use.
- **verbose** (bool) - Optional - Whether or not to output progress.
```

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

### Generate data from Linear Factor Model

Source: https://github.com/sdfordham/pysyncon/blob/main/examples/factor-model.ipynb

Instantiate LinearFactorModel and use its generate method to create covariate and outcome matrices for control and treated units.

```python
lfm = LinearFactorModel(effect_dist=effect_dist, seed=seed)

X0, X1, Z0, Z1 = lfm.generate(
    n_units=n_units,
    n_observable=n_observable,
    n_unobservable=n_unobservable,
    n_periods_pre=n_periods_pre,
    n_periods_post=n_periods_post,
)
```

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

### Calculate goodness-of-fit metrics

Source: https://github.com/sdfordham/pysyncon/blob/main/examples/factor-model.ipynb

Compute and print Mean Squared Prediction Error (MSPE), Mean Absolute Percentage Error (MAPE), and Mean Absolute Error (MAE) to assess the fit of the synthetic control model in the pre-treatment period. Requires outcome matrices Z0 and Z1.

```python
print("MSPE:", round(synth.mspe(Z0=Z0, Z1=Z1), 3))
print("MAPE:", round(synth.mape(Z0=Z0, Z1=Z1), 3))
print("MAE:", round(synth.mae(Z0=Z0, Z1=Z1), 3))
```

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

### summary()

Source: https://github.com/sdfordham/pysyncon/blob/main/doc/source/robust.md

Generates a pandas DataFrame containing summary statistics for predictors comparing the treated unit, synthetic unit, and sample mean.

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

### Description
Generates a pandas.DataFrame with summary data comparing the treated unit, synthetic unit, and the sample mean of control units.

### Parameters
#### Query Parameters
- **round** (int) - Optional - Round the table values to the given number of places, by default 3.
- **X0** (pd.DataFrame) - Optional - Matrix with each column corresponding to a control unit and each row is a covariate. Required if no dataprep is set.
- **X1** (pandas.Series) - Optional - Column vector giving the covariate values for the treated unit. Required if no dataprep is set.

### Response
- **Returns** (pandas.DataFrame) - Summary data table.

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

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

### RobustSynth Class

Source: https://github.com/sdfordham/pysyncon/blob/main/doc/source/robust.md

The `RobustSynth` class implements the robust synthetic control method. It requires a `Dataprep` object for initialization and provides methods for fitting the model and computing results.

```APIDOC
## class pysyncon.RobustSynth

Implementation of the robust synthetic control method due to Amjad, Shah & Shen [[ASS18](bibliography.md#id6)].

### att

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** (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`](dataprep.md#pysyncon.Dataprep) object set or (Z0, Z1) is not supplied

### fit

Fit the model/calculate the weights.

#### Parameters
* **dataprep** ([*Dataprep*](dataprep.md#pysyncon.Dataprep)) – [`Dataprep`](dataprep.md#pysyncon.Dataprep) object containing data to model.
* **lambda** (float) – 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

### gaps_plot

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

#### 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** (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.

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

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

### Plot synthetic control path

Source: https://github.com/sdfordham/pysyncon/blob/main/examples/robust/basque_robust.ipynb

Generate a plot showing the time path of the treated unit and its synthetic control. This visualization helps assess the fit of the synthetic control before the intervention time.

```python
robust.path_plot(time_period=range(1955, 1998), treatment_time=1975)
```

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

### Retrieving model weights

Source: https://github.com/sdfordham/pysyncon/blob/main/examples/augsynth/basque_augsynth.ipynb

Access the calculated weights for the synthetic control units.

```python
augsynth.weights()
```

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

### Display Predictor Summary Statistics

Source: https://github.com/sdfordham/pysyncon/blob/main/examples/texas.ipynb

Provides a summary of predictor values, comparing the treated unit, synthetic control, and sample means over `time_predictors_prior`. This helps in assessing the fit of the synthetic control.

```python
synth.summary()
```

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

### Fit final synthetic control with custom V

Source: https://github.com/sdfordham/pysyncon/blob/main/examples/germany.ipynb

Fits the final model using the V matrix derived from the training run.

```python
synth = Synth()
synth.fit(dataprep=dataprep, custom_V=synth_train.V)

synth.weights()
```

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

### summary

Source: https://github.com/sdfordham/pysyncon/blob/main/doc/source/penalized.md

Generates a pandas.DataFrame with summary data comparing predictors for treated, synthetic, and control units.

```APIDOC
## summary

### Description
Generates a pandas.DataFrame with summary data showing the mean value of each predictor for the treated unit, synthetic unit, and the sample mean of control units.

### Parameters
#### Query Parameters
- **round** (int) - Optional - Number of decimal places to round, default 3.
- **X0** (pd.DataFrame) - Optional - Matrix of covariates for control units.
- **X1** (pandas.Series) - Optional - Column vector of covariates for the treated unit.

### Response
- **Returns** (pandas.DataFrame) - Summary data table.

### Errors
- **ValueError** - If no weight matrix is available or Dataprep/X0/X1 is missing.
```

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

### summary

Source: https://github.com/sdfordham/pysyncon/blob/main/doc/source/augsynth.md

Generates a pandas.DataFrame with summary data comparing predictors for treated, synthetic, and control units.

```APIDOC
## summary

### Description
Generates a summary table showing mean values of predictors for the treated unit, synthetic unit, and the sample mean of control units.

### Parameters
#### Query Parameters
- **round** (int) - Optional - Number of decimal places to round values (default: 3).
- **X0** (pd.DataFrame) - Optional - Matrix of covariates for control units.
- **X1** (pandas.Series) - Optional - Vector of covariate values for the treated unit.

### Response
- **Returns** (pandas.DataFrame) - Summary data table.

### Errors
- **ValueError** - If no weight matrix is available or Dataprep/X0/X1 are missing.
```

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

### att() Method

Source: https://github.com/sdfordham/pysyncon/blob/main/doc/source/penalized.md

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

```APIDOC
## att(time_period, Z0=None, Z1=None)

### 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** (pd.DataFrame) - Optional - The matrix of the time series of the outcome variable for the control units.
- **Z1** (pd.Series) - Optional - The matrix of the time series of the outcome variable for the treated unit.

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

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

### Generate Synthetic Panel Data with LinearFactorModel

Source: https://context7.com/sdfordham/pysyncon/llms.txt

Generates synthetic panel data using a linear factor model for simulation studies. Allows customization of distributions for covariates, parameters, treatment effects, and shocks, with a specified random seed for reproducibility.

```python
from pysyncon.generator import LinearFactorModel
from pysyncon import Synth

# Create data generator with custom distributions
generator = LinearFactorModel(
    observed_dist=(0, 1),           # Uniform dist for observed covariates
    observed_params_dist=(0, 10),   # Uniform dist for observed covariate parameters
    unobserved_dist=(0, 1),         # Uniform dist for unobserved covariates
    unobserved_params_dist=(0, 10), # Uniform dist for unobserved parameters
    effect_dist=(0, 20),            # Uniform dist for treatment effect
    shocks_dist=(0, 1),             # Normal dist for random shocks
    seed=42                         # Random seed for reproducibility
)

# Generate synthetic data matrices
X0, X1, Z0, Z1 = generator.generate(
    n_units=20,           # Total units (1 treated + 19 controls)
    n_observable=5,       # Number of observable covariates
    n_unobservable=3,     # Number of unobservable covariates
    n_periods_pre=10,     # Pre-treatment time periods
    n_periods_post=5      # Post-treatment time periods
)

# X0: DataFrame (n_observable x n_controls) - control unit covariates
# X1: Series (n_observable,) - treated unit covariates
# Z0: DataFrame (n_periods x n_controls) - control unit outcomes
# Z1: Series (n_periods,) - treated unit outcomes (with treatment effect post-intervention)

print(f"X0 shape: {X0.shape}")  # (5, 19)
print(f"Z0 shape: {Z0.shape}")  # (15, 19)

# Use generated data with Synth
synth = Synth()
synth.fit(X0=X0, X1=X1, Z0=Z0.iloc[:10], Z1=Z1.iloc[:10])  # Fit on pre-period

# Evaluate on full time series
synth.path_plot(Z0=Z0, Z1=Z1, treatment_time=10)
```