maxscoreCIpy 0.6.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Kostas Florios
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,143 @@
1
+ Metadata-Version: 2.4
2
+ Name: maxscoreCIpy
3
+ Version: 0.6.0
4
+ Summary: Cattaneo et al. (2020) Reshaped Bootstrap & Plug-in Hessian with fixed beta_1=1, unified bandwidth, and multi-start optimization
5
+ Project-URL: Homepage, https://github.com/kflorios/maxscoreCIpy
6
+ Requires-Python: >=3.8
7
+ Description-Content-Type: text/markdown
8
+ License-File: LICENSE
9
+ Requires-Dist: numpy>=1.20.0
10
+ Requires-Dist: scipy>=1.7.0
11
+ Dynamic: license-file
12
+
13
+ # maxscoreCIpy
14
+
15
+ Python implementation of Manski's Maximum Score Estimator with **fixed $\beta_1 = 1$**, Cattaneo, Jansson, and Nagasawa (2020) **Reshaped Bootstrap**, analytical Gaussian kernel plug-in Hessian estimation using a unified bandwidth parameter, and multi-start Differential Evolution (`n_starts`).
16
+
17
+ ## Installation
18
+
19
+ This package requires Python 3.8 or higher (`>=3.8`).
20
+
21
+ ```bash
22
+ pip install -e .
23
+ ```
24
+
25
+ ---
26
+
27
+ ## Quick Start Example
28
+
29
+ ```python
30
+ import numpy as np
31
+ from maxscoreCIpy import MaxScoreEstimator, ReshapedBootstrap, PluginHessianEstimator
32
+
33
+ # Generate synthetic data targeting beta = [1.0, 0.5]
34
+ np.random.seed(42)
35
+ n = 1000
36
+ X = np.random.uniform(-1, 1, size=(n, 2))
37
+ true_beta = np.array([1.0, 0.5])
38
+
39
+ latent = np.dot(X, true_beta) + np.random.normal(0, 0.3, size=n)
40
+ Y = (latent >= 0).astype(float)
41
+
42
+ # 1. Point Estimation (first coefficient fixed to 1)
43
+ estimator = MaxScoreEstimator(bounds=(-10.0, 10.0), n_starts=3, seed=42)
44
+ beta_hat = estimator.fit(X, Y)
45
+ print("Estimated Beta (beta_1 = 1 fixed):", beta_hat)
46
+
47
+ # 2. Analytical Plug-in Hessian Estimation
48
+ hessian_calc = PluginHessianEstimator(bw=0.3)
49
+ H_plugin = hessian_calc.estimate(beta_hat, X, Y)
50
+ print("Analytical Plug-in Hessian Matrix:\n", H_plugin)
51
+
52
+ # 3. Reshaped Bootstrap Confidence Intervals
53
+ boot = ReshapedBootstrap(B=50, bandwidth=0.3, local_window=2.0, n_starts=3, seed=42)
54
+ boot_estimates = boot.fit_bootstrap(X, Y, beta_hat)
55
+ ci_95 = boot.confidence_intervals(beta_hat, boot_estimates, alpha=0.05)
56
+ print("95% Confidence Intervals:\n", ci_95)
57
+ ```
58
+
59
+ ---
60
+
61
+ ## API Reference
62
+
63
+ ### `MaxScoreEstimator`
64
+
65
+ Computes Manski's Maximum Score Estimator with the first coefficient fixed to `1.0` ($\beta = [1, \gamma^T]$) to resolve scale and sign indeterminacy. Optimization is performed using multi-start Differential Evolution (`scipy.optimize.differential_evolution`).
66
+
67
+ #### Initialization Arguments
68
+ ```python
69
+ MaxScoreEstimator(bounds=(-10.0, 10.0), n_starts=3, seed=None)
70
+ ```
71
+
72
+ | Parameter | Type | Default | Description |
73
+ | :--- | :--- | :--- | :--- |
74
+ | `bounds` | `tuple[float, float]` | `(-10.0, 10.0)` | Lower and upper search bounds `(min, max)` applied to each free parameter $\gamma_j$ ($j = 2, \dots, d$). |
75
+ | `n_starts` | `int` | `3` | Number of independent Differential Evolution runs per optimization. The solution achieving the highest score (lowest negative objective value) is selected. |
76
+ | `seed` | `int` or `None` | `None` | Random seed used to initialize the internal RNG (`np.random.default_rng`) for reproducible multi-start runs. |
77
+
78
+ #### Methods
79
+ * **`fit(X, Y)`**
80
+ * **`X`** (`np.ndarray`, shape `(n, d)`): Design matrix of covariates ($d \ge 2$). The first column corresponds to the normalized coefficient $\beta_1 = 1.0$.
81
+ * **`Y`** (`np.ndarray`, shape `(n,)`): Binary outcome vector taking values `0` and `1` (or `0.0` and `1.0`).
82
+ * **Returns:** `np.ndarray` of shape `(d,)` containing `[1.0, gamma_hat_1, ..., gamma_hat_{d-1}]`.
83
+
84
+ ---
85
+
86
+ ### `ReshapedBootstrap`
87
+
88
+ Implements the Cattaneo, Jansson, and Nagasawa (2020) Reshaped Bootstrap for cube-root ($n^{1/3}$) consistent Maximum Score inference. In each bootstrap replication, it maximizes the reshaped objective function incorporating the analytical plug-in Hessian quadratic centering term:
89
+ $$
90
+ \tilde{M}_n^*(\gamma) = M_n^*(\gamma) - M_n(\gamma) + \frac{1}{2} (\gamma - \hat{\gamma})^T \tilde{H} (\gamma - \hat{\gamma})
91
+ $$
92
+
93
+ #### Initialization Arguments
94
+ ```python
95
+ ReshapedBootstrap(B=200, bandwidth=2.0, bounds=(-10.0, 10.0), n_starts=3, seed=None)
96
+ ```
97
+
98
+ | Parameter | Type | Default | Description |
99
+ | :--- | :--- | :--- | :--- |
100
+ | `B` | `int` | `200` | Number of bootstrap replications. Recommended minimum is `B >= 50` (typically `100–200`) for stable percentile confidence intervals. |
101
+ | `bandwidth` | `float` | `2.0` | Unified Gaussian kernel bandwidth applied to both the conditional probability regression $\hat{\kappa}(x) = \hat{E}[Y \mid X=x]$ and the analytical plug-in Hessian matrix $\tilde{H}$. Should be scaled to match the support of `X` (e.g., `0.3` for $X \sim U[-1, 1]$). |
102
+ | `bounds` | `tuple[float, float]` | `(-10.0, 10.0)` | Lower and upper search bounds `(min, max)` applied to each free parameter $\gamma_j$ ($j = 2, \dots, d$). |
103
+ | `n_starts` | `int` | `3` | Number of independent Differential Evolution runs executed within each bootstrap replication, retaining the best optimum. |
104
+ | `seed` | `int` or `None` | `None` | Random seed for reproducible resampling of $(X^*, Y^*)$ and Differential Evolution initializations. |
105
+
106
+ #### Methods
107
+ * **`fit_bootstrap(X, Y, beta_hat)`**
108
+ * **`X`** (`np.ndarray`, shape `(n, d)`): Original covariate matrix.
109
+ * **`Y`** (`np.ndarray`, shape `(n,)`): Original binary outcome vector (`0` and `1`).
110
+ * **`beta_hat`** (`np.ndarray`, shape `(d,)`): Point estimate returned by `MaxScoreEstimator.fit(X, Y)` with `beta_hat[0] == 1.0`.
111
+ * **Returns:** `np.ndarray` of shape `(B, d)` containing the bootstrap parameter estimates $\beta^{*(b)}$.
112
+ * **`confidence_intervals(beta_hat, bootstrap_estimates, alpha=0.05)`**
113
+ * **`beta_hat`** (`np.ndarray`, shape `(d,)`): Original point estimate vector.
114
+ * **`bootstrap_estimates`** (`np.ndarray`, shape `(B, d)`): Matrix of bootstrap draws returned by `fit_bootstrap`.
115
+ * **`alpha`** (`float`, default `0.05`): Significance level for two-sided $(1 - \alpha)$ percentile confidence intervals (e.g., `0.05` produces 2.5% and 97.5% bounds).
116
+ * **Returns:** `np.ndarray` of shape `(d, 2)` where column `0` is the lower bound and column `1` is the upper bound.
117
+
118
+ ---
119
+
120
+ ### `PluginHessianEstimator`
121
+
122
+ Computes the analytical Gaussian kernel derivative plug-in estimator for the Hessian matrix $\tilde{H}$ with respect to the free parameters $\gamma = (\beta_2, \dots, \beta_d)^T$, matching `Hhat.cpp` from Cattaneo et al. (2020).
123
+
124
+ #### Initialization Arguments
125
+ ```python
126
+ PluginHessianEstimator(bw=2.0)
127
+ ```
128
+
129
+ | Parameter | Type | Default | Description |
130
+ | :--- | :--- | :--- | :--- |
131
+ | `bw` | `float` | `2.0` | Smoothing bandwidth for the standard Gaussian kernel derivative $K'(u) = -\frac{u}{\sqrt{2\pi}} e^{-u^2/2}$. |
132
+
133
+ #### Methods
134
+ * **`estimate(beta_hat, X, Y)`**
135
+ * **`beta_hat`** (`np.ndarray`, shape `(d,)`): Point estimate vector.
136
+ * **`X`** (`np.ndarray`, shape `(n, d)`): Covariate matrix.
137
+ * **`Y`** (`np.ndarray`, shape `(n,)`): Binary outcome vector (`0` and `1`).
138
+ * **Returns:** Symmetric `np.ndarray` of shape `(d - 1, d - 1)` representing the estimated Hessian matrix $\tilde{H}$.
139
+
140
+ ---
141
+
142
+ ## Reference
143
+ * Cattaneo, M. D., Jansson, M., & Nagasawa, K. (2020). *Bootstrap-Based Inference for Cube Root Consistent Estimators*. Econometrica, 88(5), 2203–2219.
@@ -0,0 +1,131 @@
1
+ # maxscoreCIpy
2
+
3
+ Python implementation of Manski's Maximum Score Estimator with **fixed $\beta_1 = 1$**, Cattaneo, Jansson, and Nagasawa (2020) **Reshaped Bootstrap**, analytical Gaussian kernel plug-in Hessian estimation using a unified bandwidth parameter, and multi-start Differential Evolution (`n_starts`).
4
+
5
+ ## Installation
6
+
7
+ This package requires Python 3.8 or higher (`>=3.8`).
8
+
9
+ ```bash
10
+ pip install -e .
11
+ ```
12
+
13
+ ---
14
+
15
+ ## Quick Start Example
16
+
17
+ ```python
18
+ import numpy as np
19
+ from maxscoreCIpy import MaxScoreEstimator, ReshapedBootstrap, PluginHessianEstimator
20
+
21
+ # Generate synthetic data targeting beta = [1.0, 0.5]
22
+ np.random.seed(42)
23
+ n = 1000
24
+ X = np.random.uniform(-1, 1, size=(n, 2))
25
+ true_beta = np.array([1.0, 0.5])
26
+
27
+ latent = np.dot(X, true_beta) + np.random.normal(0, 0.3, size=n)
28
+ Y = (latent >= 0).astype(float)
29
+
30
+ # 1. Point Estimation (first coefficient fixed to 1)
31
+ estimator = MaxScoreEstimator(bounds=(-10.0, 10.0), n_starts=3, seed=42)
32
+ beta_hat = estimator.fit(X, Y)
33
+ print("Estimated Beta (beta_1 = 1 fixed):", beta_hat)
34
+
35
+ # 2. Analytical Plug-in Hessian Estimation
36
+ hessian_calc = PluginHessianEstimator(bw=0.3)
37
+ H_plugin = hessian_calc.estimate(beta_hat, X, Y)
38
+ print("Analytical Plug-in Hessian Matrix:\n", H_plugin)
39
+
40
+ # 3. Reshaped Bootstrap Confidence Intervals
41
+ boot = ReshapedBootstrap(B=50, bandwidth=0.3, local_window=2.0, n_starts=3, seed=42)
42
+ boot_estimates = boot.fit_bootstrap(X, Y, beta_hat)
43
+ ci_95 = boot.confidence_intervals(beta_hat, boot_estimates, alpha=0.05)
44
+ print("95% Confidence Intervals:\n", ci_95)
45
+ ```
46
+
47
+ ---
48
+
49
+ ## API Reference
50
+
51
+ ### `MaxScoreEstimator`
52
+
53
+ Computes Manski's Maximum Score Estimator with the first coefficient fixed to `1.0` ($\beta = [1, \gamma^T]$) to resolve scale and sign indeterminacy. Optimization is performed using multi-start Differential Evolution (`scipy.optimize.differential_evolution`).
54
+
55
+ #### Initialization Arguments
56
+ ```python
57
+ MaxScoreEstimator(bounds=(-10.0, 10.0), n_starts=3, seed=None)
58
+ ```
59
+
60
+ | Parameter | Type | Default | Description |
61
+ | :--- | :--- | :--- | :--- |
62
+ | `bounds` | `tuple[float, float]` | `(-10.0, 10.0)` | Lower and upper search bounds `(min, max)` applied to each free parameter $\gamma_j$ ($j = 2, \dots, d$). |
63
+ | `n_starts` | `int` | `3` | Number of independent Differential Evolution runs per optimization. The solution achieving the highest score (lowest negative objective value) is selected. |
64
+ | `seed` | `int` or `None` | `None` | Random seed used to initialize the internal RNG (`np.random.default_rng`) for reproducible multi-start runs. |
65
+
66
+ #### Methods
67
+ * **`fit(X, Y)`**
68
+ * **`X`** (`np.ndarray`, shape `(n, d)`): Design matrix of covariates ($d \ge 2$). The first column corresponds to the normalized coefficient $\beta_1 = 1.0$.
69
+ * **`Y`** (`np.ndarray`, shape `(n,)`): Binary outcome vector taking values `0` and `1` (or `0.0` and `1.0`).
70
+ * **Returns:** `np.ndarray` of shape `(d,)` containing `[1.0, gamma_hat_1, ..., gamma_hat_{d-1}]`.
71
+
72
+ ---
73
+
74
+ ### `ReshapedBootstrap`
75
+
76
+ Implements the Cattaneo, Jansson, and Nagasawa (2020) Reshaped Bootstrap for cube-root ($n^{1/3}$) consistent Maximum Score inference. In each bootstrap replication, it maximizes the reshaped objective function incorporating the analytical plug-in Hessian quadratic centering term:
77
+ $$
78
+ \tilde{M}_n^*(\gamma) = M_n^*(\gamma) - M_n(\gamma) + \frac{1}{2} (\gamma - \hat{\gamma})^T \tilde{H} (\gamma - \hat{\gamma})
79
+ $$
80
+
81
+ #### Initialization Arguments
82
+ ```python
83
+ ReshapedBootstrap(B=200, bandwidth=2.0, bounds=(-10.0, 10.0), n_starts=3, seed=None)
84
+ ```
85
+
86
+ | Parameter | Type | Default | Description |
87
+ | :--- | :--- | :--- | :--- |
88
+ | `B` | `int` | `200` | Number of bootstrap replications. Recommended minimum is `B >= 50` (typically `100–200`) for stable percentile confidence intervals. |
89
+ | `bandwidth` | `float` | `2.0` | Unified Gaussian kernel bandwidth applied to both the conditional probability regression $\hat{\kappa}(x) = \hat{E}[Y \mid X=x]$ and the analytical plug-in Hessian matrix $\tilde{H}$. Should be scaled to match the support of `X` (e.g., `0.3` for $X \sim U[-1, 1]$). |
90
+ | `bounds` | `tuple[float, float]` | `(-10.0, 10.0)` | Lower and upper search bounds `(min, max)` applied to each free parameter $\gamma_j$ ($j = 2, \dots, d$). |
91
+ | `n_starts` | `int` | `3` | Number of independent Differential Evolution runs executed within each bootstrap replication, retaining the best optimum. |
92
+ | `seed` | `int` or `None` | `None` | Random seed for reproducible resampling of $(X^*, Y^*)$ and Differential Evolution initializations. |
93
+
94
+ #### Methods
95
+ * **`fit_bootstrap(X, Y, beta_hat)`**
96
+ * **`X`** (`np.ndarray`, shape `(n, d)`): Original covariate matrix.
97
+ * **`Y`** (`np.ndarray`, shape `(n,)`): Original binary outcome vector (`0` and `1`).
98
+ * **`beta_hat`** (`np.ndarray`, shape `(d,)`): Point estimate returned by `MaxScoreEstimator.fit(X, Y)` with `beta_hat[0] == 1.0`.
99
+ * **Returns:** `np.ndarray` of shape `(B, d)` containing the bootstrap parameter estimates $\beta^{*(b)}$.
100
+ * **`confidence_intervals(beta_hat, bootstrap_estimates, alpha=0.05)`**
101
+ * **`beta_hat`** (`np.ndarray`, shape `(d,)`): Original point estimate vector.
102
+ * **`bootstrap_estimates`** (`np.ndarray`, shape `(B, d)`): Matrix of bootstrap draws returned by `fit_bootstrap`.
103
+ * **`alpha`** (`float`, default `0.05`): Significance level for two-sided $(1 - \alpha)$ percentile confidence intervals (e.g., `0.05` produces 2.5% and 97.5% bounds).
104
+ * **Returns:** `np.ndarray` of shape `(d, 2)` where column `0` is the lower bound and column `1` is the upper bound.
105
+
106
+ ---
107
+
108
+ ### `PluginHessianEstimator`
109
+
110
+ Computes the analytical Gaussian kernel derivative plug-in estimator for the Hessian matrix $\tilde{H}$ with respect to the free parameters $\gamma = (\beta_2, \dots, \beta_d)^T$, matching `Hhat.cpp` from Cattaneo et al. (2020).
111
+
112
+ #### Initialization Arguments
113
+ ```python
114
+ PluginHessianEstimator(bw=2.0)
115
+ ```
116
+
117
+ | Parameter | Type | Default | Description |
118
+ | :--- | :--- | :--- | :--- |
119
+ | `bw` | `float` | `2.0` | Smoothing bandwidth for the standard Gaussian kernel derivative $K'(u) = -\frac{u}{\sqrt{2\pi}} e^{-u^2/2}$. |
120
+
121
+ #### Methods
122
+ * **`estimate(beta_hat, X, Y)`**
123
+ * **`beta_hat`** (`np.ndarray`, shape `(d,)`): Point estimate vector.
124
+ * **`X`** (`np.ndarray`, shape `(n, d)`): Covariate matrix.
125
+ * **`Y`** (`np.ndarray`, shape `(n,)`): Binary outcome vector (`0` and `1`).
126
+ * **Returns:** Symmetric `np.ndarray` of shape `(d - 1, d - 1)` representing the estimated Hessian matrix $\tilde{H}$.
127
+
128
+ ---
129
+
130
+ ## Reference
131
+ * Cattaneo, M. D., Jansson, M., & Nagasawa, K. (2020). *Bootstrap-Based Inference for Cube Root Consistent Estimators*. Econometrica, 88(5), 2203–2219.
@@ -0,0 +1,6 @@
1
+ from .estimator import MaxScoreEstimator
2
+ from .bootstrap import ReshapedBootstrap
3
+ from .hessian import PluginHessianEstimator
4
+
5
+ __all__ = ["MaxScoreEstimator", "ReshapedBootstrap", "PluginHessianEstimator"]
6
+ __version__ = "0.6.0"
@@ -0,0 +1,95 @@
1
+ import numpy as np
2
+ from scipy.optimize import differential_evolution
3
+ from .utils import kernel_regression_kappa
4
+ from .hessian import PluginHessianEstimator
5
+
6
+ class ReshapedBootstrap:
7
+ """
8
+ Implements the Cattaneo et al. (2020) Reshaped Bootstrap for Maximum Score Estimator
9
+ using a unified bandwidth for kernel regression and Hessian estimation,
10
+ with multi-start optimization via n_starts.
11
+ """
12
+ def __init__(self, B=200, bandwidth=2.0, bounds=(-10.0, 10.0), n_starts=3, seed=None):
13
+ self.B = B
14
+ self.bandwidth = bandwidth
15
+ self.bounds = bounds
16
+ self.n_starts = n_starts
17
+ self.seed = seed
18
+
19
+ def fit_bootstrap(self, X, Y, beta_hat):
20
+ n, d = X.shape
21
+ rng = np.random.default_rng(self.seed)
22
+
23
+ # 1. Estimate conditional probability kappa(x) via kernel regression using bandwidth
24
+ kappa_hat = kernel_regression_kappa(X, X, Y, self.bandwidth)
25
+
26
+ # 2. Compute analytical plug-in Hessian matrix at beta_hat using the same bandwidth
27
+ hess_engine = PluginHessianEstimator(bw=self.bandwidth)
28
+ H_hat = hess_engine.estimate(beta_hat, X, Y)
29
+
30
+ gamma_hat = beta_hat[1:]
31
+ bootstrap_estimates = []
32
+
33
+ for b in range(self.B):
34
+ print("reshaped bootstrap iteration...:",b)
35
+ indices = rng.choice(n, size=n, replace=True)
36
+ X_star = X[indices]
37
+ kappa_star = kappa_hat[indices]
38
+ ###Y_star = rng.binomial(1, kappa_star).astype(float)
39
+ Y_star = Y[indices]
40
+
41
+ def reshaped_objective(gamma):
42
+ beta = np.concatenate(([1.0], gamma))
43
+
44
+ # 1. Bootstrap objective M_n^*(beta)
45
+ scores_star = np.dot(X_star, beta)
46
+ ind_star = (scores_star >= 0).astype(float)
47
+ M_star = np.mean((2.0 * Y_star - 1.0) * ind_star)
48
+
49
+ # 2. Sample objective M_n(beta)
50
+ scores_sample = np.dot(X, beta)
51
+ ind_sample = (scores_sample >= 0).astype(float)
52
+ M_sample = np.mean((2.0 * Y - 1.0) * ind_sample)
53
+
54
+ # 3. Quadratic correction term: 0.5 * (gamma - gamma_hat)^T H_hat (gamma - gamma_hat)
55
+ diff_gamma = gamma - gamma_hat
56
+ quad_term = 0.5 * np.dot(diff_gamma, np.dot(H_hat, diff_gamma))
57
+
58
+ # Maximize M_star - M_sample + quad_term -> Minimize negative
59
+ val = M_star - M_sample + quad_term
60
+ return -val
61
+
62
+ bounds_list = [self.bounds for _ in range(d - 1)]
63
+
64
+ best_fun = np.inf
65
+ best_gamma = None
66
+
67
+ for s in range(self.n_starts):
68
+ run_seed = int(rng.integers(0, 1000000))
69
+ result = differential_evolution(
70
+ reshaped_objective,
71
+ bounds=bounds_list,
72
+ seed=run_seed,
73
+ polish=True,
74
+ strategy='rand1bin',
75
+ popsize=1500,
76
+ maxiter=5000
77
+ )
78
+ if result.fun < best_fun:
79
+ best_fun = result.fun
80
+ best_gamma = result.x
81
+
82
+ gamma_star = best_gamma
83
+ beta_star = np.concatenate(([1.0], gamma_star))
84
+ bootstrap_estimates.append(beta_star)
85
+
86
+ return np.array(bootstrap_estimates)
87
+
88
+ def confidence_intervals(self, beta_hat, bootstrap_estimates, alpha=0.05):
89
+ lower_pct = (alpha / 2) * 100
90
+ upper_pct = (1 - alpha / 2) * 100
91
+
92
+ ci_lower = np.percentile(bootstrap_estimates, lower_pct, axis=0)
93
+ ci_upper = np.percentile(bootstrap_estimates, upper_pct, axis=0)
94
+
95
+ return np.column_stack((ci_lower, ci_upper))
@@ -0,0 +1,50 @@
1
+ import numpy as np
2
+ from scipy.optimize import differential_evolution
3
+
4
+ class MaxScoreEstimator:
5
+ """
6
+ Computes Manski's Maximum Score Estimator with the first coefficient fixed to 1.
7
+ Parameter vector is parameterized as beta = [1, gamma^T].
8
+ Supports multi-start optimization via n_starts.
9
+ """
10
+ def __init__(self, bounds=(-10.0, 10.0), n_starts=3, seed=None):
11
+ self.bounds = bounds
12
+ self.n_starts = n_starts
13
+ self.seed = seed
14
+
15
+ def objective_function(self, gamma, X, Y):
16
+ beta = np.concatenate(([1.0], gamma))
17
+ scores = np.dot(X, beta)
18
+ indicator = (scores >= 0).astype(float)
19
+ val = np.mean((2.0 * Y - 1.0) * indicator)
20
+ return -val # Minimize negative score
21
+
22
+ def fit(self, X, Y):
23
+ n, d = X.shape
24
+ if d < 2:
25
+ raise ValueError("Maximum Score Estimator requires at least 2 regressors (d >= 2).")
26
+
27
+ bounds_list = [self.bounds for _ in range(d - 1)]
28
+ rng = np.random.default_rng(self.seed)
29
+
30
+ best_fun = np.inf
31
+ best_gamma = None
32
+
33
+ for i in range(self.n_starts):
34
+ run_seed = int(rng.integers(0, 1000000)) if self.seed is not None else None
35
+ result = differential_evolution(
36
+ self.objective_function,
37
+ bounds=bounds_list,
38
+ args=(X, Y),
39
+ seed=run_seed,
40
+ polish=True,
41
+ strategy='rand1bin',
42
+ popsize=1500,
43
+ maxiter=5000
44
+ )
45
+ if result.fun < best_fun:
46
+ best_fun = result.fun
47
+ best_gamma = result.x
48
+
49
+ gamma_hat = best_gamma
50
+ return np.concatenate(([1.0], gamma_hat))
@@ -0,0 +1,34 @@
1
+ import numpy as np
2
+
3
+ class PluginHessianEstimator:
4
+ """
5
+ Analytical plug-in estimator for the Hessian / score derivative matrix
6
+ matching Cattaneo et al. (2020) Hhat.cpp implementation using bandwidth bw.
7
+ """
8
+ def __init__(self, bw=2.0):
9
+ self.bw = bw
10
+
11
+ def _gaussian_kernel_derivative(self, u):
12
+ return -u / np.sqrt(2.0 * np.pi) * np.exp(-0.5 * u**2)
13
+
14
+ def estimate(self, beta_hat, X, Y):
15
+ n, d = X.shape
16
+ if d < 2:
17
+ raise ValueError("Hessian estimation requires at least 2 regressors.")
18
+
19
+ d_free = d - 1
20
+ H = np.zeros((d_free, d_free))
21
+
22
+ index = np.dot(X, beta_hat)
23
+ X_free = X[:, 1:] # Exclude first column corresponding to beta_1 = 1
24
+
25
+ for i in range(n):
26
+ u = index[i] / self.bw
27
+ k_prime = self._gaussian_kernel_derivative(u)
28
+ outer_x = np.outer(X_free[i], X_free[i])
29
+
30
+ term = (2.0 * Y[i] - 1.0) * (k_prime / (self.bw**2)) * outer_x
31
+ H += term
32
+
33
+ H = H / n
34
+ return 0.5 * (H + H.T)
@@ -0,0 +1,23 @@
1
+ import numpy as np
2
+
3
+ def kernel_pdf(u):
4
+ """Standard Gaussian kernel function."""
5
+ return np.exp(-0.5 * u**2) / np.sqrt(2 * np.pi)
6
+
7
+ def kernel_regression_kappa(x_eval, X, Y, h):
8
+ """
9
+ Nonparametric kernel regression estimator for kappa(x) = E[Y | X=x].
10
+ """
11
+ n, d = X.shape
12
+ kappa_vals = np.zeros(x_eval.shape[0])
13
+
14
+ for idx, x in enumerate(x_eval):
15
+ diff = (X - x) / h
16
+ weights = np.prod(kernel_pdf(diff), axis=1)
17
+ sum_w = np.sum(weights)
18
+ if sum_w < 1e-12:
19
+ kappa_vals[idx] = 0.5
20
+ else:
21
+ kappa_vals[idx] = np.sum(weights * Y) / sum_w
22
+
23
+ return np.clip(kappa_vals, 0.001, 0.999)
@@ -0,0 +1,143 @@
1
+ Metadata-Version: 2.4
2
+ Name: maxscoreCIpy
3
+ Version: 0.6.0
4
+ Summary: Cattaneo et al. (2020) Reshaped Bootstrap & Plug-in Hessian with fixed beta_1=1, unified bandwidth, and multi-start optimization
5
+ Project-URL: Homepage, https://github.com/kflorios/maxscoreCIpy
6
+ Requires-Python: >=3.8
7
+ Description-Content-Type: text/markdown
8
+ License-File: LICENSE
9
+ Requires-Dist: numpy>=1.20.0
10
+ Requires-Dist: scipy>=1.7.0
11
+ Dynamic: license-file
12
+
13
+ # maxscoreCIpy
14
+
15
+ Python implementation of Manski's Maximum Score Estimator with **fixed $\beta_1 = 1$**, Cattaneo, Jansson, and Nagasawa (2020) **Reshaped Bootstrap**, analytical Gaussian kernel plug-in Hessian estimation using a unified bandwidth parameter, and multi-start Differential Evolution (`n_starts`).
16
+
17
+ ## Installation
18
+
19
+ This package requires Python 3.8 or higher (`>=3.8`).
20
+
21
+ ```bash
22
+ pip install -e .
23
+ ```
24
+
25
+ ---
26
+
27
+ ## Quick Start Example
28
+
29
+ ```python
30
+ import numpy as np
31
+ from maxscoreCIpy import MaxScoreEstimator, ReshapedBootstrap, PluginHessianEstimator
32
+
33
+ # Generate synthetic data targeting beta = [1.0, 0.5]
34
+ np.random.seed(42)
35
+ n = 1000
36
+ X = np.random.uniform(-1, 1, size=(n, 2))
37
+ true_beta = np.array([1.0, 0.5])
38
+
39
+ latent = np.dot(X, true_beta) + np.random.normal(0, 0.3, size=n)
40
+ Y = (latent >= 0).astype(float)
41
+
42
+ # 1. Point Estimation (first coefficient fixed to 1)
43
+ estimator = MaxScoreEstimator(bounds=(-10.0, 10.0), n_starts=3, seed=42)
44
+ beta_hat = estimator.fit(X, Y)
45
+ print("Estimated Beta (beta_1 = 1 fixed):", beta_hat)
46
+
47
+ # 2. Analytical Plug-in Hessian Estimation
48
+ hessian_calc = PluginHessianEstimator(bw=0.3)
49
+ H_plugin = hessian_calc.estimate(beta_hat, X, Y)
50
+ print("Analytical Plug-in Hessian Matrix:\n", H_plugin)
51
+
52
+ # 3. Reshaped Bootstrap Confidence Intervals
53
+ boot = ReshapedBootstrap(B=50, bandwidth=0.3, local_window=2.0, n_starts=3, seed=42)
54
+ boot_estimates = boot.fit_bootstrap(X, Y, beta_hat)
55
+ ci_95 = boot.confidence_intervals(beta_hat, boot_estimates, alpha=0.05)
56
+ print("95% Confidence Intervals:\n", ci_95)
57
+ ```
58
+
59
+ ---
60
+
61
+ ## API Reference
62
+
63
+ ### `MaxScoreEstimator`
64
+
65
+ Computes Manski's Maximum Score Estimator with the first coefficient fixed to `1.0` ($\beta = [1, \gamma^T]$) to resolve scale and sign indeterminacy. Optimization is performed using multi-start Differential Evolution (`scipy.optimize.differential_evolution`).
66
+
67
+ #### Initialization Arguments
68
+ ```python
69
+ MaxScoreEstimator(bounds=(-10.0, 10.0), n_starts=3, seed=None)
70
+ ```
71
+
72
+ | Parameter | Type | Default | Description |
73
+ | :--- | :--- | :--- | :--- |
74
+ | `bounds` | `tuple[float, float]` | `(-10.0, 10.0)` | Lower and upper search bounds `(min, max)` applied to each free parameter $\gamma_j$ ($j = 2, \dots, d$). |
75
+ | `n_starts` | `int` | `3` | Number of independent Differential Evolution runs per optimization. The solution achieving the highest score (lowest negative objective value) is selected. |
76
+ | `seed` | `int` or `None` | `None` | Random seed used to initialize the internal RNG (`np.random.default_rng`) for reproducible multi-start runs. |
77
+
78
+ #### Methods
79
+ * **`fit(X, Y)`**
80
+ * **`X`** (`np.ndarray`, shape `(n, d)`): Design matrix of covariates ($d \ge 2$). The first column corresponds to the normalized coefficient $\beta_1 = 1.0$.
81
+ * **`Y`** (`np.ndarray`, shape `(n,)`): Binary outcome vector taking values `0` and `1` (or `0.0` and `1.0`).
82
+ * **Returns:** `np.ndarray` of shape `(d,)` containing `[1.0, gamma_hat_1, ..., gamma_hat_{d-1}]`.
83
+
84
+ ---
85
+
86
+ ### `ReshapedBootstrap`
87
+
88
+ Implements the Cattaneo, Jansson, and Nagasawa (2020) Reshaped Bootstrap for cube-root ($n^{1/3}$) consistent Maximum Score inference. In each bootstrap replication, it maximizes the reshaped objective function incorporating the analytical plug-in Hessian quadratic centering term:
89
+ $$
90
+ \tilde{M}_n^*(\gamma) = M_n^*(\gamma) - M_n(\gamma) + \frac{1}{2} (\gamma - \hat{\gamma})^T \tilde{H} (\gamma - \hat{\gamma})
91
+ $$
92
+
93
+ #### Initialization Arguments
94
+ ```python
95
+ ReshapedBootstrap(B=200, bandwidth=2.0, bounds=(-10.0, 10.0), n_starts=3, seed=None)
96
+ ```
97
+
98
+ | Parameter | Type | Default | Description |
99
+ | :--- | :--- | :--- | :--- |
100
+ | `B` | `int` | `200` | Number of bootstrap replications. Recommended minimum is `B >= 50` (typically `100–200`) for stable percentile confidence intervals. |
101
+ | `bandwidth` | `float` | `2.0` | Unified Gaussian kernel bandwidth applied to both the conditional probability regression $\hat{\kappa}(x) = \hat{E}[Y \mid X=x]$ and the analytical plug-in Hessian matrix $\tilde{H}$. Should be scaled to match the support of `X` (e.g., `0.3` for $X \sim U[-1, 1]$). |
102
+ | `bounds` | `tuple[float, float]` | `(-10.0, 10.0)` | Lower and upper search bounds `(min, max)` applied to each free parameter $\gamma_j$ ($j = 2, \dots, d$). |
103
+ | `n_starts` | `int` | `3` | Number of independent Differential Evolution runs executed within each bootstrap replication, retaining the best optimum. |
104
+ | `seed` | `int` or `None` | `None` | Random seed for reproducible resampling of $(X^*, Y^*)$ and Differential Evolution initializations. |
105
+
106
+ #### Methods
107
+ * **`fit_bootstrap(X, Y, beta_hat)`**
108
+ * **`X`** (`np.ndarray`, shape `(n, d)`): Original covariate matrix.
109
+ * **`Y`** (`np.ndarray`, shape `(n,)`): Original binary outcome vector (`0` and `1`).
110
+ * **`beta_hat`** (`np.ndarray`, shape `(d,)`): Point estimate returned by `MaxScoreEstimator.fit(X, Y)` with `beta_hat[0] == 1.0`.
111
+ * **Returns:** `np.ndarray` of shape `(B, d)` containing the bootstrap parameter estimates $\beta^{*(b)}$.
112
+ * **`confidence_intervals(beta_hat, bootstrap_estimates, alpha=0.05)`**
113
+ * **`beta_hat`** (`np.ndarray`, shape `(d,)`): Original point estimate vector.
114
+ * **`bootstrap_estimates`** (`np.ndarray`, shape `(B, d)`): Matrix of bootstrap draws returned by `fit_bootstrap`.
115
+ * **`alpha`** (`float`, default `0.05`): Significance level for two-sided $(1 - \alpha)$ percentile confidence intervals (e.g., `0.05` produces 2.5% and 97.5% bounds).
116
+ * **Returns:** `np.ndarray` of shape `(d, 2)` where column `0` is the lower bound and column `1` is the upper bound.
117
+
118
+ ---
119
+
120
+ ### `PluginHessianEstimator`
121
+
122
+ Computes the analytical Gaussian kernel derivative plug-in estimator for the Hessian matrix $\tilde{H}$ with respect to the free parameters $\gamma = (\beta_2, \dots, \beta_d)^T$, matching `Hhat.cpp` from Cattaneo et al. (2020).
123
+
124
+ #### Initialization Arguments
125
+ ```python
126
+ PluginHessianEstimator(bw=2.0)
127
+ ```
128
+
129
+ | Parameter | Type | Default | Description |
130
+ | :--- | :--- | :--- | :--- |
131
+ | `bw` | `float` | `2.0` | Smoothing bandwidth for the standard Gaussian kernel derivative $K'(u) = -\frac{u}{\sqrt{2\pi}} e^{-u^2/2}$. |
132
+
133
+ #### Methods
134
+ * **`estimate(beta_hat, X, Y)`**
135
+ * **`beta_hat`** (`np.ndarray`, shape `(d,)`): Point estimate vector.
136
+ * **`X`** (`np.ndarray`, shape `(n, d)`): Covariate matrix.
137
+ * **`Y`** (`np.ndarray`, shape `(n,)`): Binary outcome vector (`0` and `1`).
138
+ * **Returns:** Symmetric `np.ndarray` of shape `(d - 1, d - 1)` representing the estimated Hessian matrix $\tilde{H}$.
139
+
140
+ ---
141
+
142
+ ## Reference
143
+ * Cattaneo, M. D., Jansson, M., & Nagasawa, K. (2020). *Bootstrap-Based Inference for Cube Root Consistent Estimators*. Econometrica, 88(5), 2203–2219.
@@ -0,0 +1,13 @@
1
+ LICENSE
2
+ README.md
3
+ pyproject.toml
4
+ maxscoreCIpy/__init__.py
5
+ maxscoreCIpy/bootstrap.py
6
+ maxscoreCIpy/estimator.py
7
+ maxscoreCIpy/hessian.py
8
+ maxscoreCIpy/utils.py
9
+ maxscoreCIpy.egg-info/PKG-INFO
10
+ maxscoreCIpy.egg-info/SOURCES.txt
11
+ maxscoreCIpy.egg-info/dependency_links.txt
12
+ maxscoreCIpy.egg-info/requires.txt
13
+ maxscoreCIpy.egg-info/top_level.txt
@@ -0,0 +1,2 @@
1
+ numpy>=1.20.0
2
+ scipy>=1.7.0
@@ -0,0 +1 @@
1
+ maxscoreCIpy
@@ -0,0 +1,18 @@
1
+ [build-system]
2
+ requires = ["setuptools>=61.0.0", "wheel"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "maxscoreCIpy"
7
+ version = "0.6.0"
8
+ description = "Cattaneo et al. (2020) Reshaped Bootstrap & Plug-in Hessian with fixed beta_1=1, unified bandwidth, and multi-start optimization"
9
+ readme = "README.md"
10
+ requires-python = ">=3.8"
11
+ dependencies = [
12
+ "numpy>=1.20.0",
13
+ "scipy>=1.7.0"
14
+ ]
15
+
16
+
17
+ [project.urls]
18
+ Homepage = "https://github.com/kflorios/maxscoreCIpy"
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+