### Example: PanelMatch and Covariate Balance

Source: https://cran.r-project.org/web/packages/PanelMatch/refman/PanelMatch.html

Demonstrates setting up panel data, running PanelMatch with specific parameters, and then calculating and retrieving covariate balance using get_covariate_balance and get_unrefined_balance.

```R
dem$rdata <- runif(runif(nrow(dem)))
dem.panel <- PanelData(dem, "wbcode2", "year", "dem", "y")
pm.obj <- PanelMatch(lead = 0:3, lag = 4, refinement.method = "mahalanobis", 
                     panel.data = dem.panel, match.missing = TRUE,
                     covs.formula = ~ tradewb + rdata + I(lag(tradewb, 1:4)) + I(lag(y, 1:4)), 
                     size.match = 5, qoi = "att")

# create multiple configurations to compare
pm2 <- PanelMatch(lead = 0:3, lag = 4, refinement.method = "ps.match", 
                  panel.data = dem.panel, match.missing = TRUE,
                  covs.formula = ~ tradewb + rdata + I(lag(tradewb, 1:4)) + I(lag(y, 1:4)), 
                  size.match = 5, qoi = "att")

pb <- get_covariate_balance(pm.obj, pm2,
                            include.unrefined = TRUE,
                            panel.data = dem.panel, 
                            covariates = c("tradewb", "rdata"))
get_unrefined_balance(pb)
```

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

### PanelMatch Example with Data Preparation and Extraction

Source: https://cran.r-project.org/web/packages/PanelMatch/refman/PanelMatch.html

Demonstrates creating a subset of data, preparing it for PanelMatch, running the PanelMatch function with specified parameters, and then extracting the results using the extract function.

```R
dem.sub <- dem[dem[, "wbcode2"] <= 100, ]
dem.sub.panel <- PanelData(dem.sub, "wbcode2", "year", "dem", "y")
# create subset of data for simplicity
PM.results <- PanelMatch(panel.data = dem.sub.panel,
                         lag = 4,
                         refinement.method = "mahalanobis",
                         match.missing = TRUE,
                         covs.formula = ~ I(lag(tradewb, 1:4)) + I(lag(y, 1:4)),
                         size.match = 5, qoi = "att",
                         lead = 0:4, forbid.treatment.reversal = FALSE)
extract(PM.results, qoi = "att")
extract(PM.results) # valid since att is specified
```

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

### PanelMatch: Usage with PS Weight and Lagged Covariates

Source: https://cran.r-project.org/web/packages/PanelMatch/refman/PanelMatch.html

This example demonstrates using propensity score weighting with lagged covariates for matching. It's useful when past covariate values are important predictors.

```R
# include lagged variables
PM.results <- PanelMatch(panel.data = dem.sub.panel, lag = 4, 
                         refinement.method = "ps.weight", 
                         match.missing = TRUE, 
                         covs.formula = ~ tradewb + I(lag(tradewb, 1:4)) + I(lag(y, 1:4)),
                         size.match = 5, qoi = "att",
                         lead = 0:4, 
                         forbid.treatment.reversal = FALSE)
```

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

### Get Unrefined Balance

Source: https://cran.r-project.org/web/packages/PanelMatch/refman/PanelMatch.html

Extracts unrefined covariate balance results from a PanelMatch object. Use this if you want to specifically examine the balance before any refinement methods are applied.

```R
get_unrefined_balance(pb.object)
```

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

### Prepare Panel Data with PanelData()

Source: https://cran.r-project.org/web/packages/PanelMatch/vignettes/panelmatch-overview.Rmd

Initializes panel data by conducting error checks, balancing the panel, and creating a PanelData object. This simplifies later stages by storing metadata like time and unit identifiers, treatment, and outcome variables.

```r
library(PanelMatch)
dem.panel <- PanelData(panel.data = dem, 
                       unit.id = "wbcode2", 
                       time.id = "year", 
                       treatment = "dem", 
                       outcome = "y")
```

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

### Get Set Treatment Effects

Source: https://cran.r-project.org/web/packages/PanelMatch/refman/PanelMatch.html

Calculate the size of treatment effects for each matched set at specified future time periods. This function helps in understanding the impact of the treatment over time.

```R
dem.sub <- dem[dem[, "wbcode2"] <= 100, ]
dem.sub.panel <- PanelData(dem.sub, "wbcode2", "year", "dem", "y")
# create subset of data for simplicity
PM.results <- PanelMatch(panel.data = dem.sub.panel, lag = 4, 
                         refinement.method = "ps.match", 
                         match.missing = TRUE, 
                         covs.formula = ~ tradewb,
                         size.match = 5, qoi = "att",
                         lead = 0:4, 
                         forbid.treatment.reversal = FALSE)
set.effects <- get_set_treatment_effects(pm.obj = PM.results, 
                panel.data = dem.sub.panel, lead = 0)
```

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

### Get Covariate Balance

Source: https://cran.r-project.org/web/packages/PanelMatch/refman/PanelMatch.html

Calculate covariate balance for specified covariates across matched sets. Use this to assess the quality of your matching. Requires a PanelMatch object and the original panel data.

```R
get_covariate_balance(PM.results, panel.data = dem.sub.panel, covariates = c("tradewb", "rdata"))
```

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

### handle_bootstrap

Source: https://cran.r-project.org/web/packages/PanelMatch/refman/PanelMatch.html

Helper function for calculating non-parallelized bootstrapped estimates for the Quantity of Interest (QOI).

```APIDOC
## handle_bootstrap

### Description
Helper function for calculating bootstrapped estimates for the QOI. This version is not parallelized.

### Usage
```R
handle_bootstrap(
  qoi.in,
  data.in,
  lead,
  number.iterations,
  att.treated.unit.ids,
  atc.treated.unit.ids,
  outcome.variable,
  unit.id.variable,
  confidence.level,
  lag,
  pooled
)
```

### Arguments
* `qoi.in` (string): Specifies the Quantity of Interest (QOI).
* `data.in` (data.frame): The input data frame.
* `number.iterations` (integer): Specifies the number of bootstrap iterations.
* `att.treated.unit.ids` (integer vector): Specifies the treated units for the ATT or ATC.
* `atc.treated.unit.ids` (integer vector): Specifies the "treated" units under the ATC definition.
* `outcome.variable` (string): Specifies the name of the outcome variable.
* `unit.id.variable` (string): Specifies the name of the unit ID variable.
* `confidence.level` (double): Specifies the confidence level for the confidence interval.
* `lag` (integer vector): Specifies the size of the lag.
* `pooled` (logical): Specifies whether to calculate point estimates for each specified lead value or a single pooled estimate.

### Value
Returns a matrix of bootstrapped QOI estimate values.
```

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

### Parse and Prepare Data for Refinement

Source: https://cran.r-project.org/web/packages/PanelMatch/refman/PanelMatch.html

Prepares data for refinement based on a provided formula. It expects data with specific column orders for unit, time, and treatment.

```R
parse_and_prep(formula, data)
```

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

### Prepare Data for Panel Estimation

Source: https://cran.r-project.org/web/packages/PanelMatch/refman/PanelMatch.html

Prepares input data for PanelEstimate by calculating necessary weights, parameters, and indicator variables. Merges lower-level helper results with original data.

```R
prepare_data(
  data.in,
  lead,
  sets.att = NULL,
  sets.atc = NULL,
  qoi.in,
  dependent.variable
)
```

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

### Prepare Panel Data and Run PanelMatch

Source: https://cran.r-project.org/web/packages/PanelMatch/refman/PanelMatch.html

Prepares panel data and performs matching using PanelMatch. Requires specifying lead and lag periods, refinement method, and covariate formulas.

```r
dem$rdata <- runif(runif(nrow(dem)))
dem.panel <- PanelData(dem, "wbcode2", "year", "dem", "y")
pm.obj <- PanelMatch(lead = 0:3, lag = 4, refinement.method = "mahalanobis", 
                     panel.data = dem.panel, match.missing = TRUE,
                     covs.formula = ~ tradewb + rdata + I(lag(tradewb, 1:4)) + I(lag(y, 1:4)), 
                     size.match = 5, qoi = "att")
pb <- get_covariate_balance(pm.obj,
                            include.unrefined = TRUE,
                            panel.data = dem.panel, 
                            covariates = c("tradewb", "rdata"))
summary(pb)
```

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

### handle_bootstrap_parallel

Source: https://cran.r-project.org/web/packages/PanelMatch/refman/PanelMatch.html

Helper function for calculating parallelized bootstrapped estimates for the Quantity of Interest (QOI).

```APIDOC
## handle_bootstrap_parallel

### Description
Helper function for calculating bootstrapped estimates for the QOI. This version is parallelized.

### Usage
```R
handle_bootstrap_parallel(
  qoi.in,
  data.in,
  lead,
  number.iterations,
  att.treated.unit.ids,
  atc.treated.unit.ids,
  outcome.variable,
  unit.id.variable,
  confidence.level,
  lag,
  pooled,
  num.cores = 1
)
```

### Arguments
* `qoi.in` (string): Specifies the Quantity of Interest (QOI).
* `data.in` (data.frame): The input data frame.
* `number.iterations` (integer): Specifies the number of bootstrap iterations.
* `att.treated.unit.ids` (integer vector): Specifies the treated units for the ATT or ATC.
* `atc.treated.unit.ids` (integer vector): Specifies the "treated" units under the ATC definition.
* `outcome.variable` (string): Specifies the name of the outcome variable.
* `unit.id.variable` (string): Specifies the name of the unit ID variable.
* `confidence.level` (double): Specifies the confidence level for the confidence interval.
* `lag` (integer vector): Specifies the size of the lag.
* `pooled` (logical): Specifies whether to calculate point estimates for each specified lead value or a single pooled estimate.
* `num.cores` (integer, optional): Number of cores to be used for parallelization. Defaults to 1.

### Value
Returns a matrix of bootstrapped QOI estimate values.
```

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

### parse_and_prep

Source: https://cran.r-project.org/web/packages/PanelMatch/refman/PanelMatch.html

Prepares data for refinement by parsing a formula object and the data.

```APIDOC
## parse_and_prep

### Description
Accepts formula object and data, creates the data used for refinement.

### Usage
```
parse_and_prep(formula, data)
```

### Arguments
- `formula` (formula): Formula object specifying how to construct the data used for refinement. This is likely to be some variation of the `covs.formula` argument.
- `data` (data.frame): Data frame object to be used to create the data needed for refinement. `data` has unit, time, treatment columns in that order, followed by everything else.

### Value
Data frame object with the data prepared for refinement. Data will have unit, time, treatment columns in that order, followed by everything else.
```

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

### Print matched.set Objects in PanelMatch

Source: https://cran.r-project.org/web/packages/PanelMatch/refman/PanelMatch.html

Prints a summary of matched set sizes for a 'matched.set' object. Use 'verbose = TRUE' for raw list output or 'show.all = TRUE' to display all matched sets.

```R
dem.sub <- dem[dem[, "wbcode2"] <= 100, ]
# create subset of data for simplicity
dem.sub.panel <- PanelData(dem.sub, "wbcode2", "year", "dem", "y")
PM.results <- PanelMatch(panel.data = dem.sub.panel, lag = 4,
                        refinement.method = "ps.match",
                        match.missing = TRUE,
                        covs.formula = ~ tradewb,
                        size.match = 5, qoi = "att",
                        lead = 0:4,
                        forbid.treatment.reversal = FALSE)
print(extract(PM.results, qoi = "att"))
```

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

### Handle Bootstrap Estimates (Parallel)

Source: https://cran.r-project.org/web/packages/PanelMatch/refman/PanelMatch.html

A helper function for calculating bootstrapped estimates for the Quantity of Interest (QOI), optimized for parallel processing. Specify the number of cores to use for faster computation.

```R
handle_bootstrap_parallel(
  qoi.in,
  data.in,
  lead,
  number.iterations,
  att.treated.unit.ids,
  atc.treated.unit.ids,
  outcome.variable,
  unit.id.variable,
  confidence.level,
  lag,
  pooled,
  num.cores = 1
)
```

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

### prepare_data

Source: https://cran.r-project.org/web/packages/PanelMatch/refman/PanelMatch.html

Prepares data for PanelMatch by calculating weights, parameters, and indicator variables, merging them with original data.

```APIDOC
## prepare_data

### Description
prepare_data The calculation of point estimates and standard errors first requires the calculation of a variety of different weights, parameters, and indicator variables. This function prepares the data within PanelEstimate() such that the estimates can be calculated easily. In practical terms, the function calls the lower level helpers to calculate W_its and D_its as described in Imai et al. (2023) and merges those results together with the original data to facilitate calculations. 

### Usage
```R
prepare_data(
  data.in,
  lead,
  sets.att = NULL,
  sets.atc = NULL,
  qoi.in,
  dependent.variable
)

```

### Arguments
`data.in` |  data.frame: the data to be used in the analysis  
`lead` |  See PanelMatch() documentation  
`sets.att` |  matched.set object containing ATT or ART matched sets.  
`sets.atc` |  matched.set object containing ATC matched sets.  
`qoi.in` |  See PanelMatch() documentation  
`dependent.variable` |  string specifying the outcome/dependent variable.  

### Value
data.frame with the results of the lower level calculations
```

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

### handle_ps_match

Source: https://cran.r-project.org/web/packages/PanelMatch/refman/PanelMatch.html

Returns a matched.set object with weights for control units, along with some other metadata.

```APIDOC
## handle_ps_match

### Description
handle_ps_match Returns a matched.set object with weights for control units, along with some other metadata

### Usage
```R
handle_ps_match(just.ps.sets, msets, refinement.method, verbose, max.set.size)
```

### Arguments
`just.ps.sets` | Output from find_ps() function
---|---
`msets` | matched.set object – list containing the treated observations and matched controls
`verbose` | Logical. See PanelMatch() documentation
`max.set.size` | maximum number of control units that will receive non-zero weights within a matched set

### Value
matched.set object with weights for control units, along with some other metadata
```

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

### Estimate using Imai, Kim, and Wang (2023)

Source: https://cran.r-project.org/web/packages/PanelMatch/refman/PanelMatch.html

A small helper function implementing the estimation function from Imai, Kim, and Wang (2023).

```r
equality_four(x, y, z)
```

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

### Pre-process Panel Data with PanelData

Source: https://cran.r-project.org/web/packages/PanelMatch/refman/PanelMatch.html

Prepares panel data for analysis by identifying unit IDs, time IDs, treatment indicators, and outcome variables. Requires a data.frame with sequential time data and integer unit identifiers.

```R
PanelData(panel.data, unit.id, time.id, treatment, outcome)
```

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

### Prepare Control Units Data Frames

Source: https://cran.r-project.org/web/packages/PanelMatch/refman/PanelMatch.html

Helper functions to create data frames for control and treated units, containing time/ID combinations and weights. These are used for efficient lookup and assignment of weights.

```R
pcs(control_units, weights, unit_id_col, time_id_col)
pts(treated_units, weights, unit_id_col, time_id_col)
```

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

### Prepare and Match Panel Data

Source: https://cran.r-project.org/web/packages/PanelMatch/refman/PanelMatch.html

Prepares panel data and performs matching using PanelMatch. Ensure your data is correctly formatted and specify matching parameters like lag, refinement method, and covariates.

```r
dem.sub <- dem[dem[, "wbcode2"] <= 100, ]
dem.sub.panel <- PanelData(dem.sub, "wbcode2", "year", "dem", "y")
PM.results <- PanelMatch(panel.data = dem.sub.panel, 
                         lag = 4, 
                         refinement.method = "mahalanobis",
                         match.missing = TRUE,
                         covs.formula = ~ I(lag(tradewb, 1:4)) + I(lag(y, 1:4)),
                         size.match = 5, qoi = "att",
                         lead = 0:4, forbid.treatment.reversal = FALSE)
summary(PM.results)
```

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

### Prepare Data for Estimation

Source: https://cran.r-project.org/web/packages/PanelMatch/refman/PanelMatch.html

Prepares the data within `PanelEstimate()` by calculating necessary weights, parameters, and indicator variables. This function calls lower-level helpers to compute W_its and D_its and merges them with the original data for easier estimation.

```APIDOC
## prepare_data The calculation of point estimates and standard errors first requires the calculation of a variety of different weights, parameters, and indicator variables. This function prepares the data within PanelEstimate() such that the estimates can be calculated easily. In practical terms, the function calls the lower level helpers to calculate W_its and D_its as described in Imai et al. (2023) and merges those results together with the original data to facilitate calculations.

```

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

### PanelMatch: Basic Usage with PS Match

Source: https://cran.r-project.org/web/packages/PanelMatch/refman/PanelMatch.html

Use this snippet to perform propensity score matching for panel data. Ensure your panel data is correctly formatted and specify the desired quantity of interest (qoi).

```R
dem.sub <- dem[dem[, "wbcode2"] <= 100, ]
dem.sub.panel <- PanelData(dem.sub, "wbcode2", "year", "dem", "y")
# create subset of data for simplicity
PM.results <- PanelMatch(panel.data = dem.sub.panel, lag = 4, 
                         refinement.method = "ps.match", 
                         match.missing = TRUE, 
                         covs.formula = ~ tradewb,
                         size.match = 5, qoi = "att",
                         lead = 0:4, 
                         forbid.treatment.reversal = FALSE)
```

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

### Parallelized Bootstrap Placebo Test Helper

Source: https://cran.r-project.org/web/packages/PanelMatch/refman/PanelMatch.html

Use for calculating bootstrapped estimates for placebo tests in parallel. Requires specifying QOI, data, placebo lead, number of iterations, treated unit IDs, outcome and unit ID variables, confidence level, lag, and number of cores.

```R
handle_bootstrap_placebo_parallel(
  qoi.in,
  data.in,
  placebo.lead,
  number.iterations,
  att.treated.unit.ids,
  atc.treated.unit.ids,
  outcome.variable,
  unit.id.variable,
  confidence.level,
  lag,
  num.cores = 1
)
```

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

### Extract Matched Sets (S3 Method) - extract

Source: https://cran.r-project.org/web/packages/PanelMatch/refman/PanelMatch.html

S3 method for extracting matched.set objects from PanelMatch results. Defaults to 'att' if qoi is not specified and att, art, or atc results are available.

```R
extract(pm.object, qoi = NULL)
```

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

### Prepare Data for Panel Estimation

Source: https://cran.r-project.org/web/packages/PanelMatch/refman/PanelMatch.html

Prepares data within `PanelEstimate` by calculating necessary weights, parameters, and indicator variables. This function calls lower-level helpers to compute W_its and D_its and merges them with the original data.

```R
prepare_data
```

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

### print.matched.set

Source: https://cran.r-project.org/web/packages/PanelMatch/refman/PanelMatch.html

Prints matched.set objects, providing an overview or detailed summary of matched set sizes.

```APIDOC
## Print matched.set objects.
### Description
Print matched.set objects. 
### Usage
```
## S3 method for class 'matched.set'
print(x, ..., verbose = FALSE, n = 5, show.all = FALSE)

```

### Arguments
`x` |  a `matched.set` object  
---|---
`...` |  Not used. additional arguments to be passed to `print`  
`verbose` |  logical indicating whether or not output should be printed in expanded/raw list form. The verbose form is not recommended unless the data set is small. Default is FALSE, which prints an overview of matched set sizes.  
`n` |  Integer. Integer. Number of matched sets to display information about as a preview. Default is 5.  
`show.all` |  Logical. By default ('show.all = FALSE'), the print method only shows a small preview of the sizes of matched sets. When set to TRUE, a full summary description of matched set sizes is shown.  
### Value
Returns nothing, but prints information about matched sets: treated observation IDs, the time of treatment, and the size of matched sets. 
### Examples
```
dem.sub <- dem[dem[, "wbcode2"] <= 100, ]
# create subset of data for simplicity
dem.sub.panel <- PanelData(dem.sub, "wbcode2", "year", "dem", "y")
PM.results <- PanelMatch(panel.data = dem.sub.panel, lag = 4,
                        refinement.method = "ps.match",
                        match.missing = TRUE,
                        covs.formula = ~ tradewb,
                        size.match = 5, qoi = "att",
                        lead = 0:4,
                        forbid.treatment.reversal = FALSE)
print(extract(PM.results, qoi = "att"))




```
```

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

### Prepare Panel Data with PanelData()

Source: https://cran.r-project.org/web/packages/PanelMatch/refman/PanelMatch.html

Use PanelData() to format panel data for analysis. It balances and sorts the data, noting these properties in attributes. It also stores mappings for converted time data.

```r
d <- PanelData(panel.data = dem, 
               unit.id = "wbcode2", 
               time.id = "year", 
               treatment = "dem", 
               outcome = "y")
```

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

### Handle Bootstrap Estimates (Non-Parallel)

Source: https://cran.r-project.org/web/packages/PanelMatch/refman/PanelMatch.html

A helper function for calculating bootstrapped estimates for the Quantity of Interest (QOI). This version is not parallelized. It requires detailed input on the data, treatment units, and outcome variables.

```R
handle_bootstrap(
  qoi.in,
  data.in,
  lead,
  number.iterations,
  att.treated.unit.ids,
  atc.treated.unit.ids,
  outcome.variable,
  unit.id.variable,
  confidence.level,
  lag,
  pooled
)
```

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

### Handle PS Match Function

Source: https://cran.r-project.org/web/packages/PanelMatch/refman/PanelMatch.html

Use this function to return a matched.set object with weights for control units. It requires the output from the find_ps() function and a matched.set object.

```R
handle_ps_match(just.ps.sets, msets, refinement.method, verbose, max.set.size)
```

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

### Create Matched Sets with PanelMatch() (PS Weight)

Source: https://cran.r-project.org/web/packages/PanelMatch/vignettes/panelmatch-overview.Rmd

Creates and refines matched sets using the propensity score weighting method. This function requires specifying covariates, lag periods, and other matching parameters.

```r
PM.ps.weight <- PanelMatch(lag = 4, 
                      refinement.method = "ps.weight",
                      panel.data = dem.panel, 
                      match.missing = FALSE, 
                      covs.formula = ~ I(lag(tradewb, 0:4)) + 
                                       I(lag(y, 1:4)),
                      qoi = "att", 
                      lead = 0:2,
                      use.diagonal.variance.matrix = TRUE,
                      forbid.treatment.reversal = FALSE)
```

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

### getWits

Source: https://cran.r-project.org/web/packages/PanelMatch/refman/PanelMatch.html

Returns a vector of Wit values.

```APIDOC
## getWits returns a vector of Wits, as defined in the paper (equation 25 or equation 23). They should be in the same order as the data frame containing the original problem data. The pts, pcs, and getWits functions act for a specific lead. So, for instance if our lead window is 0,1,2,3,4, these function must be called for each of those – so for 0, then for 1, etc.

### Description
getWits returns a vector of Wits, as defined in the paper (equation 25 or equation 23). They should be in the same order as the data frame containing the original problem data. The pts, pcs, and getWits functions act for a specific lead. So, for instance if our lead window is 0,1,2,3,4, these function must be called for each of those – so for 0, then for 1, etc. 

### Usage
```
getWits(matched_sets, lead, data, estimation.method = "bootstrap")

```
```

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

### print.PanelBalance

Source: https://cran.r-project.org/web/packages/PanelMatch/refman/PanelMatch.html

Prints covariate balance information for PanelMatch configurations within a PanelBalance object.

```APIDOC
## Print basic information about PanelBalance objects

### Description
This function prints out covariate balance information for all of the PanelMatch configurations specified within a PanelBalance object. Specifically it prints out the name of the PanelMatch object(s), and covariate balance measures over the specified time period after refinement. If no refinement was applied, then these unrefined results will be shown. 

### Usage
```R
## S3 method for class 'PanelBalance'
print(x, ...)

```

### Arguments
`x` |  `PanelBalance` object  
`...` |  Not used  

### Value
Nothing 
### Examples
```R
dem$rdata <- runif(runif(nrow(dem)))
dem.panel <- PanelData(dem, "wbcode2", "year", "dem", "y")
pm.obj <- PanelMatch(lead = 0:3, lag = 4, refinement.method = "mahalanobis", 
                     panel.data = dem.panel, match.missing = TRUE,
                     covs.formula = ~ tradewb + rdata + I(lag(tradewb, 1:4)) + I(lag(y, 1:4)), 
                     size.match = 5, qoi = "att")
pb <- get_covariate_balance(pm.obj,
                            include.unrefined = TRUE,
                            panel.data = dem.panel, 
                            covariates = c("tradewb", "rdata"))
print(pb)

```
```

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

### print.PanelMatch

Source: https://cran.r-project.org/web/packages/PanelMatch/refman/PanelMatch.html

Prints PanelMatch objects, showing information about matched sets.

```APIDOC
## Print PanelMatch objects.

### Description
Print PanelMatch objects. 

### Usage
```R
## S3 method for class 'PanelMatch'
print(x, ..., verbose = FALSE, n = 5, show.all = FALSE)

```

### Arguments
`x` |  a `PanelMatch` object  
`...` |  additional arguments to be passed to `print.matched.set`  
`verbose` |  logical indicating whether or not underlying data should be printed in expanded/raw list form. The verbose form is not recommended unless the data set is small. Default is FALSE  
`n` |  Integer. Number of matched sets to display information about as a preview. Default is 5.  
`show.all` |  Logical. By default ('show.all = FALSE'), the print method only shows a small preview of the sizes of matched sets. When set to TRUE, a full summary description of matched set sizes is shown.  

```

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

### estimates (PanelEstimate method)

Source: https://cran.r-project.org/web/packages/PanelMatch/refman/PanelMatch.html

Extracts QOI (Quantity of Governance) estimates from PanelEstimate objects. This method is analogous to the 'coef()' method.

```APIDOC
## Extract QOI estimates

### Description
This is a method for extracting point estimates for the QOI from `PanelEstimate` objects. This function is analogous to the 'coef()' method used elsewhere. 

### Usage
```
## S3 method for class 'PanelEstimate'
estimates(object, ...)
```

### Arguments
`object` | `PanelEstimate` object
`...` | not used
```

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

### print.PanelData

Source: https://cran.r-project.org/web/packages/PanelMatch/refman/PanelMatch.html

Prints PanelData objects and their basic metadata.

```APIDOC
## Print PanelData objects and basic metadata

### Description
Print PanelData objects and basic metadata 

### Usage
```R
## S3 method for class 'PanelData'
print(x, ..., n = 5, verbose = FALSE)

```

### Arguments
`x` |  `PanelData` object  
`...` |  additional arguments to be passed to `print.data.frame()`  
`n` |  Integer. Number of rows to print by default for previewing data. Default is 5.  
`verbose` |  Logical. Print the entire data frame, rather than just a preview. Default is FALSE.  

### Value
Returns nothing but prints `PanelData` object. This is a data frame that has been balanced, sorted, and tagged with important metadata to facilitate the use of other functions. 
### Examples
```R
d <- PanelData(dem, "wbcode2", "year", "dem", "y")
print(d)


```
```

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

### Matched Set Constructor

Source: https://cran.r-project.org/web/packages/PanelMatch/refman/PanelMatch.html

Constructs a 'matched.set' object. This function is typically not used directly by users but is part of the PanelMatch workflow. It stores matching parameters and results.

```R
matched_set(matchedsets, id, t, L, t.var, id.var, treatment.var)
```

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

### matched_set Constructor

Source: https://cran.r-project.org/web/packages/PanelMatch/refman/PanelMatch.html

Constructs a 'matched.set' object, which represents matched treated and control units.

```APIDOC
## matched_set

### Description
A constructor for the matched.set class. Users should never need to use this function by itself. See below for more about `matched.set` objects.

### Usage
```
matched_set(matchedsets, id, t, L, t.var, id.var, treatment.var)
```

### Arguments
- `matchedsets` (list): A list of treated units and matched control units. Each element in the list should be a vector of control unit ids.
- `id` (vector): A vector containing the ids of treated units.
- `t` (vector): A vector containing the times of treatment for treated units.
- `L` (integer): Specifies the length of the lag window used in matching.
- `t.var` (string): Specifies the time variable.
- `id.var` (string): Specifies the unit id variable.
- `treatment.var` (string): Specifies the treatment variable.

### Value
`matched.set` objects have additional attributes reflecting the specified parameters when using the `PanelMatch` function:
- `lag` (integer): Length of treatment history used for matching.
- `t.var` (string): Time variable name.
- `id.var` (string): Unit id variable name.
- `treatment.var` (string): Treatment variable name.
- `class` (string): Class of the object, should always be "matched.set".
- `refinement.method` (any): Method used to refine and/or weight the control units in each set.
- `covs.formula` (formula): One-sided formula indicating variables for matching and refinement.
- `match.missing` (logical): Indicates whether units should be matched on patterns of missingness in treatment histories.
- `max.match.size` (integer): Maximum size of matched sets after refinement.
```

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

### enforce_lead_restrictions

Source: https://cran.r-project.org/web/packages/PanelMatch/refman/PanelMatch.html

Checks treatment and control units for treatment reversion in the lead window. Treated units must remain treated and control units must remain in control according to the specified quantity of governance (qoi).

```APIDOC
## enforce_lead_restrictions

### Description
enforce_lead_restrictions check treatment and control units for treatment reversion in the lead window. Treated units must stay treated and control units must stay in control (according to the specified qoi)

### Usage
```
enforce_lead_restrictions(
  matched_sets,
  ordered.data,
  max.lead,
  t.var,
  id.var,
  treatment.var
)
```

### Arguments
`matched_sets` | matched.set object
`ordered.data` | parsed data as data.frame object
`max.lead` | The largest lead value (e.g. the biggest F)
`t.var` | string specifying the time variable
`id.var` | string specifying the unit id variable
`treatment.var` | string specifying the treatment variable.

### Value
matched.set object with the matched sets that meet the conditions
```

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

### Check Treatment Reversion in Lead Window

Source: https://cran.r-project.org/web/packages/PanelMatch/refman/PanelMatch.html

Checks treatment and control units for reversion in the lead window. Treated units must remain treated and control units must remain in control according to the specified quantity of governance (qoi).

```r
enforce_lead_restrictions(
  matched_sets,
  ordered.data,
  max.lead,
  t.var,
  id.var,
  treatment.var
)
```

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

### Print PanelData Objects and Metadata

Source: https://cran.r-project.org/web/packages/PanelMatch/refman/PanelMatch.html

Prints PanelData objects along with basic metadata. Allows previewing a specified number of rows or the entire data frame if verbose is TRUE.

```R
d <- PanelData(dem, "wbcode2", "year", "dem", "y")
print(d)
```

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

### handle_mahalanobis_calculations

Source: https://cran.r-project.org/web/packages/PanelMatch/refman/PanelMatch.html

Returns a matched.set object with weights for control units, along with some other metadata.

```APIDOC
## handle_mahalanobis_calculations Returns a matched.set object with weights for control units, along with some other metadata

### Description
handle_mahalanobis_calculations Returns a matched.set object with weights for control units, along with some other metadata

### Usage
```R
handle_mahalanobis_calculations(
  mahal.nested.list,
  msets,
  max.size,
  verbose,
  use.diagonal.covmat
)
```

### Arguments
`mahal.nested.list` | Output from build_maha_mats function
`msets` | matched.set object – list containing the treated observations and matched controls
`max.size` | maximum number of control units that will receive non-zero weights within a matched set
`verbose` | Logical. See PanelMatch() documentation
`use.diagonal.covmat` | Logical. See PanelMatch() documentation

### Value
matched.set object with weights for control units, along with some other metadata
```

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

### Prepare Control Units Data Frame

Source: https://cran.r-project.org/web/packages/PanelMatch/refman/PanelMatch.html

Prepares data frames for control units (pcs) and treated units (pts) by creating time-id combinations for efficient lookup and weight assignment.

```R
pcs(sets, lead.in)
```

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

### expand_treated_ts

Source: https://cran.r-project.org/web/packages/PanelMatch/refman/PanelMatch.html

Builds a list that contains all times in a lag window that correspond to a particular treated unit. This is structured as a list of vectors. Each vector is lag + 1 units long. The overall list will be the same length as the number of matched sets.

```APIDOC
## expand_treated_ts

### Description
expand_treated_ts Builds a list that contains all times in a lag window that correspond to a particular treated unit. This is structured as a list of vectors. Each vector is lag + 1 units long. The overall list will be the same length as the number of matched sets 

### Usage
```R
expand_treated_ts(lag, treated.ts)
```

### Arguments
`lag` |  lag value  
---|---  
`treated.ts` |  times of treated observations  

### Value
list. Contains all times in a lag window that correspond to a particular treated unit
```

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

### summary.matched.set

Source: https://cran.r-project.org/web/packages/PanelMatch/refman/PanelMatch.html

Summarizes information about a matched.set object and the matched sets contained within them. This method provides data on the sizes of matched sets and metadata about their creation.

```APIDOC
## summary.matched.set

### Description
Summarize information about a matched.set object and the matched sets contained within them.

### Usage
```R
## S3 method for class 'matched.set'
summary(object, ..., verbose = TRUE)
```

### Arguments
- `object`: A `matched.set` object.
- `...`: Optional additional arguments to be passed to the `summary` function.
- `verbose`: Logical value specifying whether or not a longer, more verbose summary should be calculated and returned. Default is TRUE.

### Value
A list object with either 5 or 1 element(s), depending on whether or not `verbose` is set to TRUE or not.
- `overview`: A `data.frame` object containing information about the treated units (unit id, time of treatment), and the number of matched control units with weights zero and above.
- `set.size.summary`: A `summary` object summarizing the minimum, maximum, and IQR of matched set sizes.
- `number.of.treated.units`: The number of unit, time pairs that are considered to be "treated" units.
- `num.units.empty.set`: The number of units treated at a particular time that were not able to be matched to any control units.
- `lag`: The size of the lag window used for matching on treatment history.

### Examples
```R
dem.sub <- dem[dem[, "wbcode2"] <= 100, ]
dem.sub.panel <- PanelData(dem.sub, "wbcode2", "year", "dem", "y")
# create subset of data for simplicity
PM.results <- PanelMatch(lag = 4, refinement.method = "ps.match",
                         panel.data = dem.sub.panel, match.missing = TRUE,
                         covs.formula = ~ I(lag(tradewb, 1:4)) + I(lag(y, 1:4)),
                         size.match = 5, qoi = "att",
                         lead = 0:4, forbid.treatment.reversal = FALSE)
summary(extract(PM.results, qoi = "att"))
```
```

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

### extract

Source: https://cran.r-project.org/web/packages/PanelMatch/refman/PanelMatch.html

Extract matched.set objects from PanelMatch results.

```APIDOC
## extract

### Description
Extract matched.set objects from PanelMatch results 

### Usage
```R
## S3 method for class 'PanelMatch'
extract(pm.object, qoi = NULL)
```

### Arguments
`pm.object` |  `PanelMatch` obect  
---|---  
`qoi` |  character, specifying the qoi. Valid inputs include "att", "atc", "art", and NULL. If NULL, function extracts att, art, or atc results if possible. Otherwise, throws an error if ate is specified.  

### Value
a `matched.set` object 

### Examples
```R
dem.sub <- dem[dem[, "wbcode2"] <= 100, ]
dem.sub.panel <- PanelData(dem.sub, "wbcode2", "year", "dem", "y")
# create subset of data for simplicity
PM.results <- PanelMatch(panel.data = dem.sub.panel,
                         lag = 4, 
                         refinement.method = "mahalanobis",
                         match.missing = TRUE,
                         covs.formula = ~ I(lag(tradewb, 1:4)) + I(lag(y, 1:4)),
                         size.match = 5, qoi = "att",
                         lead = 0:4, forbid.treatment.reversal = FALSE)
extract(PM.results, qoi = "att")
extract(PM.results) # valid since att is specified
```
```

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

### PanelMatch: Perform Panel Matching

Source: https://cran.r-project.org/web/packages/PanelMatch/refman/PanelMatch.html

Use PanelMatch to find optimal treatment and control units in panel data. Requires data to be pre-processed with PanelData. Specify matching parameters like lag, refinement method, and covariates.

```R
dem.sub <- dem[dem[, "wbcode2"] <= 100, ]
dem.sub.panel <- PanelData(dem, 'wbcode2', 'year', 'dem', 'y')
PM.results <- PanelMatch(panel.data = dem.sub.panel,
                         lag = 4,
                         refinement.method = "mahalanobis",
                         match.missing = TRUE,
                         covs.formula = ~ I(lag(tradewb, 1:4)) + I(lag(y, 1:4)),
                         size.match = 5, qoi = "att",
                         lead = 0:4, forbid.treatment.reversal = FALSE)
print(PM.results)
```

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

### Plot Control Unit Weights with PanelMatch

Source: https://cran.r-project.org/web/packages/PanelMatch/refman/PanelMatch.html

Generates a heatmap visualizing the weights or distances of control units within matched sets for treated observations. Requires a `matched.set` object and `PanelData`. Customize colors for low, mid, high, and missing values.

```R
dem.panel <- PanelData(dem, "wbcode2", "year", "dem", "y")
PM.results <- PanelMatch(panel.data = dem.panel, lag = 4,
                       refinement.method = "ps.match",
                       match.missing = TRUE,
                       covs.formula = ~ tradewb,
                       size.match = 5, qoi = "att",
                       lead = 0:4,
                       forbid.treatment.reversal = FALSE)

mso <- extract(PM.results)
plot(mso, panel.data = dem.panel)
```

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

### Calculate Point Estimates Helper Function

Source: https://cran.r-project.org/web/packages/PanelMatch/refman/PanelMatch.html

A helper function to calculate the point estimates for a specified Quantity of Interest (QOI). It takes processed data and lead information as input.

```R
calculate_point_estimates(
  qoi.in,
  data.in,
  lead,
  outcome.variable,
  pooled = FALSE
)
```

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

### Create Matched Sets with PanelMatch() (Mahalanobis)

Source: https://cran.r-project.org/web/packages/PanelMatch/vignettes/panelmatch-overview.Rmd

Creates and refines matched sets using the Mahalanobis distance refinement method. This function requires specifying covariates, lag periods, and other matching parameters.

```r
PM.maha <- PanelMatch(panel.data = dem.panel, 
                      lag = 4, 
                      refinement.method = "mahalanobis",
                      match.missing = FALSE, 
                      covs.formula = ~ I(lag(tradewb, 0:4)) + 
                                       I(lag(y, 1:4)),
                      size.match = 5, 
                      qoi = "att", 
                      lead = 0:2,
                      use.diagonal.variance.matrix = TRUE,
                      forbid.treatment.reversal = FALSE)
```

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

### Calculate Wit Values

Source: https://cran.r-project.org/web/packages/PanelMatch/refman/PanelMatch.html

Returns a vector of Wit values, as defined in the paper (equation 25 or 23). This function is called for a specific lead period and requires matched sets, the lead value, and the data.

```r
getWits(matched_sets, lead, data, estimation.method = "bootstrap")
```

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

### Calculate Per-Unit Summation for Dit

Source: https://cran.r-project.org/web/packages/PanelMatch/refman/PanelMatch.html

A low-level helper function similar to perunitSum, specifically for calculating values defined in Imai et al. (2023) focusing on Dit.

```R
perunitSum_Dit(udf, qoi_in)
```

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

### pcs Function

Source: https://cran.r-project.org/web/packages/PanelMatch/refman/PanelMatch.html

Prepares control unit data frames with time/id combinations and weights for efficient lookup.

```APIDOC
## pcs Function

### Description
Prepare Control Units pcs and pts create data frames with the time/id combinations–that need to be found so that they can be easily looked up in the data frame via a hash table. The data frame also contains information about the weight of that unit at particular times, so we use the hash table to look up where to put this data so that we can easily assign the appropriate weights in the original data frame containing the problem data. pcs does this for all control units in a matched set.

### Usage
```R
pcs(sets, lead.in)
```

### Arguments
`sets` | object describing the matched sets
`lead.in` | integer describing a particular lead value.

### Value
data.frame object with time-id combinations
```

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

### PanelMatch: Subset PanelBalance Objects

Source: https://cran.r-project.org/web/packages/PanelMatch/refman/PanelMatch.html

Subset a PanelBalance object to extract balance information for specific PanelMatch configurations. Use this to compare different matching strategies.

```R
dem$rdata <- runif(runif(nrow(dem)))
dem.panel <- PanelData(dem, "wbcode2", "year", "dem", "y")
pm.obj <- PanelMatch(lead = 0:3, lag = 4, refinement.method = "mahalanobis", 
                     panel.data = dem.panel, match.missing = TRUE,
                     covs.formula = ~ tradewb + rdata + I(lag(tradewb, 1:4)) + I(lag(y, 1:4)), 
                     size.match = 5, qoi = "att")

# create multiple configurations to compare
pm2 <- PanelMatch(lead = 0:3, lag = 4, refinement.method = "ps.match", 
                  panel.data = dem.panel, match.missing = TRUE,
                  covs.formula = ~ tradewb + rdata + I(lag(tradewb, 1:4)) + I(lag(y, 1:4)), 
                  size.match = 5, qoi = "att")

pb <- get_covariate_balance(pm.obj, pm2,
                            include.unrefined = TRUE,
                            panel.data = dem.panel, 
                            covariates = c("tradewb", "rdata"))
bal.maha <- pb[1]
bal.ps <- pb[2]
```

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

### PanelData

Source: https://cran.r-project.org/web/packages/PanelMatch/refman/PanelMatch.html

Pre-processes and balances panel data for use in analysis.

```APIDOC
## PanelData

### Description
Pre-process and balance panel data.

### Usage
```R
PanelData(panel.data, unit.id, time.id, treatment, outcome)
```

### Arguments
- **panel.data** (`data.frame`): A data frame containing time series cross sectional data. Time data should be sequential integers. Unit identifiers must be integers. Treatment data must be binary.
- **unit.id** (character string): The name of the unit identifier column. Must be integer.
- **time.id** (character string): The name of the time variable column.
- **treatment** (character string): The name of the treatment variable column. Must be a binary indicator (0 or 1).
- **outcome** (character string): The name of the outcome variable column.

### Value
Returns a `PanelData` object.
```

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

### Print Covariate Balance for PanelBalance Objects

Source: https://cran.r-project.org/web/packages/PanelMatch/refman/PanelMatch.html

Prints covariate balance information for PanelMatch configurations within a PanelBalance object. Shows balance measures over the specified time period after refinement, or unrefined results if no refinement was applied.

```R
dem$rdata <- runif(runif(nrow(dem)))
dem.panel <- PanelData(dem, "wbcode2", "year", "dem", "y")
pm.obj <- PanelMatch(lead = 0:3, lag = 4, refinement.method = "mahalanobis", 
                     panel.data = dem.panel, match.missing = TRUE,
                     covs.formula = ~ tradewb + rdata + I(lag(tradewb, 1:4)) + I(lag(y, 1:4)), 
                     size.match = 5, qoi = "att")
pb <- get_covariate_balance(pm.obj,
                            include.unrefined = TRUE,
                            panel.data = dem.panel, 
                            covariates = c("tradewb", "rdata"))
print(pb)
```

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

### PanelMatch: Matching and Estimation

Source: https://cran.r-project.org/web/packages/PanelMatch/refman/PanelMatch.html

Performs matching and estimation for panel data. Requires a PanelData object and specifies matching parameters like refinement method, covariates, and quantity of interest. Use placebo tests to assess robustness.

```R
dem.sub <- dem[dem[, "wbcode2"] <= 100, ]
dem.sub.panel <- PanelData(dem.sub, "wbcode2", "year", "dem", "y")
# create subset of data for simplicity
PM.results <- PanelMatch(panel.data = dem.sub.panel, lag = 4, 
                         refinement.method = "ps.match", 
                         match.missing = TRUE, 
                         covs.formula = ~ tradewb,
                         size.match = 5, qoi = "att",
                         lead = 0:4, 
                         forbid.treatment.reversal = FALSE, placebo.test = TRUE)
placebo_test(PM.results, panel.data = dem.sub.panel, se.method = "unconditional", plot = FALSE)
```