### Example: Bivariate Probit Model Setup

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

Sets up a simulated dataset and estimates a bivariate probit model using `vglm` from the `VGAM` package. This example is a prerequisite for demonstrating `invMillsRatio` with bivariate models.

```R
library( "mvtnorm" )
library( "VGAM" )
nObs <- 1000

# error terms (trivariate normal)
sigma <- symMatrix( c( 2, 0.7, 1.2, 1, 0.5, 1 ) )
myData <- as.data.frame( rmvnorm( nObs, c( 0, 0, 0 ), sigma ) )
names( myData ) <- c( "e0", "e1", "e2" )

# exogenous variables (indepently normal)
myData$x0 <- rnorm( nObs )
myData$x1 <- rnorm( nObs )
myData$x2 <- rnorm( nObs )

# endogenous variables
myData$y0 <-   -1.5 + 0.8 * myData$x1 + myData$e0
myData$y1 <- (  0.3 + 0.4 * myData$x1 + 0.3 * myData$x2 + myData$e1 ) > 0
myData$y2 <- ( -0.1 + 0.6 * myData$x1 + 0.7 * myData$x2 + myData$e2 ) > 0

# bivariate probit (using rhobit transformation)
bProbit <- vglm( cbind( y1, y2 ) ~ x1 + x2, family = binom2.rho,
   data = myData )
summary( bProbit )
```

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

### R Example: Summarizing Selection Model Results

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

Demonstrates how to fit a sample selection model using the `selection` function and then summarize the results. It shows how to get a full summary and a summary of only the outcome equation.

```r
## Wooldridge( 2003 ): example 17.5, page 590
data( Mroz87 )
wooldridge <- selection( lfp ~ nwifeinc + educ + exper + I( exper^2 ) +
   age + kids5 + kids618, log( wage ) ~ educ + exper + I( exper^2 ),
   data = Mroz87, method = "2step" )

# summary of the 1st step probit estimation (Example 17.1, p. 562f)
# and the 2nd step OLS regression (example 17.5, page 590)
summary( wooldridge )
```

```r
# summary of the outcome equation only
print(summary(wooldridge), part="outcome")
```

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

### Handling Convergence Issues with Start Values

Source: https://cran.r-project.org/web/packages/sampleSelection/vignettes/selection.Rnw

Illustrates how to specify start values for the selection model to address potential convergence problems. This is crucial when the log-likelihood function is not globally concave.

```R
greeneStart <- selection( lfp ~ age + I( age^2 ) + faminc + kids + educ,
   wage ~ exper + I( exper^2 ) + educ + city,
   data = Mroz87, start = c(0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0.5, 0.9))

cat( greeneStart$message )

```

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

### Compare Starting Values and Coefficients in R

Source: https://cran.r-project.org/web/packages/sampleSelection/vignettes/intReg.Rnw

Compares the starting values and estimated coefficients from two different estimation methods (ML and two-step) for sample selection models.

```R
# compare starting values (small differences)
cbind( res$start, res2$start, res$start - res2$start )
```

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

### Load and Prepare Data for Greene Example

Source: https://cran.r-project.org/web/packages/sampleSelection/vignettes/selection.Rnw

Loads the Mroz87 dataset and creates a binary variable for the presence of children. This is a prerequisite for the Greene (2002) example.

```r
data( "Mroz87" )
Mroz87$kids <- ( Mroz87$kids5 + Mroz87$kids618 > 0 )
```

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

### Tobit-2 Example with Random Numbers

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

Demonstrates the tobit-2 model using randomly generated data. Requires the `mvtnorm` package.

```R
   vc <- diag(2)
   vc[2,1] <- vc[1,2] <- -0.7
   eps <- rmvnorm(N, rep(0, 2), vc)
   xs <- runif(N)
   ys <- xs + eps[,1] > 0
   xo <- runif(N)
   yo <- (xo + eps[,2])*(ys > 0)
   a <- selection(ys~xs, yo ~xo)
   summary(a)
```

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

### Estimate and Extract All Coefficients

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

This example demonstrates estimating a sample selection model using `heckit` and then extracting all coefficients using `coef(a)`.

```R
## Estimate a simple female wage model taking into account the labour
## force participation
   data(Mroz87)
   a <- heckit(lfp ~ huswage + kids5 + mtr + fatheduc + educ + city,
               log(wage) ~ educ + city, data=Mroz87)
## extract all coefficients of the model:
coef( a )
```

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

### Tobit-5 Example with Random Numbers

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

Illustrates the tobit-5 model using randomly generated data. Requires the `mvtnorm` package.

```R
N <- 500
   library(mvtnorm)
   vc <- diag(3)
   vc[lower.tri(vc)] <- c(0.9, 0.5, 0.6)
   vc[upper.tri(vc)] <- vc[lower.tri(vc)]
   eps <- rmvnorm(N, rep(0, 3), vc)
   xs <- runif(N)
   ys <- xs + eps[,1] > 0
   xo1 <- runif(N)
   yo1 <- xo1 + eps[,2]
   xo2 <- runif(N)
   yo2 <- xo2 + eps[,3]
   a <- selection(ys~xs, list(yo1 ~ xo1, yo2 ~ xo2))
   summary(a)
```

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

### Sample Selection Model with Provided Start Values (Smoke Data)

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

Estimates a sample selection model using the 'Smoke' dataset with specific starting values. This is useful for reducing execution time and ensuring convergence.

```R
bounds <- c(0,5,10,20,50,Inf)
# estimation with starting values that are very close to the estimates
# (in order to reduce the execution time of running this example) 
resS <- selection( smoker ~ educ + age, cigs_intervals ~ educ, 
  data = Smoke, boundaries = bounds, 
  start = c( 0.527, -0.0482, -0.0057, 4.23, -0.319, 2.97, 2.245 ) )
summary( resS )
```

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

### Cameron and Trivedi Example

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

Demonstrates ML estimation for a sample selection model using the RandHIE dataset. Requires specifying selection and outcome equations.

```R
data( RandHIE )
subsample <- RandHIE$year == 2 & !is.na( RandHIE$educdec )
selectEq <- binexp ~ logc + idp + lpi + fmde + physlm + disea +
   hlthg + hlthf + hlthp + linc + lfam + educdec + xage + female +
   child + fchild + black
outcomeEq <- lnmeddol ~ logc + idp + lpi + fmde + physlm + disea +
   hlthg + hlthf + hlthp + linc + lfam + educdec + xage + female +
   child + fchild + black
# ML estimation
cameron <- selection( selectEq, outcomeEq, data = RandHIE[ subsample, ] )
summary( cameron )
```

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

### Extract Summary Coefficients

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

This example demonstrates extracting all coefficients, standard errors, t-values, and p-values from the summary of a fitted selection model using `coef(summary(a))`.

```R
## extract all coefficients, standard errors, t-values
## and p-values of the model:
coef( summary( a ) )
```

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

### Treatment Regression Example with Treatment Data

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

Estimates the effect of treatment on income using the `Treatment` dataset from the `Ecdat` package. Models treatment participation and log real income.

```R
data(Treatment, package="Ecdat")
a <- treatReg(treat~poly(age,2) + educ + u74 + u75 + ethn,
              log(re78)~treat + poly(age,2) + educ + ethn,
              data=Treatment)
print(summary(a))
```

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

### Prepare and Analyze nlswork Data with plm

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

Prepares the nlswork dataset for panel data analysis using the plm package and then estimates a random effects model for ln_wage. Requires the 'plm' package to be installed and loaded.

```R
library( "plm" )
nlswork <- plm.data( nlswork, c( "idcode", "year" ) )
plmResult <- plm( ln_wage ~ union + age + grade + not_smsa + south + occ_code,
   data = nlswork, model = "random" )
summary( plmResult )
```

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

### Example: Heckit with Inverse Mill's Ratio

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

Demonstrates using `glm` for probit estimation and `invMillsRatio` to obtain the Inverse Mill's Ratio, which is then used in a `lm` model for Heckit estimation.

```R
data(Mroz87)
myProbit <- glm( lfp ~ nwifeinc + educ + exper + I( exper^2 ) + age +
   kids5 + kids618, family = binomial( link = "probit" ), data=Mroz87 )
Mroz87$IMR <- invMillsRatio( myProbit )$IMR1
myHeckit <- lm( log( wage ) ~ educ + exper + I( exper^2 ) + IMR,
   data = Mroz87[ Mroz87$lfp == 1, ] )
```

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

### Estimate Sample Selection Model (Two-Step) in R

Source: https://cran.r-project.org/web/packages/sampleSelection/vignettes/intReg.Rnw

Estimates a sample selection model using a two-step approach. Requires the 'sampleSelection' package. Starting values are derived from a tobit-2 model.

```R
res2 <- selection( yS ~ x1 + x2, yO ~ x1, data = dat, boundaries = bound, 
   start = "2step" )
res2
summary( res2 )
```

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

### Example: Comparing Inverse Mill's Ratios

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

Compares the Inverse Mill's Ratios calculated by `invMillsRatio` for a probit model and its inverse (using `nolfp` as the dependent variable). The `all.equal` function checks for numerical equality.

```R
# using NO labor force participation as endogenous variable
Mroz87$nolfp <- 1 - Mroz87$lfp
myProbit2 <- glm( nolfp ~ nwifeinc + educ + exper + I( exper^2 ) + age +
   kids5 + kids618, family = binomial( link = "probit" ), data=Mroz87 )
all.equal( invMillsRatio( myProbit )$IMR1, invMillsRatio( myProbit2 )$IMR0 )
```

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

### Example usage of predict with selection models

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

Demonstrates various ways to use the predict method with a fitted sample selection model. Includes predictions for the default type, conditional expectations, link values, response probabilities, and predictions on new data.

```R
# ML estimation
m <- selection( lfp ~ age + I( age^2 ) + faminc + kids + educ,
   wage ~ exper + I( exper^2 ) + educ + city, Mroz87 )
   
predict( m )
predict( m, type = "conditional" ) 
predict( m, type = "link" ) 
predict( m, type = "response" ) 
predict( m, newdata = Mroz87[ 3:9, ] )

```

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

### Extract Outcome Coefficients

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

This example shows how to extract only the coefficients related to the outcome equation from a fitted selection model using `coef(a, part="outcome")`.

```R
## now extract the coefficients of the outcome model only:
coef( a, part="outcome")
```

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

### Selection Model without Exclusion Restriction

Source: https://cran.r-project.org/web/packages/sampleSelection/vignettes/selection.Rnw

Runs the selection model without an exclusion restriction. This setup can also lead to convergence problems, and results may be biased if convergence is achieved.

```R
set.seed(6)
xs <- runif(1000, -1, 1)
  ys <- xs + eps[,1] > 0
  yo1 <- xs + eps[,2]
  yo2 <- xs + eps[,3]
summary(tmp <- selection(ys~xs, list(yo1 ~ xs, yo2 ~ xs), iterlim=20))
```

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

### Example: Bivariate Probit without Rhobit Transformation

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

Estimates a bivariate probit model using `vglm` without the default 'rhobit' transformation, specifying 'identitylink' for the log-correlation parameter. This is compared against the default estimation.

```R
# bivariate probit (NOT using rhobit transformation)
bProbit2 <- vglm( cbind( y1, y2 ) ~ x1 + x2, family = binom2.rho(
   lrho = "identitylink" ), data = myData )
summary( bProbit2 )
```

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

### Estimate Heckman Model using Two-Step Method

Source: https://cran.r-project.org/web/packages/sampleSelection/vignettes/selection.Rnw

Estimates a Heckman selection model using the two-step method. This is applied to the Mroz87 dataset for the Greene (2002) example.

```r
greeneTS <- selection( lfp ~ age + I( age^2 ) + faminc + kids + educ,
   wage ~ exper + I( exper^2 ) + educ + city,
   data = Mroz87, method = "2step" )
```

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

### Estimate Sample Selection Model (ML) in R

Source: https://cran.r-project.org/web/packages/sampleSelection/vignettes/intReg.Rnw

Estimates a sample selection model using maximum likelihood. Requires the 'sampleSelection' package. Starting values are derived from a tobit-2 model.

```R
library( "sampleSelection" )
res <- selection( yS ~ x1 + x2, yO ~ x1, data = dat, boundaries = bound )
res
summary( res )
```

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

### Example: Comparing Bivariate Probit Inverse Mills Ratios

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

Calculates and compares the Inverse Mill's Ratios from two bivariate probit models estimated with and without the 'rhobit' transformation. `all.equal` is used to check for numerical equivalence within a tolerance.

```R
# inverse Mills Ratios
imr  <- invMillsRatio( bProbit )
imr2 <- invMillsRatio( bProbit2 )
all.equal( imr, imr2, tolerance = .Machine$double.eps ^ 0.25)
```

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

### Robust Maximization with SANN for Selection Models

Source: https://cran.r-project.org/web/packages/sampleSelection/vignettes/selection.Rnw

Uses the SANN maximizer for a specified number of iterations to obtain starting values for the Newton-Raphson algorithm, addressing convergence issues in selection models.

```R
set.seed(0)
greeneSANN <- selection( lfp ~ age + I( age^2 ) + faminc + kids + educ,
   wage ~ exper + I( exper^2 ) + educ + city,
   data = Mroz87,
   maxMethod="SANN", parscale = 0.001 )

greeneStartSANN <- selection( lfp ~ age + I( age^2 ) + faminc + kids + educ,
   wage ~ exper + I( exper^2 ) + educ + city,
   data = Mroz87, start = coef( greeneSANN ) )

cat( greeneStartSANN$message )
```

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

### Predicting values from a fitted probit model

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

Demonstrates how to use the predict method with a fitted probit model to get different types of predictions. Use `type = "link"` for linear predictors and `type = "response"` for predicted probabilities. You can also provide new data to predict on.

```R
## female labour force participation probability
data( "Mroz87" )
m <- probit( lfp ~ kids5 + kids618 + educ + hushrs +
   huseduc + huswage + mtr + motheduc, data=Mroz87 )
predict( m )                            # equal to linearPredictors(m)
predict( m, type = "response" )         # equal to fitted(m)
predict( m, newdata = Mroz87[ 3:9, ] )  # equal to linearPredictors(m)[3:9]
predict( m, newdata = Mroz87[ 3:9, ], type = "response" ) # equal to fitted(m)[3:9]
```

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

### Create Design Matrix for Selection Model

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

Generates the design matrix for sample selection models. Specify 'outcome' to get matrices for the outcome equation or 'selection' for the selection equation.

```R
model.matrix(object, part = "outcome", ... )
```

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

### Extract Summary Outcome Coefficients

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

This example shows how to extract coefficients, standard errors, t-values, and p-values specifically for the outcome model from the summary of a fitted selection model using `coef(summary(a), part="outcome")`.

```R
## now extract the coefficients, standard errors, t-values
## and p-values of the outcome model only:
coef( summary( a ), part="outcome")
```

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

### Generating Switching Regression Data

Source: https://cran.r-project.org/web/packages/sampleSelection/vignettes/selection.Rnw

Creates data for a switching regression model with three components, using multivariate normal disturbances with specified correlations. This setup is used to demonstrate the estimation of models with multiple outcome equations.

```R
set.seed(0)
vc <- diag(3)
vc[lower.tri(vc)] <- c(0.9, 0.5, 0.1)
vc[upper.tri(vc)] <- vc[lower.tri(vc)]
eps <- rmvnorm(500, c(0,0,0), vc)
xs <- runif(500)
ys <- xs + eps[,1] > 0
xo1 <- runif(500)
yo1 <- xo1 + eps[,2]
xo2 <- runif(500)
yo2 <- xo2 + eps[,3]
```

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

### Load nlswork Dataset

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

Loads the nlswork dataset into the R environment. This is the initial step before performing any analysis.

```R
data( "nlswork" )
```

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

### Get Data Frame for Selection Model

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

Extracts the data frame used for estimating a sample selection model. Use this method to retrieve all variables involved in the estimation process.

```R
model.frame(formula, ... )
```

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

### Load Libraries and Set Seed

Source: https://cran.r-project.org/web/packages/sampleSelection/vignettes/treatReg.R

Loads the sampleSelection library and sets the random seed for reproducibility.

```R
library(sampleSelection)
options(width=70)
set.seed(0)
```

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

### Load Mroz87 Dataset

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

Loads the Mroz87 dataset, which contains data on U.S. women's labor force participation. This dataset is commonly used for sample selection model examples.

```r
data(Mroz87)
```

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

### Summarize nlswork Dataset

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

Provides a summary of the nlswork dataset, showing variable distributions and basic statistics. This is useful for initial data exploration.

```R
summary( nlswork )
```

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

### Estimate Heckman Model using ML Method

Source: https://cran.r-project.org/web/packages/sampleSelection/vignettes/selection.Rnw

Estimates a Heckman selection model using the Maximum Likelihood (ML) method with the BHHH algorithm. This is used for the Greene (2002) example.

```r
greeneML <- selection( lfp ~ age + I( age^2 ) + faminc + kids + educ,
   wage ~ exper + I( exper^2 ) + educ + city, data = Mroz87,
   maxMethod = "BHHH", iterlim = 500 )
```

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

### 2-Step Estimation for Tobit Model with Boundary Issues

Source: https://cran.r-project.org/web/packages/sampleSelection/vignettes/selection.Rnw

Illustrates the 2-step estimation method for a Tobit-2 model, which can still provide estimates even when the ML estimator fails due to boundary issues with the correlation coefficient (rho).

```R
tobitTS <- selection(ys~x, y~x, method="2step")
coef( summary( tobitTS ) )[ "rho", ]
```

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

### Ecdat Example with Exclusion Restriction

Source: https://cran.r-project.org/web/packages/sampleSelection/vignettes/treatReg.R

Applies the `treatReg` function to the 'Treatment' dataset from the Ecdat package, using an exclusion restriction (e.g., 'u74', 'u75' in the selection equation but not the outcome equation).

```R
data(Treatment, package="Ecdat")
er <- treatReg(treat~poly(age,2) + educ + u74 + u75 + ethn,
               log(re78)~treat + poly(age,2) + educ + ethn,
               data=Treatment)
print(summary(er))
```

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

### Estimate Initial Selection Model

Source: https://cran.r-project.org/web/packages/sampleSelection/vignettes/intReg.Rnw

Estimates a selection model with a limited set of explanatory variables. Use this to establish a baseline model.

```R
SmokeRes1 <- selection( smoker ~ educ + age, 
  cigs_intervals ~ educ, data = Smoke, boundaries = bounds )
```

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

### selection-methods

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

Provides methods for selection models, including logLik, nobs, nObs, and print.

```APIDOC
## selection-methods

### Description
Methods for selection models 

### Usage
```R
## S3 method for class 'selection'
logLik(object, ... )

## S3 method for class 'selection'
nobs(object, ... )
             
## S3 method for class 'selection'
nObs(x, ... )
             
## S3 method for class 'selection'
print( x, digits = max(3, getOption("digits") - 3), ... )

```

### Arguments
`object`, `x` |  object of class `selection`.  
---|---
`digits` |  the minimum number of significant digits of the coefficients to be printed.  
`...` |  further arguments (currently ignored).  

### Details
The `logLik` method returns the log likelihood value of the model. The `nobs` and `nObs` methods return the number of observations. The `print` method prints the call and the estimated coefficients. 
Furthermore, some standard methods can be applied to selection models: The `lrtest` method can be used to perform likelihood-ratio tests. The `stdEr` method returns the vector of the standard errors of the estimated parameters. 
The methods `coef.selection`, `fitted.selection` `model.frame.selection`, `model.matrix.selection`, `residuals.selection`, `summary.selection`, and `vcov.selection` are described at seperate help pages. 

### Author(s)
Arne Henningsen 

### See Also
`selection`, `summary.selection`, and `probit-methods`.
```

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

### Ecdat Example Without Exclusion Restriction

Source: https://cran.r-project.org/web/packages/sampleSelection/vignettes/treatReg.R

Applies the `treatReg` function to the 'Treatment' dataset from the Ecdat package, without an explicit exclusion restriction (all variables in the selection equation are also in the outcome equation).

```R
noer <- treatReg(treat~poly(age,2) + educ + u74 + u75 + ethn,
                 log(re78)~treat + poly(age,2) + educ + u74 + u75 + ethn,
                 data=Treatment)
print(summary(noer))
```

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

### Data Preparation and Equation Specification

Source: https://cran.r-project.org/web/packages/sampleSelection/vignettes/selection.Rnw

Loads the RandHIE dataset and defines the selection and outcome equations for the analysis. Ensures data is preprocessed for the model.

```R
data( "RandHIE" )
subsample <- RandHIE$year == 2 & !is.na( RandHIE$educdec )
selectEq <- binexp ~ logc + idp + lpi + fmde + physlm + disea +
   hlthg + hlthf + hlthp + linc + lfam + educdec + xage + female +
   child + fchild + black
outcomeEq <- lnmeddol ~ logc + idp + lpi + fmde + physlm + disea +
   hlthg + hlthf + hlthp + linc + lfam + educdec + xage + female +
   child + fchild + black
```

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

### BibTeX Entry for sampleSelection Package

Source: https://cran.r-project.org/web/packages/sampleSelection/citation.html

Use this BibTeX entry to cite the sampleSelection R package in LaTeX documents and other academic publications.

```bibtex
@Article{
    title = {Sample Selection Models in {R}: Package
      {sampleSelection}},
    author = {Ott Toomet and Arne Henningsen},
    journal = {Journal of Statistical Software},
    year = {2008},
    volume = {27},
    number = {7},
    url = {https://www.jstatsoft.org/v27/i07/},
  }
```

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

### Sample Selection with Random Numbers and IV/2SLS Estimation

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

Generates random data to demonstrate Heckman selection models with Instrumental Variables (IV)/2SLS estimation. Requires the `mvtnorm` package.

```R
library( "mvtnorm" )
nObs <- 1000
sigma <- matrix( c( 1, 0.5, 0.1, 0.5, 1, -0.3, 0.1, -0.3, 1 ), ncol = 3 )
errorTerms <- rmvnorm( nObs, c( 0, 0, 0 ), sigma )
myData <- data.frame( no = c( 1:nObs ), x1 = rnorm( nObs ), x2 = rnorm( nObs ),
   u1 = errorTerms[ , 1 ], u2 = errorTerms[ , 2 ], u3 = errorTerms[ , 3 ] )
myData$w <- 1 + myData$x1 + myData$u1
myData$y <- 2 + myData$w + myData$u2
myData$s <- ( 2 * myData$x1 + myData$x2 + myData$u3 - 0.2 ) > 0
myData$y[ !myData$s ] <- NA
myHeckit <- heckit( s ~ x1 + x2, y ~ w, data = myData )
summary( myHeckit )  # biased!
myHeckitIv <- heckit( s ~ x1 + x2, y ~ w, data = myData, inst = ~ x1 )
summary( myHeckitIv ) # unbiased
```

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

### Two-Step and ML Estimation with Mroz87 Data

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

Demonstrates two-step and Maximum Likelihood (ML) estimation for sample selection models using the `Mroz87` dataset. Requires the `kids` variable to be created.

```R
data( Mroz87 )
Mroz87$kids  <- ( Mroz87$kids5 + Mroz87$kids618 > 0 )
# Two-step estimation
summary( heckit( lfp ~ age + I( age^2 ) + faminc + kids + educ,
   wage ~ exper + I( exper^2 ) + educ + city, Mroz87 ) )
# ML estimation
summary( selection( lfp ~ age + I( age^2 ) + faminc + kids + educ,
   wage ~ exper + I( exper^2 ) + educ + city, Mroz87 ) )
```

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

### Generate Sample Selection Dataset in R

Source: https://cran.r-project.org/web/packages/sampleSelection/vignettes/intReg.Rnw

Generates a synthetic dataset for sample selection models, including latent variables, observed outcomes, and selection indicators. Requires the 'mvtnorm' package.

```R
library( "mvtnnorm" )
# number of observations
nObs <- 300
# parameters
betaS <- c( 1, 1, -1 )
betaO <- c( 10, 4 )
rho <- 0.4
sigma <- 5
# boundaries of the intervals
bound <- c(-Inf,5,15,Inf)

# set 'seed' of the pseudo random number generator
# in order to always generate the same pseudo random numbers
set.seed(123)
# generate variables x1 and x2
dat <- data.frame( x1 = rnorm( nObs ), x2 = rnorm( nObs ) )
# variance-covariance matrix of the two error terms
vcovMat <- matrix( c( 1, rho*sigma, rho*sigma, sigma^2 ), nrow = 2 )
# generate the two error terms
eps <- rmvnorm( nObs, sigma = vcovMat )
dat$epsS <- eps[,1]
dat$epsO <- eps[,2]
# generate the selection variable
dat$yS <- with( dat, betaS[1] + betaS[2] * x1 + betaS[3] * x2 + epsS ) > 0
table( dat$yS )
# generate the unobserved/latent outcome variable
dat$yOu <- with( dat, betaO[1] + betaO[2] * x1 + epsO )
dat$yOu[ !dat$yS ] <- NA
# obtain the intervals of the outcome variable
dat$yO <- cut( dat$yOu, bound )
table( dat$yO )
```

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

### Load Smoke Dataset

Source: https://cran.r-project.org/web/packages/sampleSelection/vignettes/intReg.Rnw

Loads the 'Smoke' dataset, which is commonly used for demonstrating selection models related to smoking behavior.

```R
data( "Smoke" )
```

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

### Sample Selection with Random Numbers and OLS/Heckit

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

Generates random data to demonstrate Ordinary Least Squares (OLS) and Heckman selection models. Requires the `mvtnorm` package.

```R
library( "mvtnorm" )
nObs <- 1000
sigma <- matrix( c( 1, -0.7, -0.7, 1 ), ncol = 2 )
errorTerms <- rmvnorm( nObs, c( 0, 0 ), sigma )
myData <- data.frame( no = c( 1:nObs ), x1 = rnorm( nObs ), x2 = rnorm( nObs ),
   u1 = errorTerms[ , 1 ], u2 =  errorTerms[ , 2 ] )
myData$y <- 2 + myData$x1 + myData$u1
myData$s <- ( 2 * myData$x1 + myData$x2 + myData$u2 - 0.2 ) > 0
myData$y[ !myData$s ] <- NA
myOls <- lm( y ~ x1, data = myData)
summary( myOls )
myHeckit <- heckit( s ~ x1 + x2, y ~ x1, myData, print.level = 1 )
summary( myHeckit )
```

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

### S3 Methods for Selection Objects

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

Provides S3 methods for 'selection' objects to extract log-likelihood, number of observations, and print model details. Ensure the object is of class 'selection'.

```R
## S3 method for class 'selection'
logLik(object, ... )

## S3 method for class 'selection'
nobs(object, ... )
             
## S3 method for class 'selection'
nObs(x, ... )
             
## S3 method for class 'selection'
print( x, digits = max(3, getOption("digits") - 3), ... )
```

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

### ML Estimation for Tobit Model with Boundary Issues

Source: https://cran.r-project.org/web/packages/sampleSelection/vignettes/selection.Rnw

Demonstrates Maximum Likelihood (ML) estimation for a Tobit-2 model, which may encounter convergence problems when the correlation coefficient (rho) is at the boundary of the parameter space.

```R
set.seed(0)
x <- runif(1000)
y <- x + rnorm(1000)
ys <- y > 0
tobitML <- selection(ys~x, y~x)
cat( tobitML$message )
coef( summary( tobitML ) )[ "rho", ]
```

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

### Design Matrix of Binary Choice Models

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

Creates a design matrix for binary choice models.

```APIDOC
## Design Matrix of Binary Choice Models

### Description
Create design matrix of binary choice models 

### Usage
```R
## S3 method for class 'binaryChoice'
model.matrix( object, ... )
```

### Arguments
`object` |  object of class `binaryChoice`.  
`...` |  currently not used.  

### Value
The design matrix of binary choice models. 

### Author(s)
Arne Henningsen, Ott Toomet otoomet@ut.ee

### See Also
`binaryChoice`, `probit`, `model.matrix`, `model.frame.binaryChoice`, and `probit-methods`.
```

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

### Compare Analytical and Numerical Gradients of CDF

Source: https://cran.r-project.org/web/packages/sampleSelection/vignettes/intReg.Rnw

Compares the numerical gradient of the CDF with the analytical gradient (dmvnorm) for various input values. Useful for validating gradient calculations.

```R
#Eq??
all.equal(grad,
    (1/(2*pi)) * (
    ((((-4*rho*(x1^2-2*rho*x1*x2+x2^2)-2*(1-rho^2)*(-2*x1*x2))/(4*(1-rho^2)^2)) * 
            efun * sqrt(1-rho^2))/(1-rho^2)) - 
            ((-(rho/(sqrt(1-rho^2)))*efun)/(1-rho^2))
    ))
#Eq??
all.equal(grad,
    (1/(2*pi)) * 
    ((rho/((1-rho^2)^(3/2))) - ((rho*(x1^2-rho*x1*x2+x2^2)-x1*x2)/ 
            ((1-rho^2)^(5/2)))) * efun
    )

#Eq??
all.equal(grad,
    (1/(2*pi*sqrt(1-rho^2))) * 
    (((rho/(1-rho^2)) - ((rho*(x1^2-rho*x1*x2+x2^2)-x1*x2)/ 
            ((1-rho^2)^2))) * efun)
    )
```

```R
# Numerical gradient of the CDF w.r.t. rho
cdfRho <- function( p, xa = x1, xb = x2 ) {
   prob <- pmvnorm( upper = c( xa, xb ),
      sigma = matrix( c( 1, p, p, 1 ), nrow = 2 ) )
   return( prob )
}
grad <- c( numericGradient( cdfRho, rho ) )
print( grad )

# comparison with analytical gradient
all.equal( grad,
      dmvnorm( x = c( x1, x2 ),
      sigma = matrix( c( 1, rho, rho, 1 ), nrow = 2 ) ) )

# comparisons with other values
compDerivRho <- function( xa, xb, p ) {
   dn <- c( numericGradient( cdfRho, p, xa = xa, xb = xb ) )
   da <- dmvnorm( x = c( xa, xb ),
      sigma = matrix( c( 1, p, p, 1 ), nrow = 2 ) )
   return( all.equal( dn, da ) )
}
compDerivRho( x1, x2, rho )
compDerivRho( 0.5, x2, rho )
compDerivRho( 2.5, x2, rho )
compDerivRho( x1, -2, rho )
compDerivRho( x1, x2, 0.2 )
compDerivRho( x1, x2, 0.98 )

```

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

### tobit2fit

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

Fits tobit-2 (sample selection) and tobit-5 (switching regression) models by Maximum Likelihood (ML) estimation. Requires numeric vectors/matrices and initial parameter values.

```APIDOC
## tobit2fit

### Description
Fits tobit-2 (sample selection) and tobit-5 (switching regression) models by Maximum Likelihood (ML) estimation. The arguments must be given as numeric vectors/matrices, initial value of parameters must be specified. These functions are called by `selection` and are intended for `sampleSelection` internal use.

### Usage
```R
tobit2fit( YS, XS, YO, XO, start, weights = NULL, print.level = 0,
   maxMethod = "Newton-Raphson", ... )
```

### Arguments
`YS` - numeric 0/1 vector, where 0 denotes unobserved outcome (tobit 2) or outcome 1 observed (tobit 5).
`XS`, `XO`, `XO1`, `XO2` - numeric matrix, model matrix for selection and outcome equations.
`YO` - numeric vector, observed outcomes. Values for unobserved outcomes are ignored (they may or may not be NA).
`start` - numeric vector of initial values. The order is: betaS, betaO(1), sigma(1), rho(1), betaO2, sigma2, rho2.
`weights` - an optional vector of ‘prior weights’ to be used in the fitting process. Should be NULL or a numeric vector. Weights are currently only supported in type-2 models.
`print.level` - numeric, values greater than 0 will produce increasingly more debugging information.
`maxMethod` - character, a maximisation method supported by `maxLik`
`...` - Additional parameters to `maxLik`.

### Value
Object of class `"selection"`. It inherits from class `"maxLik"` and includes two additional components: `$tobitType`, numeric tobit model classifier (see Amemiya, 1985), and `$method`, either `"ml"` or `"2step"`, specifying the estimation method.

### Author(s)
Ott Toomet otoomet@ut.ee, Arne Henningsen

### References
Amemiya, T. (1985) _Advanced Econometrics_ , Harvard University Press

### See Also
`selection`, `maxLik`
```

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

### Summarizing Probit Estimations

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

Prints or returns a summary of a probit estimation.

```APIDOC
## Summarizing Probit Estimations

### Description
Print or return a summary of a probit estimation. 

### Usage
```R
   ## S3 method for class 'probit'
summary( object, ... )
   ## S3 method for class 'summary.probit'
print( x, ... )

```

### Arguments
`object` |  an object of class `probit`.  
---|---
`x` |  an object of class `summary.probit`.  
`...` |  currently not used.  

### Value
The `summary` method returns an object of class `summary.probit`; the `print` method prints summary results and returns the argument invisibly. 

### Author(s)
Arne Henningsen

### See Also
`probit` and `probit-methods`.
```

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

### Comparing Log-Likelihoods

Source: https://cran.r-project.org/web/packages/sampleSelection/vignettes/selection.Rnw

Compares the log-likelihood values of two different model estimations, likely to assess the improvement from a more robust maximization method.

```R
logLik( greeneML )
logLik( greeneStartSANN )
```

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

### Perform Likelihood Ratio and Wald Tests

Source: https://cran.r-project.org/web/packages/sampleSelection/vignettes/intReg.Rnw

Conducts likelihood ratio and Wald tests to compare the explanatory power of two nested selection models. Requires the 'lmtest' package.

```R
library( "lmtest" )
lrtest( SmokeRes1, SmokeRes2 )
```

```R
waldtest( SmokeRes1, SmokeRes2 )
```

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

### Design Matrix of Selection Models

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

Creates a design matrix for sample selection models.

```APIDOC
## Design Matrix of Selection Models

### Description
Create design matrix of sample selection models 

### Usage
```R
## S3 method for class 'selection'
model.matrix(object, part = "outcome", ... )
```

### Arguments
`object` |  object of class `selection`.  
`part` |  character string indication which design matrix/matrices to extract: "outcome" for the design matrix/matrices of the outcome equation(s) or "selection" for the design matrix of the selection equation.  
`...` |  further arguments passed to other methods (e.g. `model.matrix.binaryChoice` or `model.matrix`).  

### Value
If argument `part` is `"selection"`, the design matrix of the selection equation is returned. 
If argument `part` is `"outcome"`, the design matrix of the outcome equation (tobit-2 or treatment model) or a list of two outcome matrices (tobit-5 model) is returned. All unobserved outcomes, including the corresponding explanatory variables are set to `NA`, even in case where valid values were supplied for estimation. 

### Author(s)
Arne Henningsen

### See Also
`model.matrix`, `selection`, `model.frame.selection`, and `selection-methods`.
```

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

### tobit5fit

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

Fits tobit-5 (switching regression) models by Maximum Likelihood (ML) estimation. Requires numeric vectors/matrices and initial parameter values.

```APIDOC
## tobit5fit

### Description
Fits tobit-5 (switching regression) models by Maximum Likelihood (ML) estimation. The arguments must be given as numeric vectors/matrices, initial value of parameters must be specified. These functions are called by `selection` and are intended for `sampleSelection` internal use.

### Usage
```R
tobit5fit( YS, XS, YO1, XO1, YO2, XO2, start, print.level = 0,
   maxMethod = "Newton-Raphson", ... )
```

### Arguments
`YS` - numeric 0/1 vector, where 0 denotes unobserved outcome (tobit 2) or outcome 1 observed (tobit 5).
`XS`, `XO`, `XO1`, `XO2` - numeric matrix, model matrix for selection and outcome equations.
`YO1` - numeric vector, observed outcomes for the first equation.
`YO2` - numeric vector, observed outcomes for the second equation.
`start` - numeric vector of initial values. The order is: betaS, betaO(1), sigma(1), rho(1), betaO2, sigma2, rho2.
`print.level` - numeric, values greater than 0 will produce increasingly more debugging information.
`maxMethod` - character, a maximisation method supported by `maxLik`
`...` - Additional parameters to `maxLik`.

### Value
Object of class `"selection"`. It inherits from class `"maxLik"` and includes two additional components: `$tobitType`, numeric tobit model classifier (see Amemiya, 1985), and `$method`, either `"ml"` or `"2step"`, specifying the estimation method.

### Author(s)
Ott Toomet otoomet@ut.ee, Arne Henningsen

### References
Amemiya, T. (1985) _Advanced Econometrics_ , Harvard University Press

### See Also
`selection`, `maxLik`
```

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

### S3 Methods for Probit Summary

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

Defines S3 methods for 'probit' and 'summary.probit' classes to generate and print summaries of probit estimations. The 'summary' method returns a 'summary.probit' object, and the 'print' method displays results.

```R
   ## S3 method for class 'probit'
summary( object, ... )
   ## S3 method for class 'summary.probit'
print( x, ... )
```

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

### 2-step Heckman Estimation for Tobit-5 Models

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

Fits tobit-5 (switching regression) models using 2-step Heckman estimation. Primarily for internal use by the 'selection' function.

```R
heckit5fit( selection, outcome1, outcome2, data = sys.frame(sys.parent()),
   ys = FALSE, yo = FALSE, xs = FALSE, xo = FALSE, mfs = FALSE,
   mfo = FALSE,
   printLevel=print.level, print.level = 0, maxMethod = "Newton-Raphson", ... )
```

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

### Fit Tobit-5 (Switching Regression) Model

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

Fits a tobit-5 (switching regression) model using Maximum Likelihood estimation. Requires numeric vectors/matrices for data and initial parameter values.

```R
tobit5fit( YS, XS, YO1, XO1, YO2, XO2, start, print.level = 0,
   maxMethod = "Newton-Raphson", ... )
```

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

### Simulating Sample Selection Data with Wider Support

Source: https://cran.r-project.org/web/packages/sampleSelection/vignettes/selection.Rnw

Generates data for a sample selection model where the support of the selection variable's regressor is widened. This increases the variation in the latent selection equation, leading to more precise parameter estimates.

```R
xs <- runif(500, -5, 5)
ys <- xs + eps[,1] > 0
yoX <- xs + eps[,2]
  yo <- yoX*(ys > 0)
  summary( selection(ys ~ xs, yo ~ xs))
```

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

### print.probit

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

Prints the call and estimated coefficients of a probit model.

```APIDOC
## print.probit

### Description
Methods for probit models

### Usage
```
## S3 method for class 'probit'
print( x, digits = max(3, getOption("digits") - 3), ... )
```

### Arguments
`x` | object of class `probit`.
`digits` | the minimum number of significant digits of the coefficients to be printed.
`...` | further arguments (currently ignored).

### Details
The `print` method prints the call and the estimated coefficients.
```

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

### 2-step Heckman Estimation for Tobit-2 Models

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

Fits tobit-2 (sample selection) models using 2-step Heckman estimation. Primarily for internal use by the 'selection' function.

```R
heckit2fit( selection, outcome, data=sys.frame(sys.parent()),
   weights = NULL, inst = NULL,
   printLevel=print.level, print.level = 0,
   maxMethod = "Newton-Raphson" )
```