From 9b818312715bc0004c3c4887c7aa30a7357f5a25 Mon Sep 17 00:00:00 2001 From: Federico Molina Date: Sat, 18 Apr 2026 22:09:56 -0300 Subject: [PATCH] Add MCNNM fit API and tutorial examples --- src/causaltensor/cauest/MCNNM.py | 55 +- tests/test_mcnnm_fit.py | 97 + tutorials/Panel Data Example.ipynb | 1266 +++++----- tutorials/Panel_Data_Example.ipynb | 1300 +++++----- tutorials/datasets.ipynb | 3788 +++++++++++++++++++++------- 5 files changed, 4260 insertions(+), 2246 deletions(-) create mode 100644 tests/test_mcnnm_fit.py diff --git a/src/causaltensor/cauest/MCNNM.py b/src/causaltensor/cauest/MCNNM.py index 6c69440..c8a9fc7 100644 --- a/src/causaltensor/cauest/MCNNM.py +++ b/src/causaltensor/cauest/MCNNM.py @@ -87,6 +87,59 @@ def __init__(self, Z=None, X=None, Omega=None, fixed_effects = 'two-way'): self.FE_beta_solver = FixedEffectPanelSolver(fixed_effects=self.fixed_effects, X=self.X, Omega=self.Omega) self.return_tau_scalar = False + def fit( + self, + O=None, + suggest_r=None, + l=None, + K=None, + list_l=None, + M_init=None, + eps=1e-7, + max_iter=2000, + ): + """Fit MC-NNM using the solver implied by the provided arguments. + + Dispatch order is ``suggest_r`` > ``l`` > cross-validation. If neither + ``suggest_r`` nor ``l`` is provided, cross-validation is used with + ``K=2`` unless another ``K`` is specified. + + Parameters + ---------- + O: 2D numpy array + The observation matrix. + suggest_r: int or None + Suggested rank for ``solve_with_suggested_rank``. + l: float or None + Nuclear norm regularizer for ``solve_with_regularizer``. + K: int or None + Number of cross-validation folds for ``solve_with_cross_validation``. + list_l: iterable or None + Candidate regularizers for cross-validation. + M_init: 2D numpy array or None + Initial low-rank matrix for ``solve_with_regularizer``. + eps: float + Convergence threshold for ``solve_with_regularizer``. + max_iter: int + Maximum iterations for ``solve_with_regularizer``. + """ + if O is None: + raise ValueError("O must be provided.") + + if suggest_r is not None: + return self.solve_with_suggested_rank(O=O, suggest_r=suggest_r) + if l is not None: + return self.solve_with_regularizer( + O=O, + l=l, + M_init=M_init, + eps=eps, + max_iter=max_iter, + ) + if K is None: + K = 2 + return self.solve_with_cross_validation(O=O, K=K, list_l=list_l) + def solve_with_regularizer(self, O=None, l=None, M_init=None, eps=1e-7, max_iter=2000): """ Solve the matrix completion problem with nuclear norm regularizer and fixed effects Parameters @@ -214,4 +267,4 @@ def MC_NNM_with_suggested_rank(O, Omega, suggest_r=1): def MC_NNM_with_cross_validation(O, Omega, K=5, list_l=None): solver = MCNNMPanelSolver(Z = 1-Omega) res = solver.solve_with_cross_validation(O, K, list_l) - return res.M, res.row_fixed_effects, res.column_fixed_effects, res.tau \ No newline at end of file + return res.M, res.row_fixed_effects, res.column_fixed_effects, res.tau diff --git a/tests/test_mcnnm_fit.py b/tests/test_mcnnm_fit.py new file mode 100644 index 0000000..617d43d --- /dev/null +++ b/tests/test_mcnnm_fit.py @@ -0,0 +1,97 @@ +import numpy as np +import pytest + +from causaltensor.cauest.MCNNM import MCNNMPanelSolver + + +def make_solver(): + Z = np.zeros((3, 3), dtype=int) + Z[2, 2] = 1 + return MCNNMPanelSolver(Z=Z) + + +def test_fit_uses_suggested_rank_first(monkeypatch): + solver = make_solver() + O = np.arange(9, dtype=float).reshape(3, 3) + result = object() + calls = {} + + def fake_suggested_rank(*, O=None, suggest_r=1): + calls["O"] = O + calls["suggest_r"] = suggest_r + return result + + monkeypatch.setattr(solver, "solve_with_suggested_rank", fake_suggested_rank) + + assert solver.fit(O=O, suggest_r=2, l=0.5, K=3) is result + assert calls["O"] is O + assert calls["suggest_r"] == 2 + + +def test_fit_uses_regularizer_when_l_is_provided(monkeypatch): + solver = make_solver() + O = np.arange(9, dtype=float).reshape(3, 3) + M_init = np.ones_like(O) + result = object() + calls = {} + + def fake_regularizer( + *, + O=None, + l=None, + M_init=None, + eps=1e-7, + max_iter=2000, + ): + calls["O"] = O + calls["l"] = l + calls["M_init"] = M_init + calls["eps"] = eps + calls["max_iter"] = max_iter + return result + + monkeypatch.setattr(solver, "solve_with_regularizer", fake_regularizer) + + assert ( + solver.fit(O=O, l=0.5, K=3, M_init=M_init, eps=1e-5, max_iter=7) + is result + ) + assert calls["O"] is O + assert calls["l"] == 0.5 + assert calls["M_init"] is M_init + assert calls["eps"] == 1e-5 + assert calls["max_iter"] == 7 + + +def test_fit_uses_cross_validation_by_default(monkeypatch): + solver = make_solver() + O = np.arange(9, dtype=float).reshape(3, 3) + list_l = [0.1, 0.2] + result = object() + calls = {} + + def fake_cross_validation(*, O=None, K=2, list_l=None): + calls["O"] = O + calls["K"] = K + calls["list_l"] = list_l + return result + + monkeypatch.setattr(solver, "solve_with_cross_validation", fake_cross_validation) + + assert solver.fit(O=O, list_l=list_l) is result + assert calls["O"] is O + assert calls["K"] == 2 + assert calls["list_l"] is list_l + + calls.clear() + assert solver.fit(O=O, K=4, list_l=list_l) is result + assert calls["O"] is O + assert calls["K"] == 4 + assert calls["list_l"] is list_l + + +def test_fit_requires_observation_matrix(): + solver = make_solver() + + with pytest.raises(ValueError, match="O must be provided"): + solver.fit() diff --git a/tutorials/Panel Data Example.ipynb b/tutorials/Panel Data Example.ipynb index 573dac7..2fb6eae 100644 --- a/tutorials/Panel Data Example.ipynb +++ b/tutorials/Panel Data Example.ipynb @@ -1,661 +1,673 @@ { - "cells": [ - { - "cell_type": "markdown", - "metadata": { - "id": "hX0p5BzC9-vK" - }, - "source": [ - "# Panel Data Example\n", - "\n", - "In this example, we will use [California Smoke Data](https://www.tandfonline.com/doi/abs/10.1198/jasa.2009.ap08746) [1] to show the usage of [CausalTensor](https://github.com/TianyiPeng/causaltensor) package.\n", - "\n", - "[1] Abadie, Alberto, Alexis Diamond, and Jens Hainmueller. \"Synthetic control methods for comparative case studies: Estimating the effect of California’s tobacco control program.\" Journal of the American statistical Association 105, no. 490 (2010): 493-505." - ] - }, - { - "cell_type": "code", - "execution_count": 1, - "metadata": { - "id": "ecYezNjLW3VZ" - }, - "outputs": [], - "source": [ - "import numpy as np" - ] - }, - { - "cell_type": "markdown", - "metadata": { - "id": "gAmMRnIV9uDq" - }, - "source": [ - "Install and import `causaltensor` package" - ] - }, - { - "cell_type": "code", - "execution_count": 2, - "metadata": { - "colab": { - "base_uri": "https://localhost:8080/" - }, - "id": "yoqZkdZJ3tAR", - "outputId": "009e0fef-2993-47e7-96b9-7929a08a48c0" - }, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Requirement already satisfied: causaltensor in /Users/tianyipeng/anaconda3/lib/python3.11/site-packages (0.1.12)\n", - "Requirement already satisfied: cvxopt<2.0,>=1.2 in /Users/tianyipeng/anaconda3/lib/python3.11/site-packages (from causaltensor) (1.3.2)\n", - "Requirement already satisfied: cvxpy<2.0.0,>=1.4.3 in /Users/tianyipeng/anaconda3/lib/python3.11/site-packages (from causaltensor) (1.6.3)\n", - "Requirement already satisfied: matplotlib<4.0.0,>=3.8.0 in /Users/tianyipeng/anaconda3/lib/python3.11/site-packages (from causaltensor) (3.10.1)\n", - "Requirement already satisfied: numpy<2.0,>=1.18 in /Users/tianyipeng/anaconda3/lib/python3.11/site-packages (from causaltensor) (1.24.3)\n", - "Requirement already satisfied: pandas<3.0.0,>=2.1.0 in /Users/tianyipeng/anaconda3/lib/python3.11/site-packages (from causaltensor) (2.2.3)\n", - "Requirement already satisfied: toolz<0.13.0,>=0.12.1 in /Users/tianyipeng/anaconda3/lib/python3.11/site-packages (from causaltensor) (0.12.1)\n", - "Requirement already satisfied: tqdm<5.0.0,>=4.67.1 in /Users/tianyipeng/anaconda3/lib/python3.11/site-packages (from causaltensor) (4.67.1)\n", - "Requirement already satisfied: osqp>=0.6.2 in /Users/tianyipeng/anaconda3/lib/python3.11/site-packages (from cvxpy<2.0.0,>=1.4.3->causaltensor) (0.6.7.post3)\n", - "Requirement already satisfied: clarabel>=0.5.0 in /Users/tianyipeng/anaconda3/lib/python3.11/site-packages (from cvxpy<2.0.0,>=1.4.3->causaltensor) (0.10.0)\n", - "Requirement already satisfied: scs>=3.2.4.post1 in /Users/tianyipeng/anaconda3/lib/python3.11/site-packages (from cvxpy<2.0.0,>=1.4.3->causaltensor) (3.2.7.post2)\n", - "Requirement already satisfied: scipy>=1.11.0 in /Users/tianyipeng/anaconda3/lib/python3.11/site-packages (from cvxpy<2.0.0,>=1.4.3->causaltensor) (1.11.1)\n", - "Requirement already satisfied: contourpy>=1.0.1 in /Users/tianyipeng/anaconda3/lib/python3.11/site-packages (from matplotlib<4.0.0,>=3.8.0->causaltensor) (1.0.5)\n", - "Requirement already satisfied: cycler>=0.10 in /Users/tianyipeng/anaconda3/lib/python3.11/site-packages (from matplotlib<4.0.0,>=3.8.0->causaltensor) (0.11.0)\n", - "Requirement already satisfied: fonttools>=4.22.0 in /Users/tianyipeng/anaconda3/lib/python3.11/site-packages (from matplotlib<4.0.0,>=3.8.0->causaltensor) (4.25.0)\n", - "Requirement already satisfied: kiwisolver>=1.3.1 in /Users/tianyipeng/anaconda3/lib/python3.11/site-packages (from matplotlib<4.0.0,>=3.8.0->causaltensor) (1.4.4)\n", - "Requirement already satisfied: packaging>=20.0 in /Users/tianyipeng/anaconda3/lib/python3.11/site-packages (from matplotlib<4.0.0,>=3.8.0->causaltensor) (24.2)\n", - "Requirement already satisfied: pillow>=8 in /Users/tianyipeng/anaconda3/lib/python3.11/site-packages (from matplotlib<4.0.0,>=3.8.0->causaltensor) (9.4.0)\n", - "Requirement already satisfied: pyparsing>=2.3.1 in /Users/tianyipeng/anaconda3/lib/python3.11/site-packages (from matplotlib<4.0.0,>=3.8.0->causaltensor) (3.0.9)\n", - "Requirement already satisfied: python-dateutil>=2.7 in /Users/tianyipeng/anaconda3/lib/python3.11/site-packages (from matplotlib<4.0.0,>=3.8.0->causaltensor) (2.8.2)\n", - "Requirement already satisfied: pytz>=2020.1 in /Users/tianyipeng/anaconda3/lib/python3.11/site-packages (from pandas<3.0.0,>=2.1.0->causaltensor) (2023.3.post1)\n", - "Requirement already satisfied: tzdata>=2022.7 in /Users/tianyipeng/anaconda3/lib/python3.11/site-packages (from pandas<3.0.0,>=2.1.0->causaltensor) (2023.3)\n", - "Requirement already satisfied: qdldl in /Users/tianyipeng/anaconda3/lib/python3.11/site-packages (from osqp>=0.6.2->cvxpy<2.0.0,>=1.4.3->causaltensor) (0.1.7.post5)\n", - "Requirement already satisfied: six>=1.5 in /Users/tianyipeng/anaconda3/lib/python3.11/site-packages (from python-dateutil>=2.7->matplotlib<4.0.0,>=3.8.0->causaltensor) (1.16.0)\n", - "\u001b[33mWARNING: There was an error checking the latest version of pip.\u001b[0m\u001b[33m\n", - "\u001b[0m" - ] - } - ], - "source": [ - "!pip install causaltensor #install the causaltensor package\n", - "import causaltensor as ct" - ] - }, - { - "cell_type": "markdown", - "metadata": { - "id": "Eea_IhaL94-s" - }, - "source": [ - "## Load Data\n", - "\n", - "*California Smoke Data* consists of annual tobacco consumption (smoking consumption in packs per capita) of 39 states from 1970 to 2000.\n", - "\n", - "Among those states, California (the treated state) started a state-level tobacco control program in 1989; while other states largely serve as control states. The problem at hand is to evaluate the impact of this program to the tobacco consumption in California given the data.\n", - "\n", - "Let's first download the data." - ] - }, - { - "cell_type": "code", - "execution_count": 3, - "metadata": { - "colab": { - "base_uri": "https://localhost:8080/" - }, - "id": "76t1BOKU8Cqv", - "outputId": "a0fe1e47-aeaf-473f-f30c-46d54e7a8dba" - }, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - " % Total % Received % Xferd Average Speed Time Time Time Current\n", - " Dload Upload Total Spent Left Speed\n", - " 0 0 0 0 0 0 0 0 --:--:-- --:--:-- --:--:-- 0\n", - "100 6868 100 6868 0 0 15276 0 --:--:-- --:--:-- --:--:-- 15276\n", - "Archive: Synth.zip\n", - " inflating: synth_code.m \n", - " inflating: readme_synth_matlab.txt \n", - " inflating: MLAB_data.txt \n", - " inflating: loss_function.m \n" - ] - } - ], - "source": [ - "!curl https://github.com/TianyiPeng/causaltensor/raw/main/tutorials/Synth.zip -L -o Synth.zip\n", - "!unzip -o Synth.zip" - ] - }, - { - "cell_type": "markdown", - "metadata": { - "id": "WowuKbHEBqoX" - }, - "source": [ - "Load and pre-process the outcome data" - ] - }, - { - "cell_type": "code", - "execution_count": 4, - "metadata": { - "colab": { - "base_uri": "https://localhost:8080/" - }, - "id": "QMDAQqZuW3Vc", - "outputId": "e31add20-41bb-4c50-edff-c701c12b29da" - }, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "(39, 31)\n" - ] - } - ], - "source": [ - "O_raw = np.loadtxt('MLAB_data.txt')\n", - "O = O_raw[8:, :] ## remove features that are not relevant in this demo\n", - "O = O.T\n", - "print(O.shape)\n", - "## now O consists of the annual tobacco consumption of 39 states from 1970 to 2000\n", - "## California is the last row of O" - ] - }, - { - "cell_type": "markdown", - "metadata": { - "id": "7kGd_eePCxcA" - }, - "source": [ - "Let's take a look for the California data" - ] - }, - { - "cell_type": "code", - "execution_count": 5, - "metadata": { - "colab": { - "base_uri": "https://localhost:8080/", - "height": 448 - }, - "id": "5kWHT611W3Vc", - "outputId": "610551aa-a588-4f2e-da61-07158b776a9f" - }, - "outputs": [ - { - "data": { - "text/plain": [ - "[]" - ] - }, - "execution_count": 5, - "metadata": {}, - "output_type": "execute_result" - }, - { - "data": { - "image/png": "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", - "text/plain": [ - "
" - ] - }, - "metadata": {}, - "output_type": "display_data" - } - ], - "source": [ - "import matplotlib.pyplot as plt\n", - "\n", - "plt.plot(O[-1, :])" - ] - }, - { - "cell_type": "markdown", - "metadata": { - "id": "qx0HCNW5DHBh" - }, - "source": [ - "Prepare intervention matrix $Z$ that indicates whether the intervention is implemented or not" - ] - }, - { - "cell_type": "code", - "execution_count": 6, - "metadata": { - "id": "OKOaSdNDW3Vd" - }, - "outputs": [], - "source": [ - "Z = np.zeros_like(O) # Z has the same shape as O\n", - "Z[-1, 19:] = 1 #Only California (the last row) used the intervention, which started in 1989" - ] - }, - { - "cell_type": "markdown", - "metadata": { - "id": "nrbswjpjEPEa" - }, - "source": [ - "## Estimators\n", - "\n", - "Now after we have the outcome data ($O \\in R^{n\\times T}$) and the intervention data ($Z \\in R^{n\\times T}$), let's show a few methods that can be used directly to assess the impact of the intervention." - ] - }, - { - "cell_type": "markdown", - "metadata": { - "id": "NHJX5Sd6W3Ve" - }, - "source": [ - "## DID estimation\n", - "\n", - "The first method is difference-in-difference (DID). We use a two-way fixed effects regression to estimate the average treatment effect on the treated entries (ATT). In particular, we solve the following regression by linear regression\n", - "$$\n", - "\\min \\sum_{ij} (O_{ij} - a_i - b_j - \\tau Z_{ij})^2\n", - "$$\n", - "where $a_{i}, b_{j}$ are unknown fixed effects and $\\tau$ is the ATT.\n", - "\n", - "To use DID, simply call\n", - "```\n", - "M, tau = DID(O, Z)\n", - "````\n", - "with two return parameters `M` and `tau`. Here $M_{ij}=a_{i}+b_{j}$ is the estimated ideal outcomes; and `tau` is the estimated ATT." - ] + "cells": [ + { + "cell_type": "markdown", + "metadata": { + "id": "hX0p5BzC9-vK" + }, + "source": [ + "# Panel Data Example\n", + "\n", + "In this example, we will use [California Smoke Data](https://www.tandfonline.com/doi/abs/10.1198/jasa.2009.ap08746) [1] to show the usage of [CausalTensor](https://github.com/TianyiPeng/causaltensor) package.\n", + "\n", + "[1] Abadie, Alberto, Alexis Diamond, and Jens Hainmueller. \"Synthetic control methods for comparative case studies: Estimating the effect of California’s tobacco control program.\" Journal of the American statistical Association 105, no. 490 (2010): 493-505." + ] + }, + { + "cell_type": "code", + "execution_count": 1, + "metadata": { + "id": "ecYezNjLW3VZ" + }, + "outputs": [], + "source": [ + "import numpy as np\n" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "id": "gAmMRnIV9uDq" + }, + "source": [ + "Install and import `causaltensor` package" + ] + }, + { + "cell_type": "code", + "execution_count": 2, + "metadata": { + "colab": { + "base_uri": "https://localhost:8080/" }, - { - "cell_type": "code", - "execution_count": 7, - "metadata": { - "colab": { - "base_uri": "https://localhost:8080/" - }, - "id": "cDDMODb7W3Vf", - "outputId": "5adecf08-4180-41fe-ac36-e6f74b6fcc7d" - }, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "The estimation of DID is -27.349111083614964\n" - ] - } - ], - "source": [ - "from causaltensor.cauest import DID\n", - "\n", - "M, tau = DID(O, Z)\n", - "print('The estimation of DID is', tau)" - ] + "id": "yoqZkdZJ3tAR", + "outputId": "009e0fef-2993-47e7-96b9-7929a08a48c0" + }, + "outputs": [], + "source": [ + "import numpy as np\n", + "from pathlib import Path\n", + "import subprocess\n", + "import sys\n", + "\n", + "\n", + "def find_project_root(start):\n", + " for candidate in (start, *start.parents):\n", + " if (candidate / \"src\" / \"causaltensor\" / \"cauest\" / \"MCNNM.py\").exists():\n", + " return candidate\n", + " return None\n", + "\n", + "\n", + "PROJECT_ROOT = find_project_root(Path.cwd().resolve())\n", + "if PROJECT_ROOT is not None:\n", + " sys.path.insert(0, str(PROJECT_ROOT / \"src\"))\n", + " for module_name in list(sys.modules):\n", + " if module_name == \"causaltensor\" or module_name.startswith(\"causaltensor.\"):\n", + " del sys.modules[module_name]\n", + " TUTORIALS_DIR = PROJECT_ROOT / \"tutorials\"\n", + "else:\n", + " subprocess.check_call([sys.executable, \"-m\", \"pip\", \"install\", \"causaltensor\"])\n", + " TUTORIALS_DIR = Path.cwd()\n", + "\n", + "import causaltensor as ct\n" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "id": "Eea_IhaL94-s" + }, + "source": [ + "## Load Data\n", + "\n", + "*California Smoke Data* consists of annual tobacco consumption (smoking consumption in packs per capita) of 39 states from 1970 to 2000.\n", + "\n", + "Among those states, California (the treated state) started a state-level tobacco control program in 1989; while other states largely serve as control states. The problem at hand is to evaluate the impact of this program to the tobacco consumption in California given the data.\n", + "\n", + "Let's first download the data." + ] + }, + { + "cell_type": "code", + "execution_count": 3, + "metadata": { + "colab": { + "base_uri": "https://localhost:8080/" }, + "id": "76t1BOKU8Cqv", + "outputId": "a0fe1e47-aeaf-473f-f30c-46d54e7a8dba" + }, + "outputs": [ { - "cell_type": "markdown", - "metadata": { - "id": "wIyuxrU1W3Vi" - }, - "source": [ - "## Debiased Convex Panel Regression\n", - "\n", - "The second method is De-biaeed Convex Panel Regression (DC-PR) proposed by [2].\n", - "Note that an issue of the DID model is that, $a_i+b_j$ are often too simple to describe the complex reality of the outcome. As a fix, a low-rank factor model to generalize $a_i+b_j$ has been advocated.\n", - "\n", - "The idea in [2] is to firstly solve the following low-rank regression problem by replacing $a_i+b_j$ in DID by a low-rank matrix $M$\n", - "$$\n", - "\\hat{M}, \\hat{\\tau} = \\arg\\min \\sum_{ij} (O_{ij}-M_{ij}-\\tau Z_{ij})^2 + \\lambda \\|M\\|_{*}\n", - "$$\n", - "where $\\|M\\|_{*}$ is the nuclear norm to penalize the low-rankness of the matrix and $\\lambda$ is a tunning parameter. The second step of [2] is to mitigate the bias induced by the regularization parameter (it also reflects the interaction between $\\hat{M}$ and $Z$):\n", - "$$\n", - "\\tau^{d} = \\hat{\\tau} - \\lambda \\frac{}{\\|P_{\\hat{T}^{\\perp}}(Z)\\|_{F}^2}.\n", - "$$\n", - "See [2] for more details.\n", - "\n", - "To use DC-PR, call\n", - "```\n", - "M, tau, std = DC_PR_auto_rank(O, Z)\n", - "```\n", - "where `M`, `tau` are the final estimators for the low-rank matrix and the treatment effects respectively. In addition `std` is the stanard deviation estimation for `tau`, using the formula in [2] for the scenarios when noises are (heterogenoues) independent sub-Gaussian. This function helps to find the proper rank for $M$ (but not very stable, and may be updated later). You can also use\n", - "```\n", - "M, tau, std = DC_PR_with_suggested_rank(O, Z, suggest_r = r)\n", - "```\n", - "if you have an estimation of the rank of $M$ by yourself.\n", - "\n", - "[2] Farias, Vivek, Andrew Li, and Tianyi Peng. \"Learning treatment effects in panels with general intervention patterns.\" Advances in Neural Information Processing Systems 34 (2021): 14001-14013." - ] + "name": "stdout", + "output_type": "stream", + "text": [ + "Using tutorial data from /Users/federicomolina/Documents/github/causaltensor/tutorials\n" + ] + } + ], + "source": [ + "from pathlib import Path\n", + "import urllib.request\n", + "import zipfile\n", + "\n", + "DATA_DIR = TUTORIALS_DIR if (TUTORIALS_DIR / \"MLAB_data.txt\").exists() else Path.cwd()\n", + "\n", + "if not (DATA_DIR / \"MLAB_data.txt\").exists():\n", + " zip_path = Path.cwd() / \"Synth.zip\"\n", + " urllib.request.urlretrieve(\n", + " \"https://github.com/TianyiPeng/causaltensor/raw/main/tutorials/Synth.zip\",\n", + " zip_path,\n", + " )\n", + " with zipfile.ZipFile(zip_path) as archive:\n", + " archive.extractall(Path.cwd())\n", + " DATA_DIR = Path.cwd()\n", + "\n", + "print(f\"Using tutorial data from {DATA_DIR}\")\n" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "id": "WowuKbHEBqoX" + }, + "source": [ + "Load and pre-process the outcome data" + ] + }, + { + "cell_type": "code", + "execution_count": 4, + "metadata": { + "colab": { + "base_uri": "https://localhost:8080/" }, + "id": "QMDAQqZuW3Vc", + "outputId": "e31add20-41bb-4c50-edff-c701c12b29da" + }, + "outputs": [ { - "cell_type": "code", - "execution_count": 8, - "metadata": { - "colab": { - "base_uri": "https://localhost:8080/" - }, - "id": "bRaYUEO9W3Vi", - "outputId": "758062db-c9c5-469d-80a2-78e5a2b1b43d" - }, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "The estimation of DC_PR is -16.01057737065886 3.013020638540673\n" - ] - } - ], - "source": [ - "from causaltensor.cauest import DC_PR_with_suggested_rank\n", - "from causaltensor.cauest import DC_PR_auto_rank\n", - "\n", - "#M, tau, std = DebiasConvex.DC_PR_with_suggested_rank(O, Z, suggest_r = 2)\n", - "M, tau, std = DC_PR_auto_rank(O, Z)\n", - "print('The estimation of DC_PR is', tau, std)" - ] + "name": "stdout", + "output_type": "stream", + "text": [ + "(39, 31)\n" + ] + } + ], + "source": [ + "O_raw = np.loadtxt(DATA_DIR / \"MLAB_data.txt\")\n", + "O = O_raw[8:, :] ## remove features that are not relevant in this demo\n", + "O = O.T\n", + "print(O.shape)\n", + "## now O consists of the annual tobacco consumption of 39 states from 1970 to 2000\n", + "## California is the last row of O\n" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "id": "7kGd_eePCxcA" + }, + "source": [ + "Let's take a look for the California data" + ] + }, + { + "cell_type": "code", + "execution_count": 5, + "metadata": { + "colab": { + "base_uri": "https://localhost:8080/", + "height": 448 }, + "id": "5kWHT611W3Vc", + "outputId": "610551aa-a588-4f2e-da61-07158b776a9f" + }, + "outputs": [ { - "cell_type": "markdown", - "metadata": { - "id": "3T1wQP1A3QG0" - }, - "source": [ - "We also implemented the panel regression with a hard rank constraint:\n", - "$$\n", - "\\hat{M}, \\hat{\\tau} = \\arg\\min_{rank(M)\\leq r} \\sum_{ij} (O_{ij}-M_{ij}-\\tau Z_{ij})^2\n", - "$$\n", - "This is a non-convex optimization problem and we used the alternate minimization between $M$ and $\\tau$ for the optimization. The theoretical guarantee for this non-convex method is weaker than the convex method above (the convergence to the global optimum is not always guaranteed), but the practical performance is comparable (sometimes even better). " + "data": { + "text/plain": [ + "[]" ] + }, + "execution_count": 5, + "metadata": {}, + "output_type": "execute_result" }, { - "cell_type": "code", - "execution_count": 9, - "metadata": { - "colab": { - "base_uri": "https://localhost:8080/" - }, - "id": "d-5lTg384O8h", - "outputId": "352264fb-0bf4-44fa-ace9-003dcd1301f9" - }, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "-15.880704119035332 3.011813924289439\n" - ] - } - ], - "source": [ - "M, tau, std = DC_PR_with_suggested_rank(O, Z, suggest_r = 2, method='non-convex')\n", - "print(tau, std)" + "data": { + "image/png": "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", + "text/plain": [ + "
" ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "import matplotlib.pyplot as plt\n", + "\n", + "plt.plot(O[-1, :])" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "id": "qx0HCNW5DHBh" + }, + "source": [ + "Prepare intervention matrix $Z$ that indicates whether the intervention is implemented or not" + ] + }, + { + "cell_type": "code", + "execution_count": 6, + "metadata": { + "id": "OKOaSdNDW3Vd" + }, + "outputs": [], + "source": [ + "Z = np.zeros_like(O) # Z has the same shape as O\n", + "Z[-1, 19:] = 1 #Only California (the last row) used the intervention, which started in 1989" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "id": "nrbswjpjEPEa" + }, + "source": [ + "## Estimators\n", + "\n", + "Now after we have the outcome data ($O \\in R^{n\\times T}$) and the intervention data ($Z \\in R^{n\\times T}$), let's show a few methods that can be used directly to assess the impact of the intervention." + ] + }, + { + "cell_type": "markdown", + "metadata": { + "id": "NHJX5Sd6W3Ve" + }, + "source": [ + "## DID estimation\n", + "\n", + "The first method is difference-in-difference (DID). We use a two-way fixed effects regression to estimate the average treatment effect on the treated entries (ATT). In particular, we solve the following regression by linear regression\n", + "$$\n", + "\\min \\sum_{ij} (O_{ij} - a_i - b_j - \\tau Z_{ij})^2\n", + "$$\n", + "where $a_{i}, b_{j}$ are unknown fixed effects and $\\tau$ is the ATT.\n", + "\n", + "To use DID, simply call\n", + "```\n", + "M, tau = DID(O, Z)\n", + "````\n", + "with two return parameters `M` and `tau`. Here $M_{ij}=a_{i}+b_{j}$ is the estimated ideal outcomes; and `tau` is the estimated ATT." + ] + }, + { + "cell_type": "code", + "execution_count": 7, + "metadata": { + "colab": { + "base_uri": "https://localhost:8080/" }, + "id": "cDDMODb7W3Vf", + "outputId": "5adecf08-4180-41fe-ac36-e6f74b6fcc7d" + }, + "outputs": [ { - "cell_type": "markdown", - "metadata": { - "id": "pyJDPbgr4w9B" - }, - "source": [ - "We also provide an option to select `convex` or `non-convex` panel regression in a data-driven fasion. This is recommended in practice." - ] + "name": "stdout", + "output_type": "stream", + "text": [ + "The estimation of DID is -27.349111083614957\n" + ] + } + ], + "source": [ + "from causaltensor.cauest import DID\n", + "\n", + "M, tau = DID(O, Z)\n", + "print('The estimation of DID is', tau)" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "id": "wIyuxrU1W3Vi" + }, + "source": [ + "## Debiased Convex Panel Regression\n", + "\n", + "The second method is De-biaeed Convex Panel Regression (DC-PR) proposed by [2].\n", + "Note that an issue of the DID model is that, $a_i+b_j$ are often too simple to describe the complex reality of the outcome. As a fix, a low-rank factor model to generalize $a_i+b_j$ has been advocated.\n", + "\n", + "The idea in [2] is to firstly solve the following low-rank regression problem by replacing $a_i+b_j$ in DID by a low-rank matrix $M$\n", + "$$\n", + "\\hat{M}, \\hat{\\tau} = \\arg\\min \\sum_{ij} (O_{ij}-M_{ij}-\\tau Z_{ij})^2 + \\lambda \\|M\\|_{*}\n", + "$$\n", + "where $\\|M\\|_{*}$ is the nuclear norm to penalize the low-rankness of the matrix and $\\lambda$ is a tunning parameter. The second step of [2] is to mitigate the bias induced by the regularization parameter (it also reflects the interaction between $\\hat{M}$ and $Z$):\n", + "$$\n", + "\\tau^{d} = \\hat{\\tau} - \\lambda \\frac{}{\\|P_{\\hat{T}^{\\perp}}(Z)\\|_{F}^2}.\n", + "$$\n", + "See [2] for more details.\n", + "\n", + "To use DC-PR, call\n", + "```\n", + "M, tau, std = DC_PR_auto_rank(O, Z)\n", + "```\n", + "where `M`, `tau` are the final estimators for the low-rank matrix and the treatment effects respectively. In addition `std` is the stanard deviation estimation for `tau`, using the formula in [2] for the scenarios when noises are (heterogenoues) independent sub-Gaussian. This function helps to find the proper rank for $M$ (but not very stable, and may be updated later). You can also use\n", + "```\n", + "M, tau, std = DC_PR_with_suggested_rank(O, Z, suggest_r = r)\n", + "```\n", + "if you have an estimation of the rank of $M$ by yourself.\n", + "\n", + "[2] Farias, Vivek, Andrew Li, and Tianyi Peng. \"Learning treatment effects in panels with general intervention patterns.\" Advances in Neural Information Processing Systems 34 (2021): 14001-14013." + ] + }, + { + "cell_type": "code", + "execution_count": 8, + "metadata": { + "colab": { + "base_uri": "https://localhost:8080/" }, + "id": "bRaYUEO9W3Vi", + "outputId": "758062db-c9c5-469d-80a2-78e5a2b1b43d" + }, + "outputs": [ { - "cell_type": "code", - "execution_count": 10, - "metadata": { - "colab": { - "base_uri": "https://localhost:8080/" - }, - "id": "eDEig1Oj4wbu", - "outputId": "2287a7f5-9c1d-4d7f-cd49-74f9c6b7a7bf" - }, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "-15.880704119035332 3.011813924289439\n" - ] - } - ], - "source": [ - "M, tau, std = DC_PR_with_suggested_rank(O, Z, suggest_r = 2, method='auto')\n", - "print(tau, std)" - ] + "name": "stdout", + "output_type": "stream", + "text": [ + "The estimation of DC_PR is -16.010577370658964 3.0130206385406946\n" + ] + } + ], + "source": [ + "from causaltensor.cauest import DC_PR_with_suggested_rank\n", + "from causaltensor.cauest import DC_PR_auto_rank\n", + "\n", + "#M, tau, std = DebiasConvex.DC_PR_with_suggested_rank(O, Z, suggest_r = 2)\n", + "M, tau, std = DC_PR_auto_rank(O, Z)\n", + "print('The estimation of DC_PR is', tau, std)" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "id": "3T1wQP1A3QG0" + }, + "source": [ + "We also implemented the panel regression with a hard rank constraint:\n", + "$$\n", + "\\hat{M}, \\hat{\\tau} = \\arg\\min_{rank(M)\\leq r} \\sum_{ij} (O_{ij}-M_{ij}-\\tau Z_{ij})^2\n", + "$$\n", + "This is a non-convex optimization problem and we used the alternate minimization between $M$ and $\\tau$ for the optimization. The theoretical guarantee for this non-convex method is weaker than the convex method above (the convergence to the global optimum is not always guaranteed), but the practical performance is comparable (sometimes even better). " + ] + }, + { + "cell_type": "code", + "execution_count": 9, + "metadata": { + "colab": { + "base_uri": "https://localhost:8080/" }, + "id": "d-5lTg384O8h", + "outputId": "352264fb-0bf4-44fa-ace9-003dcd1301f9" + }, + "outputs": [ { - "cell_type": "markdown", - "metadata": { - "id": "5TE1lOIsW3Vg" - }, - "source": [ - "## SDID estimation\n", - "\n", - "The second method is called synthetic difference-in-difference (SDID) proposed by [3]. Readers can read [3] for more details. To use SDID, simply call\n", - "```\n", - "tau = SDID(O, Z)\n", - "```\n", - "where `tau` is the estimation of SDID.\n", - "\n", - "[3] Arkhangelsky, Dmitry, Susan Athey, David A. Hirshberg, Guido W. Imbens, and Stefan Wager. \"Synthetic difference-in-differences.\" American Economic Review 111, no. 12 (2021): 4088-4118." - ] + "name": "stdout", + "output_type": "stream", + "text": [ + "-15.880704119035295 3.0118139242894277\n" + ] + } + ], + "source": [ + "M, tau, std = DC_PR_with_suggested_rank(O, Z, suggest_r = 2, method='non-convex')\n", + "print(tau, std)" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "id": "pyJDPbgr4w9B" + }, + "source": [ + "We also provide an option to select `convex` or `non-convex` panel regression in a data-driven fasion. This is recommended in practice." + ] + }, + { + "cell_type": "code", + "execution_count": 10, + "metadata": { + "colab": { + "base_uri": "https://localhost:8080/" }, + "id": "eDEig1Oj4wbu", + "outputId": "2287a7f5-9c1d-4d7f-cd49-74f9c6b7a7bf" + }, + "outputs": [ { - "cell_type": "code", - "execution_count": 11, - "metadata": { - "colab": { - "base_uri": "https://localhost:8080/" - }, - "id": "NrEirNOEW3Vg", - "outputId": "85a20188-df0d-4572-9852-5853bd5dd58e" - }, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "The estimation of SDID is -15.602326126984675\n" - ] - } - ], - "source": [ - "from causaltensor.cauest import SDID\n", - "\n", - "## to use SDID, cvxopt package is needed\n", - "\n", - "tau = SDID(O, Z)\n", - "print('The estimation of SDID is', tau) ## The result matched the result in [2]" - ] + "name": "stdout", + "output_type": "stream", + "text": [ + "-15.880704119035295 3.0118139242894277\n" + ] + } + ], + "source": [ + "M, tau, std = DC_PR_with_suggested_rank(O, Z, suggest_r = 2, method='auto')\n", + "print(tau, std)" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "id": "5TE1lOIsW3Vg" + }, + "source": [ + "## SDID estimation\n", + "\n", + "The second method is called synthetic difference-in-difference (SDID) proposed by [3]. Readers can read [3] for more details. To use SDID, simply call\n", + "```\n", + "tau = SDID(O, Z)\n", + "```\n", + "where `tau` is the estimation of SDID.\n", + "\n", + "[3] Arkhangelsky, Dmitry, Susan Athey, David A. Hirshberg, Guido W. Imbens, and Stefan Wager. \"Synthetic difference-in-differences.\" American Economic Review 111, no. 12 (2021): 4088-4118." + ] + }, + { + "cell_type": "code", + "execution_count": 11, + "metadata": { + "colab": { + "base_uri": "https://localhost:8080/" }, + "id": "NrEirNOEW3Vg", + "outputId": "85a20188-df0d-4572-9852-5853bd5dd58e" + }, + "outputs": [ { - "cell_type": "code", - "execution_count": 12, - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "p = 1, SDID tau = -16.54070037591654\n", - "p = 2, SDID tau = -12.404186180341236\n", - "p = 3, SDID tau = -18.732037530978\n", - "p = 4, SDID tau = -12.190802434113351\n", - "p = 5, SDID tau = -18.66043871411996\n", - "p = 6, SDID tau = -13.967810657779738\n", - "p = 7, SDID tau = -16.15254066972357\n", - "p = 8, SDID tau = -10.730949273166983\n", - "p = 9, SDID tau = -23.308037378142874\n", - "p = 10, SDID tau = -13.749051700441838\n", - "p = 11, SDID tau = -12.63275340733902\n", - "p = 12, SDID tau = -19.233563389051632\n", - "p = 13, SDID tau = -19.414339504862216\n", - "p = 14, SDID tau = -8.267961258006359\n", - "p = 15, SDID tau = -16.276998135272706\n", - "p = 16, SDID tau = -10.808111417832722\n", - "p = 17, SDID tau = -2.0520046242906074\n", - "p = 18, SDID tau = -15.887881115161814\n", - "p = 19, SDID tau = 2.851301706918961\n" - ] - }, - { - "data": { - "image/png": "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LITo136FhYWIjIxEZGSkYdu4cePg7+9veL17770Xp0+fNqQ7bNy4EZMnTza8PwBYs2YNkpKSEBwcDG9vb/z973/HmTNnjF4rISEBKpWq1/bs2LEDN910E4YNGwYfHx888MADqKmpQUtLS4/HHDlyBFqtFrGxsUb9v3v3bkPf/+EPf8D//u//YtasWUhPT8fhw4d7bUdrayvc3d27bHdxccE111xjeDxmzBijvpJ5eHj02mYisj0GukRkd66//nokJyfjhRde6PKcQqHoEuBpNJou+7m6uho9liSp2206na7f7WpqakJqaioOHjxo9O/EiRO4/vrrDft1l0ZgCaNHj+42t9YUoaGhmDNnDj777DMAwGeffYZFixYZnv/iiy/wzDPPYOnSpdi+fTsOHjyIhx9+uMtku77e++nTp3HrrbdiwoQJ+Oabb7B//36sWbMGQO8T95qamqBUKrF//36jvi8sLDTkCv/+979HcXExHnjgARw5cgRTpkzB6tWrezxnUFDQVU18rK2tRXBwsMnHE5HlMdAlIru0cuVKbN26FVlZWUbbg4ODUVFRYRTsmrP27eUTuDo6OrB//36MHTsWADB58mQcPXoUI0aMwKhRo4z+DSS49fX1RXh4OPbu3Wu0fe/evRg3bly/zxMYGIjk5GSsWbMGzc3NXZ6vq6sDAIwdOxZnz541mlBVUFCAuro6o9dbtGgRvvzyS2RlZaG4uNgoL3Xv3r2YOXMmnnjiCUyaNAmjRo0yGsXur/3790On0+Gvf/0rpk+fjtjYWJSVlRnto1KpoNVqjbZNmjQJWq0WVVVVXfo+NDTUsF9kZCQef/xxfPvtt1ixYgU++uijHtsyadIkFBQUdNne0dGB3377zfC4qKgIdXV1husA0I/gt7W1YdKkSQPuAyKyHga6RGSXEhISsGjRoi4lnG688UZcuHABb7zxBk6dOoU1a9bgX//6l9led82aNdi0aROOHTuGtLQ0XLx4EUuWLAGgn+xUW1uL++67D/v27cOpU6ewbds2PPzww10Cs748++yzWLVqFb788ksUFRXh+eefx8GDB/HHP/5xwO3VarWYOnUqvvnmG5w4cQKFhYV4//33DWkYc+fONfRnXl4ecnNz8eCDD+KGG24wmox1xx13oLGxEcuWLcPs2bMRHh5ueG706NH47bffsG3bNhw/fhwvvvgi9u3bN6C2AsCoUaOg0WiwevVqFBcX45///GeXCXsjRoxAU1MTdu7cierqarS0tCA2NhaLFi3Cgw8+iG+//RYlJSXIzc3F66+/jh9++AEAsHz5cmzbtg0lJSXIy8vDzz//bBScXik5ORlZWVld/t+5urriqaeeQk5ODvbv34/Fixdj+vTpmDp1qmGfPXv2ICYmxlCVgojsEwNdIrJbr776apfUgrFjx+Jvf/sb1qxZg8TEROTm5nZbkcBUK1euxMqVK5GYmIhff/0VW7ZsQVBQEAAYRmG1Wi3mzZuHhIQELF++HP7+/kb5wP3xhz/8AU8//TRWrFiBhIQEZGRkYMuWLRg9evSAzhMTE4O8vDzMnj0bK1aswPjx43HzzTdj586dWLt2LQB9isZ3332HgIAAXH/99Zg7dy5iYmLw5ZdfGp3Lx8cHqampOHTokFHaAgA89thjuOOOO3DPPfdg2rRpqKmpwRNPPDGgtgJAYmIi3n77baxatQrjx4/Hxo0bu5STmzlzJh5//HHcc889CA4OxhtvvAEAWLduHR588EGsWLECcXFxWLhwIfbt24fhw4cD0JdAS0tLw9ixY5GSkoLY2Fj87W9/67Et8+fPh4uLC3bs2GG03dPTE8899xzuv/9+zJo1C97e3l366vPPP8cjjzwy4PdPRNYlif7OZiAiInIya9aswZYtW7Bt2zYA+jq6y5cvN6R9dOfo0aOYM2cOjh8/Dj8/Pyu1lIhM4WLrBhAREdnKY489hrq6OjQ2NvZ7GeDy8nJ8+umnDHKJHAADXSIiGrRcXFzwpz/9aUDHzJ0710KtISJzY+oCERERETklTkYjIiIiIqfEQJeIiIiInBIDXSIiIiJySgx0iYiIiMgpMdAlIiIiIqfEQJeIiIiInBIDXSIiIiJySgx0iYiIiMgp/X8bdzgFryf0gAAAAABJRU5ErkJggg==", - "text/plain": [ - "
" - ] - }, - "metadata": {}, - "output_type": "display_data" - } - ], - "source": [ - "# Here we generate synthetic time-varying exogenous covariates X_cov.\n", - "# We want X_cov to have shape (n, T, p), where:\n", - "# n: number of units (rows in O)\n", - "# T: number of time periods (columns in O)\n", - "# p: number of covariates (here we try various p to see 'stability')\n", - "np.random.seed(0)\n", - "\n", - "p_values = range(1, 20)\n", - "tau_estimates = []\n", - "\n", - "n, T = O.shape\n", - "\n", - "tau_no_cov = SDID(O, Z)\n", - "\n", - "for p in p_values:\n", - " X_cov = np.random.randn(n, T, p)\n", - " tau = SDID(O, Z, X_cov=X_cov)\n", - " tau_estimates.append(tau)\n", - " print(f\"p = {p}, SDID tau = {tau}\")\n", - "\n", - "plt.figure(figsize=(8, 5))\n", - "plt.plot(p_values, tau_estimates, marker='o', label='SDID tau with fake covariates')\n", - "plt.axhline(tau_no_cov, color='red', linestyle='--', label='SDID tau without covariates')\n", - "plt.xlabel(\"Number of Covariates (p)\")\n", - "plt.ylabel(\"SDID Estimate (tau)\")\n", - "plt.title(\"SDID Estimates with Different Numbers of Covariates\")\n", - "plt.legend()\n", - "plt.grid(True)\n", - "plt.show()" - ] - }, + "name": "stdout", + "output_type": "stream", + "text": [ + "The estimation of SDID is -15.61431090150178\n" + ] + } + ], + "source": [ + "from causaltensor.cauest import SDID\n", + "\n", + "## to use SDID, cvxopt package is needed\n", + "\n", + "tau = SDID(O, Z)\n", + "print('The estimation of SDID is', tau) ## The result matched the result in [2]" + ] + }, + { + "cell_type": "code", + "execution_count": 12, + "metadata": {}, + "outputs": [ { - "cell_type": "markdown", - "metadata": { - "id": "e748YgFHW3Vh" - }, - "source": [ - "## Matrix Completion\n", - "\n", - "The third method is based on matrix completion method proposed by [4]. The idea is to solve the following matrix completion problem, only using the outcome data without intervention (i.e., $Z_{ij}=0$)\n", - "$$\n", - "\\hat{M}, \\hat{a}, \\hat{b} = \\arg\\min \\sum_{ij, Z_{ij}=0} (O_{ij}-M_{ij} - a_i - b_j)^2 + \\lambda \\|M\\|_{*}\n", - "$$\n", - "where $\\|M\\|_{*}$ is the nuclear norm that penalizes the low-rankness of the matrix (here $a_{i}$ and $b_{j}$ are used to improve the empirical performance, as suggested by [4]).\n", - "\n", - "After $\\hat{M}, \\hat{a}, \\hat{b}$ are obtained, the ATT $\\hat{\\tau}$ can be estimated simply by\n", - "$$\n", - "\\hat{\\tau} = \\frac{\\sum_{ij, Z_{ij}=1} (O_{ij} - \\hat{M}_{ij} - \\hat{a}_i - \\hat{b}_{j})}{\\sum_{ij, Z_{ij}=1} 1}.\n", - "$$\n", - "\n", - "To use this method (referred to as matrix completion with nuclear norm minimization, or MC-NNM), when you have an estimation of the rank of the matrix $M$ (e.g., by checking the spectrum), call\n", - "```\n", - "M, a, b, tau = MC_NNM_with_suggested_rank(O, 1-Z, suggest_r = r)\n", - "```\n", - "where `M`, `a`, `b` are the optimizers and `tau` is the estimated ATT.\n", - "\n", - "We also provide a function to help you find the right parameter $\\lambda$ or rank by cross-validation:\n", - "```\n", - "M, a, b, tau = MC_NNM_with_cross_validation(O, 1-Z)\n", - "```\n", - "\n", - "\n", - "[4] Athey, Susan, Mohsen Bayati, Nikolay Doudchenko, Guido Imbens, and Khashayar Khosravi. \"Matrix completion methods for causal panel data models.\" Journal of the American Statistical Association 116, no. 536 (2021): 1716-1730." - ] + "name": "stdout", + "output_type": "stream", + "text": [ + "p = 1, SDID tau = -16.539671285922704\n", + "p = 2, SDID tau = -12.402794465067027\n", + "p = 3, SDID tau = -18.730933502033807\n", + "p = 4, SDID tau = -12.19259129934589\n", + "p = 5, SDID tau = -18.659521007643455\n", + "p = 6, SDID tau = -13.96672610975754\n", + "p = 7, SDID tau = -16.15125042007348\n", + "p = 8, SDID tau = -10.73480065388118\n", + "p = 9, SDID tau = -23.312094394723342\n", + "p = 10, SDID tau = -13.748113451308004\n", + "p = 11, SDID tau = -12.636696492107852\n", + "p = 12, SDID tau = -19.236770262379945\n", + "p = 13, SDID tau = -19.413859360829665\n", + "p = 14, SDID tau = -8.270521827469773\n", + "p = 15, SDID tau = -16.276325476709246\n", + "p = 16, SDID tau = -10.806997302864314\n", + "p = 17, SDID tau = -2.056041270362535\n", + "p = 18, SDID tau = -15.886851581450706\n", + "p = 19, SDID tau = 2.852840617999361\n" + ] }, { - "cell_type": "code", - "execution_count": 13, - "metadata": { - "colab": { - "base_uri": "https://localhost:8080/" - }, - "id": "ziuVG2CVW3Vh", - "outputId": "77485282-d36e-4fe8-cba8-f06e6b868aa6" - }, - "outputs": [ - { - "data": { - "text/plain": [ - "-22.345401569119492" - ] - }, - "execution_count": 13, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "from causaltensor.cauest import MC_NNM_with_suggested_rank\n", - "\n", - "M, a, b, tau = MC_NNM_with_suggested_rank(O, 1-Z, suggest_r = 1)\n", - "tau" + "data": { + "image/png": "iVBORw0KGgoAAAANSUhEUgAAAroAAAHWCAYAAACYIyqlAAAAOnRFWHRTb2Z0d2FyZQBNYXRwbG90bGliIHZlcnNpb24zLjEwLjgsIGh0dHBzOi8vbWF0cGxvdGxpYi5vcmcvwVt1zgAAAAlwSFlzAAAPYQAAD2EBqD+naQAAr9RJREFUeJztnQd4FOX2xk96CKQAAUINvfcOikhHLNjb34p6FXsXrwXRa72Wa7t2UfTaFWwgRUA6SO+9BhISAumkz/95v80sm81usrvZNrvv73k2m52dnZ35puw75zvfe0I0TdOEEEIIIYSQACPU1ytACCGEEEKIJ6DQJYQQQgghAQmFLiGEEEIICUgodAkhhBBCSEBCoUsIIYQQQgISCl1CCCGEEBKQUOgSQgghhJCAhEKXEEIIIYQEJBS6hBBCCCEkIKHQJcQP+eyzzyQkJEQOHjzo61UxBGirZ555xuF57777bvEWixcvVt+JZ0u++OIL6dy5s0REREhCQoJ5+r///W9p27athIWFSe/evb22nsEMjh3soxMnTkigYO/4CvbznwQfFLrEZ2zZskUuv/xySU5OlujoaGnevLmMGTNG3n777UrztW7dWl3I8AgNDVUX7R49esg//vEPWb16tUNiBoJRXwYeuPgnJibK0KFD5Z///KccPnzY4fW2XI7144477nCqDV544QWZNWuW+BMrVqxQPxpZWVliVDy1De46jnbu3Ck33XSTtGvXTj766CP58MMP1fR58+bJo48+KmeddZZMnz5dHR+B0sbYXrRZz549xVbleW/fgAQy9o6v6ti4caNcd9110rJlS4mKipIGDRrI6NGj1XFYVlYmgcj27dvVMcyAQmAT7usVIMEJfiRHjBghrVq1kttuu02SkpLkyJEjsmrVKnnzzTflnnvuqTQ/IlsPPfSQ+j83N1d27Ngh33//vbqIP/DAA/L666879L3XXHONTJgwQcrLy+XUqVPy999/y3/+8x/1nZ988olcffXVDi0HgvyGG26oMr1jx47iDBAyEPsXX3xxpenXX3+9Whf84Phi30ybNk39UBolEnT69GkJDw/32jY4cxydc845av0iIyPN0xDdxWcxf/v27c3TFy5cqG7msAzL+f0RV9sYN7g//fSTXHbZZR5dv2DG3vFlj48//ljdpDdp0kRdezp06KCus3/++afccsstkpqaqm7kjHL+OyN0cQyfe+65KqBCAhMKXeITnn/+eYmPj1cCwfpHMj09vcr8iPYi2mDJyy+/LNdee6288cYb6sI8efLkGr+3b9++VZZz6NAhGTt2rNx4443SpUsX6dWrV43LgaC1Xo47Qbc1HsQx0CPgTZw5jiBcrddPP8ZtHft16tRxq8gtKCiQmJgY8QewbYgYPvvss3LppZeqKG4w4a19Ye/4sgWCCxC5Q4YMkdmzZ0tsbKz5vfvvv1/Wrl0rW7duFX8DQr64uFidW94+/4nB0AjxAZ06ddLOPfdch+ZNTk7Wzj//fJvv5ebmag0aNNCaN2+ulZeXm6fj0L7rrrvMrw8cOKCm/fvf/7a5nBUrVqj3r7322hrXx3rZ9ti9e7d26aWXak2aNNGioqLUOl511VVaVlaWeTnWjxtvvFG9N336dPUa623dDosWLdL69eunRUdHa927d1evwY8//qhe47v69u2rrV+/vtL6bNq0SS2/TZs2ah6s180336ydOHHCPM/UqVNtrpflenzxxRdq+fj++vXrq206fPiwU9tuizfffFMLDQ3VTp06ZZ726quvqu9/4IEHzNNKS0u1evXqaY8++milfYJ1d2Qb9P03c+ZMrVu3blpkZKTWtWtXbc6cOTXuU1eOI+wfTNP3E/aj9brZW2ccB860+/Dhw9U2rV27Vhs2bJhWp04d7b777lPvFRYWak8//bTWrl07tc0tWrTQHnnkETXdEkfax5HjxBoce3Xr1tVmzJih5sXxaut7dWydA7ba03K7cYyfc845aruxnd9//716f/HixdrAgQNV23Xs2FGbP39+pWXq27Njxw7tiiuu0GJjY9V15d5779VOnz5dZVtquy/+/vtvbezYsVrDhg3VMlq3bq3ORUd499131f7AfmnatKl25513Vjpn7B1f9hg/frwWHh6uHTp0yKHvz8vL0x588EF1/GAd0J44Hyyvv9huW9f3srIyrVmzZtpll11mnobPDhkyRLU32gLtqu83W8fHl19+qbYf64xjVH/PchsPHjyoTZ48Wa0blollX3755ZWOJf34sn5YHlezZ8/Wzj77bC0mJkZdcyZMmKBt3bq10nqlpqZqN910k7rGoT2SkpK0iy66qNpzgXgXRnSJT0Be7sqVK1WkoHv37i4vp169enLJJZeorl50Q3Xr1s2l5SCagXy2+fPnOzR/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", + "text/plain": [ + "
" ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "# Here we generate synthetic time-varying exogenous covariates X_cov.\n", + "# We want X_cov to have shape (n, T, p), where:\n", + "# n: number of units (rows in O)\n", + "# T: number of time periods (columns in O)\n", + "# p: number of covariates (here we try various p to see 'stability')\n", + "np.random.seed(0)\n", + "\n", + "p_values = range(1, 20)\n", + "tau_estimates = []\n", + "\n", + "n, T = O.shape\n", + "\n", + "tau_no_cov = SDID(O, Z)\n", + "\n", + "for p in p_values:\n", + " X_cov = np.random.randn(n, T, p)\n", + " tau = SDID(O, Z, X_cov=X_cov)\n", + " tau_estimates.append(tau)\n", + " print(f\"p = {p}, SDID tau = {tau}\")\n", + "\n", + "plt.figure(figsize=(8, 5))\n", + "plt.plot(p_values, tau_estimates, marker='o', label='SDID tau with fake covariates')\n", + "plt.axhline(tau_no_cov, color='red', linestyle='--', label='SDID tau without covariates')\n", + "plt.xlabel(\"Number of Covariates (p)\")\n", + "plt.ylabel(\"SDID Estimate (tau)\")\n", + "plt.title(\"SDID Estimates with Different Numbers of Covariates\")\n", + "plt.legend()\n", + "plt.grid(True)\n", + "plt.show()" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "id": "e748YgFHW3Vh" + }, + "source": [ + "## Matrix Completion\n", + "\n", + "The third method is based on matrix completion method proposed by [4]. The idea is to solve the following matrix completion problem, only using the outcome data without intervention (i.e., $Z_{ij}=0$)\n", + "$$\n", + "\\hat{M}, \\hat{a}, \\hat{b} = \\arg\\min \\sum_{ij, Z_{ij}=0} (O_{ij}-M_{ij} - a_i - b_j)^2 + \\lambda \\|M\\|_{*}\n", + "$$\n", + "where $\\|M\\|_{*}$ is the nuclear norm that penalizes the low-rankness of the matrix (here $a_{i}$ and $b_{j}$ are used to improve the empirical performance, as suggested by [4]).\n", + "\n", + "After $\\hat{M}, \\hat{a}, \\hat{b}$ are obtained, the ATT $\\hat{\\tau}$ can be estimated simply by\n", + "$$\n", + "\\hat{\\tau} = \\frac{\\sum_{ij, Z_{ij}=1} (O_{ij} - \\hat{M}_{ij} - \\hat{a}_i - \\hat{b}_{j})}{\\sum_{ij, Z_{ij}=1} 1}.\n", + "$$\n", + "\n", + "The recommended MC-NNM API is now `MCNNMPanelSolver.fit`. It chooses the solving method from the arguments you pass:\n", + "\n", + "```python\n", + "solver = MCNNMPanelSolver(Z=Z)\n", + "result = solver.fit(O=O, suggest_r=r) # suggested rank\n", + "result = solver.fit(O=O, l=2.0) # fixed nuclear-norm regularizer\n", + "result = solver.fit(O=O, K=5, list_l=None) # cross-validation over regularizers\n", + "```\n", + "\n", + "The old functional API is still available for backward compatibility:\n", + "\n", + "```python\n", + "M, a, b, tau = MC_NNM_with_suggested_rank(O, 1-Z, suggest_r=r)\n", + "M, a, b, tau = MC_NNM_with_cross_validation(O, 1-Z)\n", + "```\n", + "\n", + "[4] Athey, Susan, Mohsen Bayati, Nikolay Doudchenko, Guido Imbens, and Khashayar Khosravi. \"Matrix completion methods for causal panel data models.\" Journal of the American Statistical Association 116, no. 536 (2021): 1716-1730.\n" + ] + }, + { + "cell_type": "code", + "execution_count": 13, + "metadata": { + "colab": { + "base_uri": "https://localhost:8080/" }, + "id": "ziuVG2CVW3Vh", + "outputId": "77485282-d36e-4fe8-cba8-f06e6b868aa6" + }, + "outputs": [ { - "cell_type": "code", - "execution_count": 14, - "metadata": { - "colab": { - "base_uri": "https://localhost:8080/" - }, - "id": "kQ6UUC-EW3Vh", - "outputId": "0afd0f3e-8142-4be5-82c1-7dc61390e632" - }, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "The estimation of MC_NNM is -20.267535327741044\n" - ] - } - ], - "source": [ - "from causaltensor.cauest import MC_NNM_with_cross_validation\n", - "\n", - "M, a, b, tau = MC_NNM_with_cross_validation(O, 1-Z)\n", - "print('The estimation of MC_NNM is', tau)" + "data": { + "text/plain": [ + "-22.34540156911949" ] + }, + "execution_count": 13, + "metadata": {}, + "output_type": "execute_result" } - ], - "metadata": { + ], + "source": [ + "from causaltensor.cauest import MCNNMPanelSolver\n", + "\n", + "solver = MCNNMPanelSolver(Z=Z)\n", + "result = solver.fit(O=O, suggest_r=1)\n", + "M, a, b, tau = result.M, result.row_fixed_effects, result.column_fixed_effects, result.tau\n", + "\n", + "# Old API equivalent:\n", + "# from causaltensor.cauest import MC_NNM_with_suggested_rank\n", + "# M, a, b, tau = MC_NNM_with_suggested_rank(O, 1-Z, suggest_r=1)\n", + "\n", + "tau\n" + ] + }, + { + "cell_type": "code", + "execution_count": 14, + "metadata": { "colab": { - "provenance": [] + "base_uri": "https://localhost:8080/" }, - "kernelspec": { - "display_name": ".venv", - "language": "python", - "name": "python3" - }, - "language_info": { - "codemirror_mode": { - "name": "ipython", - "version": 3 - }, - "file_extension": ".py", - "mimetype": "text/x-python", - "name": "python", - "nbconvert_exporter": "python", - "pygments_lexer": "ipython3", - "version": "3.11.5" - }, - "orig_nbformat": 4 + "id": "kQ6UUC-EW3Vh", + "outputId": "0afd0f3e-8142-4be5-82c1-7dc61390e632" + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "The estimation of MC_NNM is -20.267535327741044\n" + ] + } + ], + "source": [ + "result = solver.fit(O=O, K=5)\n", + "M, a, b, tau = result.M, result.row_fixed_effects, result.column_fixed_effects, result.tau\n", + "\n", + "# Old API equivalent:\n", + "# from causaltensor.cauest import MC_NNM_with_cross_validation\n", + "# M, a, b, tau = MC_NNM_with_cross_validation(O, 1-Z, K=5)\n", + "\n", + "print('The estimation of MC_NNM is', tau)\n" + ] + } + ], + "metadata": { + "colab": { + "provenance": [] + }, + "kernelspec": { + "display_name": ".venv", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.13.5" }, - "nbformat": 4, - "nbformat_minor": 0 + "orig_nbformat": 4 + }, + "nbformat": 4, + "nbformat_minor": 0 } diff --git a/tutorials/Panel_Data_Example.ipynb b/tutorials/Panel_Data_Example.ipynb index f891bdf..d3a4001 100644 --- a/tutorials/Panel_Data_Example.ipynb +++ b/tutorials/Panel_Data_Example.ipynb @@ -1,679 +1,679 @@ { - "cells": [ - { - "cell_type": "markdown", - "metadata": { - "id": "hX0p5BzC9-vK" - }, - "source": [ - "# Panel Data Example\n", - "\n", - "In this example, we will use [California Smoke Data](https://www.tandfonline.com/doi/abs/10.1198/jasa.2009.ap08746) [1] to show the usage of [CausalTensor](https://github.com/TianyiPeng/causaltensor) package.\n", - "\n", - "[1] Abadie, Alberto, Alexis Diamond, and Jens Hainmueller. \"Synthetic control methods for comparative case studies: Estimating the effect of California’s tobacco control program.\" Journal of the American statistical Association 105, no. 490 (2010): 493-505." - ] - }, - { - "cell_type": "code", - "execution_count": 16, - "metadata": { - "id": "ecYezNjLW3VZ" - }, - "outputs": [], - "source": [ - "import numpy as np" - ] - }, - { - "cell_type": "markdown", - "metadata": { - "id": "gAmMRnIV9uDq" - }, - "source": [ - "Install and import `causaltensor` package" - ] - }, - { - "cell_type": "code", - "execution_count": 18, - "metadata": { - "colab": { - "base_uri": "https://localhost:8080/" - }, - "id": "yoqZkdZJ3tAR", - "outputId": "8268464c-71bb-4664-ef6a-d42f9686cf6e" - }, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Collecting causaltensor\n", - " Obtaining dependency information for causaltensor from https://files.pythonhosted.org/packages/19/53/178b36b775141dce511d6c972037c10dd1c36f08dd81da4b3bbf15b2b5d1/causaltensor-0.1.12-py3-none-any.whl.metadata\n", - " Using cached causaltensor-0.1.12-py3-none-any.whl.metadata (5.1 kB)\n", - "Requirement already satisfied: cvxopt<2.0,>=1.2 in /Users/tianyipeng/anaconda3/lib/python3.11/site-packages (from causaltensor) (1.3.2)\n", - "Requirement already satisfied: cvxpy<2.0.0,>=1.4.3 in /Users/tianyipeng/anaconda3/lib/python3.11/site-packages (from causaltensor) (1.6.3)\n", - "Requirement already satisfied: matplotlib<4.0.0,>=3.8.0 in /Users/tianyipeng/anaconda3/lib/python3.11/site-packages (from causaltensor) (3.10.1)\n", - "Requirement already satisfied: numpy<2.0,>=1.18 in /Users/tianyipeng/anaconda3/lib/python3.11/site-packages (from causaltensor) (1.24.3)\n", - "Requirement already satisfied: pandas<3.0.0,>=2.1.0 in /Users/tianyipeng/anaconda3/lib/python3.11/site-packages (from causaltensor) (2.2.3)\n", - "Requirement already satisfied: toolz<0.13.0,>=0.12.1 in /Users/tianyipeng/anaconda3/lib/python3.11/site-packages (from causaltensor) (0.12.1)\n", - "Requirement already satisfied: tqdm<5.0.0,>=4.67.1 in /Users/tianyipeng/anaconda3/lib/python3.11/site-packages (from causaltensor) (4.67.1)\n", - "Requirement already satisfied: osqp>=0.6.2 in /Users/tianyipeng/anaconda3/lib/python3.11/site-packages (from cvxpy<2.0.0,>=1.4.3->causaltensor) (0.6.7.post3)\n", - "Requirement already satisfied: clarabel>=0.5.0 in /Users/tianyipeng/anaconda3/lib/python3.11/site-packages (from cvxpy<2.0.0,>=1.4.3->causaltensor) (0.10.0)\n", - "Requirement already satisfied: scs>=3.2.4.post1 in /Users/tianyipeng/anaconda3/lib/python3.11/site-packages (from cvxpy<2.0.0,>=1.4.3->causaltensor) (3.2.7.post2)\n", - "Requirement already satisfied: scipy>=1.11.0 in /Users/tianyipeng/anaconda3/lib/python3.11/site-packages (from cvxpy<2.0.0,>=1.4.3->causaltensor) (1.11.1)\n", - "Requirement already satisfied: contourpy>=1.0.1 in /Users/tianyipeng/anaconda3/lib/python3.11/site-packages (from matplotlib<4.0.0,>=3.8.0->causaltensor) (1.0.5)\n", - "Requirement already satisfied: cycler>=0.10 in /Users/tianyipeng/anaconda3/lib/python3.11/site-packages (from matplotlib<4.0.0,>=3.8.0->causaltensor) (0.11.0)\n", - "Requirement already satisfied: fonttools>=4.22.0 in /Users/tianyipeng/anaconda3/lib/python3.11/site-packages (from matplotlib<4.0.0,>=3.8.0->causaltensor) (4.25.0)\n", - "Requirement already satisfied: kiwisolver>=1.3.1 in /Users/tianyipeng/anaconda3/lib/python3.11/site-packages (from matplotlib<4.0.0,>=3.8.0->causaltensor) (1.4.4)\n", - "Requirement already satisfied: packaging>=20.0 in /Users/tianyipeng/anaconda3/lib/python3.11/site-packages (from matplotlib<4.0.0,>=3.8.0->causaltensor) (24.2)\n", - "Requirement already satisfied: pillow>=8 in /Users/tianyipeng/anaconda3/lib/python3.11/site-packages (from matplotlib<4.0.0,>=3.8.0->causaltensor) (9.4.0)\n", - "Requirement already satisfied: pyparsing>=2.3.1 in /Users/tianyipeng/anaconda3/lib/python3.11/site-packages (from matplotlib<4.0.0,>=3.8.0->causaltensor) (3.0.9)\n", - "Requirement already satisfied: python-dateutil>=2.7 in /Users/tianyipeng/anaconda3/lib/python3.11/site-packages (from matplotlib<4.0.0,>=3.8.0->causaltensor) (2.8.2)\n", - "Requirement already satisfied: pytz>=2020.1 in /Users/tianyipeng/anaconda3/lib/python3.11/site-packages (from pandas<3.0.0,>=2.1.0->causaltensor) (2023.3.post1)\n", - "Requirement already satisfied: tzdata>=2022.7 in /Users/tianyipeng/anaconda3/lib/python3.11/site-packages (from pandas<3.0.0,>=2.1.0->causaltensor) (2023.3)\n", - "Requirement already satisfied: qdldl in /Users/tianyipeng/anaconda3/lib/python3.11/site-packages (from osqp>=0.6.2->cvxpy<2.0.0,>=1.4.3->causaltensor) (0.1.7.post5)\n", - "Requirement already satisfied: six>=1.5 in /Users/tianyipeng/anaconda3/lib/python3.11/site-packages (from python-dateutil>=2.7->matplotlib<4.0.0,>=3.8.0->causaltensor) (1.16.0)\n", - "Using cached causaltensor-0.1.12-py3-none-any.whl (41 kB)\n", - "Installing collected packages: causaltensor\n", - "Successfully installed causaltensor-0.1.12\n", - "\u001b[33mWARNING: There was an error checking the latest version of pip.\u001b[0m\u001b[33m\n", - "\u001b[0m" - ] - } - ], - "source": [ - "!pip install causaltensor #install the causaltensor package\n", - "import causaltensor as ct" - ] - }, - { - "cell_type": "markdown", - "metadata": { - "id": "Eea_IhaL94-s" - }, - "source": [ - "## Load Data\n", - "\n", - "*California Smoke Data* consists of annual tobacco consumption (smoking consumption in packs per capita) of 39 states from 1970 to 2000.\n", - "\n", - "Among those states, California (the treated state) started a state-level tobacco control program in 1989; while other states largely serve as control states. The problem at hand is to evaluate the impact of this program to the tobacco consumption in California given the data.\n", - "\n", - "Let's first download the data." - ] - }, - { - "cell_type": "code", - "execution_count": 19, - "metadata": { - "colab": { - "base_uri": "https://localhost:8080/" - }, - "id": "76t1BOKU8Cqv", - "outputId": "d6c0d4ba-9acb-4d3c-91eb-a6b22836f788" - }, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - " % Total % Received % Xferd Average Speed Time Time Time Current\n", - " Dload Upload Total Spent Left Speed\n", - " 0 0 0 0 0 0 0 0 --:--:-- --:--:-- --:--:-- 0\n", - "100 6868 100 6868 0 0 85843 0 --:--:-- --:--:-- --:--:-- 85843\n", - "Archive: Synth.zip\n", - " inflating: synth_code.m \n", - " inflating: readme_synth_matlab.txt \n", - " inflating: MLAB_data.txt \n", - " inflating: loss_function.m \n" - ] - } - ], - "source": [ - "!curl https://github.com/TianyiPeng/causaltensor/raw/main/tutorials/Synth.zip -L -o Synth.zip\n", - "!unzip -o Synth.zip" - ] - }, - { - "cell_type": "markdown", - "metadata": { - "id": "WowuKbHEBqoX" - }, - "source": [ - "Load and pre-process the outcome data" - ] - }, - { - "cell_type": "code", - "execution_count": 20, - "metadata": { - "colab": { - "base_uri": "https://localhost:8080/" - }, - "id": "QMDAQqZuW3Vc", - "outputId": "fa5a4bfb-52f7-4bc1-a716-84f5ea2f7ac5" - }, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "(39, 31)\n" - ] - } - ], - "source": [ - "O_raw = np.loadtxt('MLAB_data.txt')\n", - "O = O_raw[8:, :] ## remove features that are not relevant in this demo\n", - "O = O.T\n", - "print(O.shape)\n", - "## now O consists of the annual tobacco consumption of 39 states from 1970 to 2000\n", - "## California is the last row of O" - ] - }, - { - "cell_type": "markdown", - "metadata": { - "id": "7kGd_eePCxcA" - }, - "source": [ - "Let's take a look for the California data" - ] - }, - { - "cell_type": "code", - "execution_count": 21, - "metadata": { - "colab": { - "base_uri": "https://localhost:8080/", - "height": 448 - }, - "id": "5kWHT611W3Vc", - "outputId": "60daa228-f6f8-4ede-fe93-cfa4728a36e2" - }, - "outputs": [ - { - "data": { - "text/plain": [ - "[]" - ] - }, - "execution_count": 21, - "metadata": {}, - "output_type": "execute_result" - }, - { - "data": { - "image/png": "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", - "text/plain": [ - "
" - ] - }, - "metadata": {}, - "output_type": "display_data" - } - ], - "source": [ - "import matplotlib.pyplot as plt\n", - "\n", - "plt.plot(O[-1, :])" - ] - }, - { - "cell_type": "markdown", - "metadata": { - "id": "qx0HCNW5DHBh" - }, - "source": [ - "Prepare intervention matrix $Z$ that indicates whether the intervention is implemented or not" - ] - }, - { - "cell_type": "code", - "execution_count": 22, - "metadata": { - "id": "OKOaSdNDW3Vd" - }, - "outputs": [], - "source": [ - "Z = np.zeros_like(O) # Z has the same shape as O\n", - "Z[-1, 19:] = 1 #Only California (the last row) used the intervention, which started in 1989" - ] - }, - { - "cell_type": "markdown", - "metadata": { - "id": "nrbswjpjEPEa" - }, - "source": [ - "## Estimators\n", - "\n", - "Now after we have the outcome data ($O \\in R^{n\\times T}$) and the intervention data ($Z \\in R^{n\\times T}$), let's show a few methods that can be used directly to assess the impact of the intervention." - ] - }, - { - "cell_type": "markdown", - "metadata": { - "id": "NHJX5Sd6W3Ve" - }, - "source": [ - "## DID estimation\n", - "\n", - "The first method is difference-in-difference (DID). We use a two-way fixed effects regression to estimate the average treatment effect on the treated entries (ATT). In particular, we solve the following regression by linear regression\n", - "$$\n", - "\\min \\sum_{ij} (O_{ij} - a_i - b_j - \\tau Z_{ij})^2\n", - "$$\n", - "where $a_{i}, b_{j}$ are unknown fixed effects and $\\tau$ is the ATT.\n", - "\n", - "To use DID, simply call\n", - "```\n", - "solver = DIDPanelSolver(Z=Z)\n", - "result = solver.fit(O=O)\n", - "M, tau = result.M, result.tau\n", - "````\n", - "with two return parameters `M` and `tau`. Here $M_{ij}=a_{i}+b_{j}$ is the estimated ideal outcomes; and `tau` is the estimated ATT." - ] - }, - { - "cell_type": "code", - "execution_count": 23, - "metadata": { - "colab": { - "base_uri": "https://localhost:8080/" - }, - "id": "cDDMODb7W3Vf", - "outputId": "360c047d-8c5c-423d-95a0-cf12f35fdfca" - }, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "The estimation of DID is -27.349111083614964\n" - ] - } - ], - "source": [ - "from causaltensor.cauest.DID import DIDPanelSolver\n", - "\n", - "solver = DIDPanelSolver(Z=Z)\n", - "result = solver.fit(O=O)\n", - "\n", - "M, tau = result.M, result.tau\n", - "print('The estimation of DID is', tau)" - ] + "cells": [ + { + "cell_type": "markdown", + "metadata": { + "id": "hX0p5BzC9-vK" + }, + "source": [ + "# Panel Data Example\n", + "\n", + "In this example, we will use [California Smoke Data](https://www.tandfonline.com/doi/abs/10.1198/jasa.2009.ap08746) [1] to show the usage of [CausalTensor](https://github.com/TianyiPeng/causaltensor) package.\n", + "\n", + "[1] Abadie, Alberto, Alexis Diamond, and Jens Hainmueller. \"Synthetic control methods for comparative case studies: Estimating the effect of California’s tobacco control program.\" Journal of the American statistical Association 105, no. 490 (2010): 493-505." + ] + }, + { + "cell_type": "code", + "execution_count": 1, + "metadata": { + "id": "ecYezNjLW3VZ" + }, + "outputs": [], + "source": [ + "import numpy as np\n" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "id": "gAmMRnIV9uDq" + }, + "source": [ + "Install and import `causaltensor` package" + ] + }, + { + "cell_type": "code", + "execution_count": 2, + "metadata": { + "colab": { + "base_uri": "https://localhost:8080/" }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "**Note that M is maintain for backward compatability, you can acces the baseline (M) as:**" - ] + "id": "yoqZkdZJ3tAR", + "outputId": "8268464c-71bb-4664-ef6a-d42f9686cf6e" + }, + "outputs": [], + "source": [ + "import numpy as np\n", + "from pathlib import Path\n", + "import subprocess\n", + "import sys\n", + "\n", + "\n", + "def find_project_root(start):\n", + " for candidate in (start, *start.parents):\n", + " if (candidate / \"src\" / \"causaltensor\" / \"cauest\" / \"MCNNM.py\").exists():\n", + " return candidate\n", + " return None\n", + "\n", + "\n", + "PROJECT_ROOT = find_project_root(Path.cwd().resolve())\n", + "if PROJECT_ROOT is not None:\n", + " sys.path.insert(0, str(PROJECT_ROOT / \"src\"))\n", + " for module_name in list(sys.modules):\n", + " if module_name == \"causaltensor\" or module_name.startswith(\"causaltensor.\"):\n", + " del sys.modules[module_name]\n", + " TUTORIALS_DIR = PROJECT_ROOT / \"tutorials\"\n", + "else:\n", + " subprocess.check_call([sys.executable, \"-m\", \"pip\", \"install\", \"causaltensor\"])\n", + " TUTORIALS_DIR = Path.cwd()\n", + "\n", + "import causaltensor as ct\n" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "id": "Eea_IhaL94-s" + }, + "source": [ + "## Load Data\n", + "\n", + "*California Smoke Data* consists of annual tobacco consumption (smoking consumption in packs per capita) of 39 states from 1970 to 2000.\n", + "\n", + "Among those states, California (the treated state) started a state-level tobacco control program in 1989; while other states largely serve as control states. The problem at hand is to evaluate the impact of this program to the tobacco consumption in California given the data.\n", + "\n", + "Let's first download the data." + ] + }, + { + "cell_type": "code", + "execution_count": 3, + "metadata": { + "colab": { + "base_uri": "https://localhost:8080/" }, + "id": "76t1BOKU8Cqv", + "outputId": "d6c0d4ba-9acb-4d3c-91eb-a6b22836f788" + }, + "outputs": [ { - "cell_type": "code", - "execution_count": 24, - "metadata": {}, - "outputs": [], - "source": [ - "M, tau = result.baseline, result.tau" - ] + "name": "stdout", + "output_type": "stream", + "text": [ + "Using tutorial data from /Users/federicomolina/Documents/github/causaltensor/tutorials\n" + ] + } + ], + "source": [ + "from pathlib import Path\n", + "import urllib.request\n", + "import zipfile\n", + "\n", + "DATA_DIR = TUTORIALS_DIR if (TUTORIALS_DIR / \"MLAB_data.txt\").exists() else Path.cwd()\n", + "\n", + "if not (DATA_DIR / \"MLAB_data.txt\").exists():\n", + " zip_path = Path.cwd() / \"Synth.zip\"\n", + " urllib.request.urlretrieve(\n", + " \"https://github.com/TianyiPeng/causaltensor/raw/main/tutorials/Synth.zip\",\n", + " zip_path,\n", + " )\n", + " with zipfile.ZipFile(zip_path) as archive:\n", + " archive.extractall(Path.cwd())\n", + " DATA_DIR = Path.cwd()\n", + "\n", + "print(f\"Using tutorial data from {DATA_DIR}\")\n" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "id": "WowuKbHEBqoX" + }, + "source": [ + "Load and pre-process the outcome data" + ] + }, + { + "cell_type": "code", + "execution_count": 4, + "metadata": { + "colab": { + "base_uri": "https://localhost:8080/" }, + "id": "QMDAQqZuW3Vc", + "outputId": "fa5a4bfb-52f7-4bc1-a716-84f5ea2f7ac5" + }, + "outputs": [ { - "cell_type": "markdown", - "metadata": { - "id": "wIyuxrU1W3Vi" - }, - "source": [ - "## Debiased Convex Panel Regression\n", - "\n", - "The second method is De-biaeed Convex Panel Regression (DC-PR) proposed by [2].\n", - "Note that an issue of the DID model is that, $a_i+b_j$ are often too simple to describe the complex reality of the outcome. As a fix, a low-rank factor model to generalize $a_i+b_j$ has been advocated.\n", - "\n", - "The idea in [2] is to firstly solve the following low-rank regression problem by replacing $a_i+b_j$ in DID by a low-rank matrix $M$\n", - "$$\n", - "\\hat{M}, \\hat{\\tau} = \\arg\\min \\sum_{ij} (O_{ij}-M_{ij}-\\tau Z_{ij})^2 + \\lambda \\|M\\|_{*}\n", - "$$\n", - "where $\\|M\\|_{*}$ is the nuclear norm to penalize the low-rankness of the matrix and $\\lambda$ is a tunning parameter. The second step of [2] is to mitigate the bias induced by the regularization parameter (it also reflects the interaction between $\\hat{M}$ and $Z$):\n", - "$$\n", - "\\tau^{d} = \\hat{\\tau} - \\lambda \\frac{}{\\|P_{\\hat{T}^{\\perp}}(Z)\\|_{F}^2}.\n", - "$$\n", - "See [2] for more details.\n", - "\n", - "To use DC-PR, call\n", - "```\n", - "solver = DCPanelSolver(Z=Z, O=O)\n", - "result = solver.fit()\n", - "M, tau, std = result.baseline, result.tau, result.std\n", - "```\n", - "where `M`, `tau` are the final estimators for the low-rank matrix and the treatment effects respectively. In addition `std` is the stanard deviation estimation for `tau`, using the formula in [2] for the scenarios when noises are (heterogenoues) independent sub-Gaussian. This function helps to find the proper rank for $M$ (but not very stable, and may be updated later). You can also use\n", - "```\n", - "result = solver.fit(suggest_r=2)\n", - "M, tau, std = result.baseline, result.tau, result.std\n", - "```\n", - "if you have an estimation of the rank of $M$ by yourself.\n", - "\n", - "[2] Farias, Vivek, Andrew Li, and Tianyi Peng. \"Learning treatment effects in panels with general intervention patterns.\" Advances in Neural Information Processing Systems 34 (2021): 14001-14013." - ] + "name": "stdout", + "output_type": "stream", + "text": [ + "(39, 31)\n" + ] + } + ], + "source": [ + "O_raw = np.loadtxt(DATA_DIR / \"MLAB_data.txt\")\n", + "O = O_raw[8:, :] ## remove features that are not relevant in this demo\n", + "O = O.T\n", + "print(O.shape)\n", + "## now O consists of the annual tobacco consumption of 39 states from 1970 to 2000\n", + "## California is the last row of O\n" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "id": "7kGd_eePCxcA" + }, + "source": [ + "Let's take a look for the California data" + ] + }, + { + "cell_type": "code", + "execution_count": 5, + "metadata": { + "colab": { + "base_uri": "https://localhost:8080/", + "height": 448 }, + "id": "5kWHT611W3Vc", + "outputId": "60daa228-f6f8-4ede-fe93-cfa4728a36e2" + }, + "outputs": [ { - "cell_type": "code", - "execution_count": 25, - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "The estimation of DC with auto rank is -15.880704119035332 3.011813924289439\n" - ] - } - ], - "source": [ - "from causaltensor.cauest.DebiasConvex import DCPanelSolver\n", - "\n", - "solver = DCPanelSolver(Z=Z, O=O)\n", - "result = solver.fit() # auto_rank=True by default\n", - "\n", - "# As before, remember that you can acces the base as result.M or result.baseline\n", - "M, tau, std = result.baseline, result.tau, result.std\n", - "print('The estimation of DC with auto rank is', tau, std)" + "data": { + "text/plain": [ + "[]" ] + }, + "execution_count": 5, + "metadata": {}, + "output_type": "execute_result" }, { - "cell_type": "markdown", - "metadata": { - "id": "3T1wQP1A3QG0" - }, - "source": [ - "We also implemented the panel regression with a hard rank constraint:\n", - "$$\n", - "\\hat{M}, \\hat{\\tau} = \\arg\\min_{rank(M)\\leq r} \\sum_{ij} (O_{ij}-M_{ij}-\\tau Z_{ij})^2\n", - "$$\n", - "This is a non-convex optimization problem and we used the alternate minimization between $M$ and $\\tau$ for the optimization. The theoretical guarantee for this non-convex method is weaker than the convex method above (the convergence to the global optimum is not always guaranteed), but the practical performance is comparable (sometimes even better). " + "data": { + "image/png": "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", + "text/plain": [ + "
" ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "import matplotlib.pyplot as plt\n", + "\n", + "plt.plot(O[-1, :])" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "id": "qx0HCNW5DHBh" + }, + "source": [ + "Prepare intervention matrix $Z$ that indicates whether the intervention is implemented or not" + ] + }, + { + "cell_type": "code", + "execution_count": 6, + "metadata": { + "id": "OKOaSdNDW3Vd" + }, + "outputs": [], + "source": [ + "Z = np.zeros_like(O) # Z has the same shape as O\n", + "Z[-1, 19:] = 1 #Only California (the last row) used the intervention, which started in 1989" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "id": "nrbswjpjEPEa" + }, + "source": [ + "## Estimators\n", + "\n", + "Now after we have the outcome data ($O \\in R^{n\\times T}$) and the intervention data ($Z \\in R^{n\\times T}$), let's show a few methods that can be used directly to assess the impact of the intervention." + ] + }, + { + "cell_type": "markdown", + "metadata": { + "id": "NHJX5Sd6W3Ve" + }, + "source": [ + "## DID estimation\n", + "\n", + "The first method is difference-in-difference (DID). We use a two-way fixed effects regression to estimate the average treatment effect on the treated entries (ATT). In particular, we solve the following regression by linear regression\n", + "$$\n", + "\\min \\sum_{ij} (O_{ij} - a_i - b_j - \\tau Z_{ij})^2\n", + "$$\n", + "where $a_{i}, b_{j}$ are unknown fixed effects and $\\tau$ is the ATT.\n", + "\n", + "To use DID, simply call\n", + "```\n", + "solver = DIDPanelSolver(Z=Z)\n", + "result = solver.fit(O=O)\n", + "M, tau = result.M, result.tau\n", + "````\n", + "with two return parameters `M` and `tau`. Here $M_{ij}=a_{i}+b_{j}$ is the estimated ideal outcomes; and `tau` is the estimated ATT." + ] + }, + { + "cell_type": "code", + "execution_count": 7, + "metadata": { + "colab": { + "base_uri": "https://localhost:8080/" }, + "id": "cDDMODb7W3Vf", + "outputId": "360c047d-8c5c-423d-95a0-cf12f35fdfca" + }, + "outputs": [ { - "cell_type": "code", - "execution_count": 26, - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "The estimation of DC with suggest rank and non-convex method is: -15.880704119035332 3.011813924289439\n" - ] - } - ], - "source": [ - "result = solver.fit(suggest_r=2, method='non-convex')\n", - "M, tau, std = result.baseline, result.tau, result.std\n", - "print('The estimation of DC with suggest rank and non-convex method is:', tau, std)" - ] - }, + "name": "stdout", + "output_type": "stream", + "text": [ + "The estimation of DID is -27.349111083614957\n" + ] + } + ], + "source": [ + "from causaltensor.cauest.DID import DIDPanelSolver\n", + "\n", + "solver = DIDPanelSolver(Z=Z)\n", + "result = solver.fit(O=O)\n", + "\n", + "M, tau = result.M, result.tau\n", + "print('The estimation of DID is', tau)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "**Note that M is maintain for backward compatability, you can acces the baseline (M) as:**" + ] + }, + { + "cell_type": "code", + "execution_count": 8, + "metadata": {}, + "outputs": [], + "source": [ + "M, tau = result.baseline, result.tau" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "id": "wIyuxrU1W3Vi" + }, + "source": [ + "## Debiased Convex Panel Regression\n", + "\n", + "The second method is De-biaeed Convex Panel Regression (DC-PR) proposed by [2].\n", + "Note that an issue of the DID model is that, $a_i+b_j$ are often too simple to describe the complex reality of the outcome. As a fix, a low-rank factor model to generalize $a_i+b_j$ has been advocated.\n", + "\n", + "The idea in [2] is to firstly solve the following low-rank regression problem by replacing $a_i+b_j$ in DID by a low-rank matrix $M$\n", + "$$\n", + "\\hat{M}, \\hat{\\tau} = \\arg\\min \\sum_{ij} (O_{ij}-M_{ij}-\\tau Z_{ij})^2 + \\lambda \\|M\\|_{*}\n", + "$$\n", + "where $\\|M\\|_{*}$ is the nuclear norm to penalize the low-rankness of the matrix and $\\lambda$ is a tunning parameter. The second step of [2] is to mitigate the bias induced by the regularization parameter (it also reflects the interaction between $\\hat{M}$ and $Z$):\n", + "$$\n", + "\\tau^{d} = \\hat{\\tau} - \\lambda \\frac{}{\\|P_{\\hat{T}^{\\perp}}(Z)\\|_{F}^2}.\n", + "$$\n", + "See [2] for more details.\n", + "\n", + "To use DC-PR, call\n", + "```\n", + "solver = DCPanelSolver(Z=Z, O=O)\n", + "result = solver.fit()\n", + "M, tau, std = result.baseline, result.tau, result.std\n", + "```\n", + "where `M`, `tau` are the final estimators for the low-rank matrix and the treatment effects respectively. In addition `std` is the stanard deviation estimation for `tau`, using the formula in [2] for the scenarios when noises are (heterogenoues) independent sub-Gaussian. This function helps to find the proper rank for $M$ (but not very stable, and may be updated later). You can also use\n", + "```\n", + "result = solver.fit(suggest_r=2)\n", + "M, tau, std = result.baseline, result.tau, result.std\n", + "```\n", + "if you have an estimation of the rank of $M$ by yourself.\n", + "\n", + "[2] Farias, Vivek, Andrew Li, and Tianyi Peng. \"Learning treatment effects in panels with general intervention patterns.\" Advances in Neural Information Processing Systems 34 (2021): 14001-14013." + ] + }, + { + "cell_type": "code", + "execution_count": 9, + "metadata": {}, + "outputs": [ { - "cell_type": "markdown", - "metadata": { - "id": "pyJDPbgr4w9B" - }, - "source": [ - "We also provide an option to select `convex` or `non-convex` panel regression in a data-driven fasion. This is recommended in practice." - ] - }, + "name": "stdout", + "output_type": "stream", + "text": [ + "The estimation of DC with auto rank is -15.880704119035295 3.0118139242894277\n" + ] + } + ], + "source": [ + "from causaltensor.cauest.DebiasConvex import DCPanelSolver\n", + "\n", + "solver = DCPanelSolver(Z=Z, O=O)\n", + "result = solver.fit() # auto_rank=True by default\n", + "\n", + "# As before, remember that you can acces the base as result.M or result.baseline\n", + "M, tau, std = result.baseline, result.tau, result.std\n", + "print('The estimation of DC with auto rank is', tau, std)" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "id": "3T1wQP1A3QG0" + }, + "source": [ + "We also implemented the panel regression with a hard rank constraint:\n", + "$$\n", + "\\hat{M}, \\hat{\\tau} = \\arg\\min_{rank(M)\\leq r} \\sum_{ij} (O_{ij}-M_{ij}-\\tau Z_{ij})^2\n", + "$$\n", + "This is a non-convex optimization problem and we used the alternate minimization between $M$ and $\\tau$ for the optimization. The theoretical guarantee for this non-convex method is weaker than the convex method above (the convergence to the global optimum is not always guaranteed), but the practical performance is comparable (sometimes even better). " + ] + }, + { + "cell_type": "code", + "execution_count": 10, + "metadata": {}, + "outputs": [ { - "cell_type": "code", - "execution_count": 27, - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "The estimation of DC with suggest rank and auto method is: -15.880704119035332 3.011813924289439\n" - ] - } - ], - "source": [ - "result = solver.fit(suggest_r=2, method='auto')\n", - "M, tau, std = result.baseline, result.tau, result.std\n", - "print('The estimation of DC with suggest rank and auto method is:', tau, std)" - ] - }, + "name": "stdout", + "output_type": "stream", + "text": [ + "The estimation of DC with suggest rank and non-convex method is: -15.880704119035295 3.0118139242894277\n" + ] + } + ], + "source": [ + "result = solver.fit(suggest_r=2, method='non-convex')\n", + "M, tau, std = result.baseline, result.tau, result.std\n", + "print('The estimation of DC with suggest rank and non-convex method is:', tau, std)" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "id": "pyJDPbgr4w9B" + }, + "source": [ + "We also provide an option to select `convex` or `non-convex` panel regression in a data-driven fasion. This is recommended in practice." + ] + }, + { + "cell_type": "code", + "execution_count": 11, + "metadata": {}, + "outputs": [ { - "cell_type": "markdown", - "metadata": { - "id": "5TE1lOIsW3Vg" - }, - "source": [ - "## SDID estimation\n", - "\n", - "The second method is called synthetic difference-in-difference (SDID) proposed by [3]. Readers can read [3] for more details. To use SDID, simply call\n", - "```\n", - "solver = SDIDPanelSolver(Z=Z, O=O)\n", - "result = solver.fit()\n", - "tau = result.tau\n", - "```\n", - "where `tau` is the estimation of SDID.\n", - "\n", - "[3] Arkhangelsky, Dmitry, Susan Athey, David A. Hirshberg, Guido W. Imbens, and Stefan Wager. \"Synthetic difference-in-differences.\" American Economic Review 111, no. 12 (2021): 4088-4118." - ] - }, + "name": "stdout", + "output_type": "stream", + "text": [ + "The estimation of DC with suggest rank and auto method is: -15.880704119035295 3.0118139242894277\n" + ] + } + ], + "source": [ + "result = solver.fit(suggest_r=2, method='auto')\n", + "M, tau, std = result.baseline, result.tau, result.std\n", + "print('The estimation of DC with suggest rank and auto method is:', tau, std)" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "id": "5TE1lOIsW3Vg" + }, + "source": [ + "## SDID estimation\n", + "\n", + "The second method is called synthetic difference-in-difference (SDID) proposed by [3]. Readers can read [3] for more details. To use SDID, simply call\n", + "```\n", + "solver = SDIDPanelSolver(Z=Z, O=O)\n", + "result = solver.fit()\n", + "tau = result.tau\n", + "```\n", + "where `tau` is the estimation of SDID.\n", + "\n", + "[3] Arkhangelsky, Dmitry, Susan Athey, David A. Hirshberg, Guido W. Imbens, and Stefan Wager. \"Synthetic difference-in-differences.\" American Economic Review 111, no. 12 (2021): 4088-4118." + ] + }, + { + "cell_type": "code", + "execution_count": 12, + "metadata": {}, + "outputs": [ { - "cell_type": "code", - "execution_count": 28, - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "The estimation of SDID is -15.602326126984675\n" - ] - } - ], - "source": [ - "from causaltensor.cauest.SDID import SDIDPanelSolver\n", - "\n", - "## to use SDID, cvxopt package is needed\n", - "\n", - "solver = SDIDPanelSolver(Z=Z, O=O)\n", - "result = solver.fit()\n", - "tau = result.tau\n", - "\n", - "print('The estimation of SDID is', tau) ## The result matched the result in [2]" - ] - }, + "name": "stdout", + "output_type": "stream", + "text": [ + "The estimation of SDID is -15.61431090150178\n" + ] + } + ], + "source": [ + "from causaltensor.cauest.SDID import SDIDPanelSolver\n", + "\n", + "## to use SDID, cvxopt package is needed\n", + "\n", + "solver = SDIDPanelSolver(Z=Z, O=O)\n", + "result = solver.fit()\n", + "tau = result.tau\n", + "\n", + "print('The estimation of SDID is', tau) ## The result matched the result in [2]" + ] + }, + { + "cell_type": "code", + "execution_count": 13, + "metadata": {}, + "outputs": [ { - "cell_type": "code", - "execution_count": 29, - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "p = 1, SDID tau = -16.54070037591654\n", - "p = 2, SDID tau = -12.404186180341236\n", - "p = 3, SDID tau = -18.732037530978\n", - "p = 4, SDID tau = -12.190802434113351\n", - "p = 5, SDID tau = -18.66043871411996\n", - "p = 6, SDID tau = -13.967810657779738\n", - "p = 7, SDID tau = -16.15254066972357\n", - "p = 8, SDID tau = -10.730949273166983\n", - "p = 9, SDID tau = -23.308037378142874\n", - "p = 10, SDID tau = -13.749051700441838\n", - "p = 11, SDID tau = -12.63275340733902\n", - "p = 12, SDID tau = -19.233563389051632\n", - "p = 13, SDID tau = -19.414339504862216\n", - "p = 14, SDID tau = -8.267961258006359\n", - "p = 15, SDID tau = -16.276998135272706\n", - "p = 16, SDID tau = -10.808111417832722\n", - "p = 17, SDID tau = -2.0520046242906074\n", - "p = 18, SDID tau = -15.887881115161814\n", - "p = 19, SDID tau = 2.851301706918961\n" - ] - }, - { - "data": { - "image/png": "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LITo136FhYWIjIxEZGSkYdu4cePg7+9veL17770Xp0+fNqQ7bNy4EZMnTza8PwBYs2YNkpKSEBwcDG9vb/z973/HmTNnjF4rISEBKpWq1/bs2LEDN910E4YNGwYfHx888MADqKmpQUtLS4/HHDlyBFqtFrGxsUb9v3v3bkPf/+EPf8D//u//YtasWUhPT8fhw4d7bUdrayvc3d27bHdxccE111xjeDxmzBijvpJ5eHj02mYisj0GukRkd66//nokJyfjhRde6PKcQqHoEuBpNJou+7m6uho9liSp2206na7f7WpqakJqaioOHjxo9O/EiRO4/vrrDft1l0ZgCaNHj+42t9YUoaGhmDNnDj777DMAwGeffYZFixYZnv/iiy/wzDPPYOnSpdi+fTsOHjyIhx9+uMtku77e++nTp3HrrbdiwoQJ+Oabb7B//36sWbMGQO8T95qamqBUKrF//36jvi8sLDTkCv/+979HcXExHnjgARw5cgRTpkzB6tWrezxnUFDQVU18rK2tRXBwsMnHE5HlMdAlIru0cuVKbN26FVlZWUbbg4ODUVFRYRTsmrP27eUTuDo6OrB//36MHTsWADB58mQcPXoUI0aMwKhRo4z+DSS49fX1RXh4OPbu3Wu0fe/evRg3bly/zxMYGIjk5GSsWbMGzc3NXZ6vq6sDAIwdOxZnz541mlBVUFCAuro6o9dbtGgRvvzyS2RlZaG4uNgoL3Xv3r2YOXMmnnjiCUyaNAmjRo0yGsXur/3790On0+Gvf/0rpk+fjtjYWJSVlRnto1KpoNVqjbZNmjQJWq0WVVVVXfo+NDTUsF9kZCQef/xxfPvtt1ixYgU++uijHtsyadIkFBQUdNne0dGB3377zfC4qKgIdXV1husA0I/gt7W1YdKkSQPuAyKyHga6RGSXEhISsGjRoi4lnG688UZcuHABb7zxBk6dOoU1a9bgX//6l9led82aNdi0aROOHTuGtLQ0XLx4EUuWLAGgn+xUW1uL++67D/v27cOpU6ewbds2PPzww10Cs748++yzWLVqFb788ksUFRXh+eefx8GDB/HHP/5xwO3VarWYOnUqvvnmG5w4cQKFhYV4//33DWkYc+fONfRnXl4ecnNz8eCDD+KGG24wmox1xx13oLGxEcuWLcPs2bMRHh5ueG706NH47bffsG3bNhw/fhwvvvgi9u3bN6C2AsCoUaOg0WiwevVqFBcX45///GeXCXsjRoxAU1MTdu7cierqarS0tCA2NhaLFi3Cgw8+iG+//RYlJSXIzc3F66+/jh9++AEAsHz5cmzbtg0lJSXIy8vDzz//bBScXik5ORlZWVld/t+5urriqaeeQk5ODvbv34/Fixdj+vTpmDp1qmGfPXv2ICYmxlCVgojsEwNdIrJbr776apfUgrFjx+Jvf/sb1qxZg8TEROTm5nZbkcBUK1euxMqVK5GYmIhff/0VW7ZsQVBQEAAYRmG1Wi3mzZuHhIQELF++HP7+/kb5wP3xhz/8AU8//TRWrFiBhIQEZGRkYMuWLRg9evSAzhMTE4O8vDzMnj0bK1aswPjx43HzzTdj586dWLt2LQB9isZ3332HgIAAXH/99Zg7dy5iYmLw5ZdfGp3Lx8cHqampOHTokFHaAgA89thjuOOOO3DPPfdg2rRpqKmpwRNPPDGgtgJAYmIi3n77baxatQrjx4/Hxo0bu5STmzlzJh5//HHcc889CA4OxhtvvAEAWLduHR588EGsWLECcXFxWLhwIfbt24fhw4cD0JdAS0tLw9ixY5GSkoLY2Fj87W9/67Et8+fPh4uLC3bs2GG03dPTE8899xzuv/9+zJo1C97e3l366vPPP8cjjzwy4PdPRNYlif7OZiAiInIya9aswZYtW7Bt2zYA+jq6y5cvN6R9dOfo0aOYM2cOjh8/Dj8/Pyu1lIhM4WLrBhAREdnKY489hrq6OjQ2NvZ7GeDy8nJ8+umnDHKJHAADXSIiGrRcXFzwpz/9aUDHzJ0710KtISJzY+oCERERETklTkYjIiIiIqfEQJeIiIiInBIDXSIiIiJySgx0iYiIiMgpMdAlIiIiIqfEQJeIiIiInBIDXSIiIiJySgx0iYiIiMgp/X8bdzgFryf0gAAAAABJRU5ErkJggg==", - "text/plain": [ - "
" - ] - }, - "metadata": {}, - "output_type": "display_data" - } - ], - "source": [ - "# Here we generate synthetic time-varying exogenous covariates X_cov.\n", - "# We want X_cov to have shape (n, T, p), where:\n", - "# n: number of units (rows in O)\n", - "# T: number of time periods (columns in O)\n", - "# p: number of covariates (here we try various p to see 'stability')\n", - "np.random.seed(0)\n", - "\n", - "p_values = range(1, 20)\n", - "tau_estimates = []\n", - "\n", - "n, T = O.shape\n", - "\n", - "solver = SDIDPanelSolver(Z=Z, O=O)\n", - "result = solver.fit()\n", - "tau_no_cov = result.tau\n", - "\n", - "for p in p_values:\n", - " X_cov = np.random.randn(n, T, p)\n", - "\n", - " solver = SDIDPanelSolver(Z=Z, O=O, X_cov=X_cov)\n", - " result = solver.fit()\n", - " tau = result.tau\n", - " tau_estimates.append(tau)\n", - " print(f\"p = {p}, SDID tau = {tau}\")\n", - "\n", - "plt.figure(figsize=(8, 5))\n", - "plt.plot(p_values, tau_estimates, marker='o', label='SDID tau with fake covariates')\n", - "plt.axhline(tau_no_cov, color='red', linestyle='--', label='SDID tau without covariates')\n", - "plt.xlabel(\"Number of Covariates (p)\")\n", - "plt.ylabel(\"SDID Estimate (tau)\")\n", - "plt.title(\"SDID Estimates with Different Numbers of Covariates\")\n", - "plt.legend()\n", - "plt.grid(True)\n", - "plt.show()" - ] + "name": "stdout", + "output_type": "stream", + "text": [ + "p = 1, SDID tau = -16.539671285922704\n", + "p = 2, SDID tau = -12.402794465067027\n", + "p = 3, SDID tau = -18.730933502033807\n", + "p = 4, SDID tau = -12.19259129934589\n", + "p = 5, SDID tau = -18.659521007643455\n", + "p = 6, SDID tau = -13.96672610975754\n", + "p = 7, SDID tau = -16.15125042007348\n", + "p = 8, SDID tau = -10.73480065388118\n", + "p = 9, SDID tau = -23.312094394723342\n", + "p = 10, SDID tau = -13.748113451308004\n", + "p = 11, SDID tau = -12.636696492107852\n", + "p = 12, SDID tau = -19.236770262379945\n", + "p = 13, SDID tau = -19.413859360829665\n", + "p = 14, SDID tau = -8.270521827469773\n", + "p = 15, SDID tau = -16.276325476709246\n", + "p = 16, SDID tau = -10.806997302864314\n", + "p = 17, SDID tau = -2.056041270362535\n", + "p = 18, SDID tau = -15.886851581450706\n", + "p = 19, SDID tau = 2.852840617999361\n" + ] }, { - "cell_type": "markdown", - "metadata": { - "id": "e748YgFHW3Vh" - }, - "source": [ - "## Matrix Completion\n", - "\n", - "The third method is based on matrix completion method proposed by [4]. The idea is to solve the following matrix completion problem, only using the outcome data without intervention (i.e., $Z_{ij}=0$)\n", - "$$\n", - "\\hat{M}, \\hat{a}, \\hat{b} = \\arg\\min \\sum_{ij, Z_{ij}=0} (O_{ij}-M_{ij} - a_i - b_j)^2 + \\lambda \\|M\\|_{*}\n", - "$$\n", - "where $\\|M\\|_{*}$ is the nuclear norm that penalizes the low-rankness of the matrix (here $a_{i}$ and $b_{j}$ are used to improve the empirical performance, as suggested by [4]).\n", - "\n", - "After $\\hat{M}, \\hat{a}, \\hat{b}$ are obtained, the ATT $\\hat{\\tau}$ can be estimated simply by\n", - "$$\n", - "\\hat{\\tau} = \\frac{\\sum_{ij, Z_{ij}=1} (O_{ij} - \\hat{M}_{ij} - \\hat{a}_i - \\hat{b}_{j})}{\\sum_{ij, Z_{ij}=1} 1}.\n", - "$$\n", - "\n", - "To use this method (referred to as matrix completion with nuclear norm minimization, or MC-NNM), when you have an estimation of the rank of the matrix $M$ (e.g., by checking the spectrum), call\n", - "```\n", - "solver = MCNNMPanelSolver(Z=Z)\n", - "result = solver.solve_with_suggested_rank(O=O, suggest_r=1)\n", - "M, a, b, tau = result.M, result.row_fixed_effects, result.column_fixed_effects, result.tau\n", - "```\n", - "where `M`, `a`, `b` are the optimizers and `tau` is the estimated ATT.\n", - "\n", - "We also provide a function to help you find the right parameter $\\lambda$ or rank by cross-validation:\n", - "```\n", - "result = solver.solve_with_cross_validation(O=O, K=5)\n", - "M, a, b, tau = result.M, result.row_fixed_effects, result.column_fixed_effects, result.tau\n", - "```\n", - "\n", - "\n", - "[4] Athey, Susan, Mohsen Bayati, Nikolay Doudchenko, Guido Imbens, and Khashayar Khosravi. \"Matrix completion methods for causal panel data models.\" Journal of the American Statistical Association 116, no. 536 (2021): 1716-1730." + "data": { + "image/png": "iVBORw0KGgoAAAANSUhEUgAAAroAAAHWCAYAAACYIyqlAAAAOnRFWHRTb2Z0d2FyZQBNYXRwbG90bGliIHZlcnNpb24zLjEwLjgsIGh0dHBzOi8vbWF0cGxvdGxpYi5vcmcvwVt1zgAAAAlwSFlzAAAPYQAAD2EBqD+naQAAr9RJREFUeJztnQd4FOX2xk96CKQAAUINvfcOikhHLNjb34p6FXsXrwXRa72Wa7t2UfTaFWwgRUA6SO+9BhISAumkz/95v80sm81usrvZNrvv73k2m52dnZ35puw75zvfe0I0TdOEEEIIIYSQACPU1ytACCGEEEKIJ6DQJYQQQgghAQmFLiGEEEIICUgodAkhhBBCSEBCoUsIIYQQQgISCl1CCCGEEBKQUOgSQgghhJCAhEKXEEIIIYQEJBS6hBBCCCEkIKHQJcQP+eyzzyQkJEQOHjzo61UxBGirZ555xuF57777bvEWixcvVt+JZ0u++OIL6dy5s0REREhCQoJ5+r///W9p27athIWFSe/evb22nsEMjh3soxMnTkigYO/4CvbznwQfFLrEZ2zZskUuv/xySU5OlujoaGnevLmMGTNG3n777UrztW7dWl3I8AgNDVUX7R49esg//vEPWb16tUNiBoJRXwYeuPgnJibK0KFD5Z///KccPnzY4fW2XI7144477nCqDV544QWZNWuW+BMrVqxQPxpZWVliVDy1De46jnbu3Ck33XSTtGvXTj766CP58MMP1fR58+bJo48+KmeddZZMnz5dHR+B0sbYXrRZz549xVbleW/fgAQy9o6v6ti4caNcd9110rJlS4mKipIGDRrI6NGj1XFYVlYmgcj27dvVMcyAQmAT7usVIMEJfiRHjBghrVq1kttuu02SkpLkyJEjsmrVKnnzzTflnnvuqTQ/IlsPPfSQ+j83N1d27Ngh33//vbqIP/DAA/L666879L3XXHONTJgwQcrLy+XUqVPy999/y3/+8x/1nZ988olcffXVDi0HgvyGG26oMr1jx47iDBAyEPsXX3xxpenXX3+9Whf84Phi30ybNk39UBolEnT69GkJDw/32jY4cxydc845av0iIyPN0xDdxWcxf/v27c3TFy5cqG7msAzL+f0RV9sYN7g//fSTXHbZZR5dv2DG3vFlj48//ljdpDdp0kRdezp06KCus3/++afccsstkpqaqm7kjHL+OyN0cQyfe+65KqBCAhMKXeITnn/+eYmPj1cCwfpHMj09vcr8iPYi2mDJyy+/LNdee6288cYb6sI8efLkGr+3b9++VZZz6NAhGTt2rNx4443SpUsX6dWrV43LgaC1Xo47Qbc1HsQx0CPgTZw5jiBcrddPP8ZtHft16tRxq8gtKCiQmJgY8QewbYgYPvvss3LppZeqKG4w4a19Ye/4sgWCCxC5Q4YMkdmzZ0tsbKz5vfvvv1/Wrl0rW7duFX8DQr64uFidW94+/4nB0AjxAZ06ddLOPfdch+ZNTk7Wzj//fJvv5ebmag0aNNCaN2+ulZeXm6fj0L7rrrvMrw8cOKCm/fvf/7a5nBUrVqj3r7322hrXx3rZ9ti9e7d26aWXak2aNNGioqLUOl511VVaVlaWeTnWjxtvvFG9N336dPUa623dDosWLdL69eunRUdHa927d1evwY8//qhe47v69u2rrV+/vtL6bNq0SS2/TZs2ah6s180336ydOHHCPM/UqVNtrpflenzxxRdq+fj++vXrq206fPiwU9tuizfffFMLDQ3VTp06ZZ726quvqu9/4IEHzNNKS0u1evXqaY8++milfYJ1d2Qb9P03c+ZMrVu3blpkZKTWtWtXbc6cOTXuU1eOI+wfTNP3E/aj9brZW2ccB860+/Dhw9U2rV27Vhs2bJhWp04d7b777lPvFRYWak8//bTWrl07tc0tWrTQHnnkETXdEkfax5HjxBoce3Xr1tVmzJih5sXxaut7dWydA7ba03K7cYyfc845aruxnd9//716f/HixdrAgQNV23Xs2FGbP39+pWXq27Njxw7tiiuu0GJjY9V15d5779VOnz5dZVtquy/+/vtvbezYsVrDhg3VMlq3bq3ORUd499131f7AfmnatKl25513Vjpn7B1f9hg/frwWHh6uHTp0yKHvz8vL0x588EF1/GAd0J44Hyyvv9huW9f3srIyrVmzZtpll11mnobPDhkyRLU32gLtqu83W8fHl19+qbYf64xjVH/PchsPHjyoTZ48Wa0blollX3755ZWOJf34sn5YHlezZ8/Wzj77bC0mJkZdcyZMmKBt3bq10nqlpqZqN910k7rGoT2SkpK0iy66qNpzgXgXRnSJT0Be7sqVK1WkoHv37i4vp169enLJJZeorl50Q3Xr1s2l5SCagXy2+fPnOzR/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", + "text/plain": [ + "
" ] - }, + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "# Here we generate synthetic time-varying exogenous covariates X_cov.\n", + "# We want X_cov to have shape (n, T, p), where:\n", + "# n: number of units (rows in O)\n", + "# T: number of time periods (columns in O)\n", + "# p: number of covariates (here we try various p to see 'stability')\n", + "np.random.seed(0)\n", + "\n", + "p_values = range(1, 20)\n", + "tau_estimates = []\n", + "\n", + "n, T = O.shape\n", + "\n", + "solver = SDIDPanelSolver(Z=Z, O=O)\n", + "result = solver.fit()\n", + "tau_no_cov = result.tau\n", + "\n", + "for p in p_values:\n", + " X_cov = np.random.randn(n, T, p)\n", + "\n", + " solver = SDIDPanelSolver(Z=Z, O=O, X_cov=X_cov)\n", + " result = solver.fit()\n", + " tau = result.tau\n", + " tau_estimates.append(tau)\n", + " print(f\"p = {p}, SDID tau = {tau}\")\n", + "\n", + "plt.figure(figsize=(8, 5))\n", + "plt.plot(p_values, tau_estimates, marker='o', label='SDID tau with fake covariates')\n", + "plt.axhline(tau_no_cov, color='red', linestyle='--', label='SDID tau without covariates')\n", + "plt.xlabel(\"Number of Covariates (p)\")\n", + "plt.ylabel(\"SDID Estimate (tau)\")\n", + "plt.title(\"SDID Estimates with Different Numbers of Covariates\")\n", + "plt.legend()\n", + "plt.grid(True)\n", + "plt.show()" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "id": "e748YgFHW3Vh" + }, + "source": [ + "## Matrix Completion\n", + "\n", + "The third method is based on matrix completion method proposed by [4]. The idea is to solve the following matrix completion problem, only using the outcome data without intervention (i.e., $Z_{ij}=0$)\n", + "$$\n", + "\\hat{M}, \\hat{a}, \\hat{b} = \\arg\\min \\sum_{ij, Z_{ij}=0} (O_{ij}-M_{ij} - a_i - b_j)^2 + \\lambda \\|M\\|_{*}\n", + "$$\n", + "where $\\|M\\|_{*}$ is the nuclear norm that penalizes the low-rankness of the matrix (here $a_{i}$ and $b_{j}$ are used to improve the empirical performance, as suggested by [4]).\n", + "\n", + "After $\\hat{M}, \\hat{a}, \\hat{b}$ are obtained, the ATT $\\hat{\\tau}$ can be estimated simply by\n", + "$$\n", + "\\hat{\\tau} = \\frac{\\sum_{ij, Z_{ij}=1} (O_{ij} - \\hat{M}_{ij} - \\hat{a}_i - \\hat{b}_{j})}{\\sum_{ij, Z_{ij}=1} 1}.\n", + "$$\n", + "\n", + "The recommended MC-NNM solver API is now `fit`. It dispatches to the older explicit solver methods based on the arguments you pass:\n", + "\n", + "```python\n", + "solver = MCNNMPanelSolver(Z=Z)\n", + "result = solver.fit(O=O, suggest_r=1) # calls solve_with_suggested_rank\n", + "result = solver.fit(O=O, l=2.0) # calls solve_with_regularizer\n", + "result = solver.fit(O=O, K=5, list_l=None) # calls solve_with_cross_validation\n", + "```\n", + "\n", + "The old explicit methods are still available if you prefer them:\n", + "\n", + "```python\n", + "result = solver.solve_with_suggested_rank(O=O, suggest_r=1)\n", + "result = solver.solve_with_regularizer(O=O, l=2.0)\n", + "result = solver.solve_with_cross_validation(O=O, K=5)\n", + "```\n", + "\n", + "[4] Athey, Susan, Mohsen Bayati, Nikolay Doudchenko, Guido Imbens, and Khashayar Khosravi. \"Matrix completion methods for causal panel data models.\" Journal of the American Statistical Association 116, no. 536 (2021): 1716-1730.\n" + ] + }, + { + "cell_type": "code", + "execution_count": 14, + "metadata": {}, + "outputs": [ { - "cell_type": "code", - "execution_count": 30, - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "-22.345401569119492" - ] - }, - "execution_count": 30, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "from causaltensor.cauest.MCNNM import MCNNMPanelSolver\n", - "\n", - "solver = MCNNMPanelSolver(Z=Z)\n", - "result = solver.solve_with_suggested_rank(O=O, suggest_r=1)\n", - "M, a, b, tau = result.M, result.row_fixed_effects, result.column_fixed_effects, result.tau\n", - "\n", - "tau" + "data": { + "text/plain": [ + "-22.34540156911949" ] - }, + }, + "execution_count": 14, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "from causaltensor.cauest.MCNNM import MCNNMPanelSolver\n", + "\n", + "solver = MCNNMPanelSolver(Z=Z)\n", + "result = solver.fit(O=O, suggest_r=1)\n", + "M, a, b, tau = result.M, result.row_fixed_effects, result.column_fixed_effects, result.tau\n", + "\n", + "# Old explicit solver API equivalent:\n", + "# result = solver.solve_with_suggested_rank(O=O, suggest_r=1)\n", + "\n", + "tau\n" + ] + }, + { + "cell_type": "code", + "execution_count": 15, + "metadata": { + "id": "mKB3_m0WArJw" + }, + "outputs": [ { - "cell_type": "code", - "execution_count": 31, - "metadata": { - "id": "mKB3_m0WArJw" - }, - "outputs": [ - { - "data": { - "text/plain": [ - "-20.267535327741044" - ] - }, - "execution_count": 31, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "result = solver.solve_with_cross_validation(O=O, K=5)\n", - "M, a, b, tau = result.M, result.row_fixed_effects, result.column_fixed_effects, result.tau\n", - "\n", - "tau" + "data": { + "text/plain": [ + "-20.267535327741044" ] + }, + "execution_count": 15, + "metadata": {}, + "output_type": "execute_result" } - ], - "metadata": { - "colab": { - "provenance": [] - }, - "kernelspec": { - "display_name": ".venv", - "language": "python", - "name": "python3" - }, - "language_info": { - "codemirror_mode": { - "name": "ipython", - "version": 3 - }, - "file_extension": ".py", - "mimetype": "text/x-python", - "name": "python", - "nbconvert_exporter": "python", - "pygments_lexer": "ipython3", - "version": "3.11.5" - }, - "orig_nbformat": 4 + ], + "source": [ + "result = solver.fit(O=O, K=5)\n", + "M, a, b, tau = result.M, result.row_fixed_effects, result.column_fixed_effects, result.tau\n", + "\n", + "# Old explicit solver API equivalent:\n", + "# result = solver.solve_with_cross_validation(O=O, K=5)\n", + "\n", + "tau\n" + ] + } + ], + "metadata": { + "colab": { + "provenance": [] + }, + "kernelspec": { + "display_name": ".venv", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.13.5" }, - "nbformat": 4, - "nbformat_minor": 0 + "orig_nbformat": 4 + }, + "nbformat": 4, + "nbformat_minor": 0 } diff --git a/tutorials/datasets.ipynb b/tutorials/datasets.ipynb index fd0f90d..f59c2f2 100644 --- a/tutorials/datasets.ipynb +++ b/tutorials/datasets.ipynb @@ -1,363 +1,86 @@ { "cells": [ - { - "cell_type": "code", - "execution_count": 27, - "id": "e8453a1a", - "metadata": {}, - "outputs": [], - "source": [ - "import pandas as pd\n", - "import numpy as np\n", - "import pyreadr\n", - "\n", - "\n", - "def create_y_dataframe(df: pd.DataFrame, index_col: str, column_col: str, value_col: str) -> pd.DataFrame:\n", - " \"\"\"\n", - " Create Y dataframe (entity x time matrix) from long-form data.\n", - " Removes rows or columns with NaN values before pivoting, choosing which to remove\n", - " based on which has a higher percentage of NaNs.\n", - " \n", - " Args:\n", - " df: Long-form dataframe\n", - " index_col: Column name for entities/rows\n", - " column_col: Column name for time periods/columns\n", - " value_col: Column name for values\n", - " \n", - " Returns:\n", - " Y_df: Wide-form dataframe with entities as index and time as columns\n", - " \"\"\"\n", - " df = df.copy() # Avoid SettingWithCopyWarning\n", - " df[column_col] = df[column_col].astype(int)\n", - " \n", - " # Check for NaN values in value_col\n", - " if df[value_col].isna().any():\n", - " # Calculate how many data points would be lost by removing entities vs times\n", - " entities_with_nan = df[df[value_col].isna()][index_col].unique()\n", - " times_with_nan = df[df[value_col].isna()][column_col].unique()\n", - " \n", - " total_entities = df[index_col].nunique()\n", - " total_times = df[column_col].nunique()\n", - " total_rows = len(df)\n", - " \n", - " # Count how many rows would be removed by each strategy\n", - " rows_if_remove_entities = len(df[df[index_col].isin(entities_with_nan)])\n", - " rows_if_remove_times = len(df[df[column_col].isin(times_with_nan)])\n", - " \n", - " pct_entities_with_nan = len(entities_with_nan) / total_entities if total_entities > 0 else 0\n", - " pct_times_with_nan = len(times_with_nan) / total_times if total_times > 0 else 0\n", - " \n", - " # Remove whichever loses fewer total data points\n", - " if rows_if_remove_entities <= rows_if_remove_times:\n", - " # Remove entities (rows) - loses fewer data points\n", - " df = df[~df[index_col].isin(entities_with_nan)]\n", - " print(f\"Removed {len(entities_with_nan)} entities ({pct_entities_with_nan:.1%}) with NaN values, losing {rows_if_remove_entities}/{total_rows} data points ({rows_if_remove_entities/total_rows:.1%})\")\n", - " else:\n", - " # Remove time periods (columns) - loses fewer data points\n", - " df = df[~df[column_col].isin(times_with_nan)]\n", - " print(f\"Removed {len(times_with_nan)} time periods ({pct_times_with_nan:.1%}) with NaN values, losing {rows_if_remove_times}/{total_rows} data points ({rows_if_remove_times/total_rows:.1%})\")\n", - " \n", - " Y_df = df.pivot(index=index_col, columns=column_col, values=value_col)\n", - " return Y_df\n", - "\n", - "\n", - "def create_z_dataframe(Y_df, treated_entity, treatment_start_year):\n", - " \"\"\"\n", - " Create Z dataframe (treatment indicator matrix).\n", - " \n", - " Args:\n", - " Y_df: Entity x time matrix\n", - " treated_entity: Name of the treated entity\n", - " treatment_start_year: Year when treatment starts\n", - " \n", - " Returns:\n", - " Z_df: Treatment indicator matrix (1 for treated entity after treatment, 0 otherwise)\n", - " \"\"\"\n", - " Z_df = pd.DataFrame(0, index=Y_df.index, columns=Y_df.columns)\n", - " treated_mask = Z_df.index == treated_entity\n", - " post_treatment_mask = Z_df.columns >= treatment_start_year\n", - " Z_df.loc[treated_mask, post_treatment_mask] = 1\n", - " return Z_df\n", - "\n", - "\n", - "def create_x_dataframe(df: pd.DataFrame, Y_df: pd.DataFrame, index_col: str, time_col: str, \n", - " covariate_cols: list, avg_start_year: int, avg_end_year: int, \n", - " additional_cols) -> pd.DataFrame:\n", - " \"\"\"\n", - " Create X dataframe (covariates matrix) by averaging over pre-treatment period.\n", - " \n", - " Args:\n", - " df: Long-form dataframe\n", - " Y_df: Entity x time matrix\n", - " index_col: Column name for entities\n", - " time_col: Column name for time periods\n", - " covariate_cols: List of covariate columns to average\n", - " avg_start_year: Start year for averaging period\n", - " avg_end_year: End year for averaging period\n", - " additional_cols: Dict mapping new column names to years to add from Y_df\n", - " e.g., {'Smoking 1988': 1988, 'Smoking 1980': 1980}\n", - " \n", - " Returns:\n", - " X_df: Covariates matrix with entities as rows\n", - " \"\"\"\n", - " # Filter to averaging period and only entities present in Y_df\n", - " mask = (df[time_col] >= avg_start_year) & (df[time_col] <= avg_end_year)\n", - " mask = mask & df[index_col].isin(Y_df.index) & df[time_col].isin(Y_df.columns)\n", - " \n", - " # Average covariates over period\n", - " X_df = (\n", - " df.loc[mask, [index_col] + covariate_cols]\n", - " .groupby(index_col, as_index=False)\n", - " .mean()\n", - " )\n", - " \n", - " # Set index to match Y_df for proper alignment\n", - " X_df = X_df.set_index(index_col)\n", - " \n", - " # Add additional columns from Y_df if specified\n", - " if additional_cols is not None:\n", - " for col_name, year in additional_cols.items():\n", - " if year in Y_df.columns:\n", - " # Use loc to ensure proper alignment with Y_df index\n", - " X_df[col_name] = Y_df.loc[X_df.index, year]\n", - " \n", - " return X_df\n" - ] - }, - { - "cell_type": "markdown", - "id": "d7345809", - "metadata": {}, - "source": [ - "### Smoking Dataset" - ] - }, - { - "cell_type": "code", - "execution_count": 21, - "id": "43c779c7", - "metadata": {}, - "outputs": [], - "source": [ - "# Load the smoking.rda data (if not already loaded)\n", - "result = pyreadr.read_r('../src/causaltensor/datasets/raw/smoking.rda')\n", - "df = list(result.values())[0]\n", - "\n", - "# State mapping from documentation\n", - "state_mapping = {\n", - " 1: 'Alabama', 2: 'Arkansas', 3: 'California', 4: 'Colorado',\n", - " 5: 'Connecticut', 6: 'Delaware', 7: 'Georgia', 8: 'Idaho',\n", - " 9: 'Illinois', 10: 'Indiana', 11: 'Iowa', 12: 'Kansas',\n", - " 13: 'Kentucky', 14: 'Louisiana', 15: 'Maine', 16: 'Minnesota',\n", - " 17: 'Mississippi', 18: 'Missouri', 19: 'Montana', 20: 'Nebraska',\n", - " 21: 'Nevada', 22: 'New Hampshire', 23: 'New Mexico', 24: 'North Carolina',\n", - " 25: 'North Dakota', 26: 'Ohio', 27: 'Oklahoma', 28: 'Pennsylvania',\n", - " 29: 'Rhode Island', 30: 'South Carolina', 31: 'South Dakota', 32: 'Tennessee',\n", - " 33: 'Texas', 34: 'Utah', 35: 'Vermont', 36: 'Virginia',\n", - " 37: 'West Virginia', 38: 'Wisconsin', 39: 'Wyoming'\n", - "}\n", - "df[\"state\"] = df[\"state\"].map(state_mapping)\n", - "\n", - "\n", - "# Create Y_df, Z_df, and X_df using helper functions\n", - "Y_df = create_y_dataframe(df, index_col=\"state\", column_col=\"year\", value_col=\"cigsale\")\n", - "Y = Y_df.to_numpy()\n", - "\n", - "# Create Z matrix: 1 for California after 1988, 0 otherwise\n", - "Z_df = create_z_dataframe(Y_df, treated_entity='California', treatment_start_year=1988)\n", - "\n", - "# Create X dataframe\n", - "cols_to_avg = [col for col in df.columns if col not in ['state', 'year', 'cigsale']]\n", - "X_df = create_x_dataframe(\n", - " df, Y_df, \n", - " index_col='state', \n", - " time_col='year',\n", - " covariate_cols=cols_to_avg,\n", - " avg_start_year=1980, \n", - " avg_end_year=1988,\n", - " additional_cols={'Smoking 1988': 1988, 'Smoking 1980': 1980, 'Smoking 1975': 1975}\n", - ")\n", - "\n", - "\n" - ] - }, - { - "cell_type": "markdown", - "id": "b6743cf2", - "metadata": {}, - "source": [ - "### Basque Dataset" - ] - }, { "cell_type": "code", "execution_count": 2, - "id": "c42300a2", - "metadata": {}, - "outputs": [], - "source": [ - "# Load the basque.rda data \n", - "result = pyreadr.read_r('../src/causaltensor/datasets/raw/basque.rda')\n", - "df = list(result.values())[0]\n", - "\n", - "\n", - "# Create Y_df, Z_df, and X_df using helper functions\n", - "Y_df = create_y_dataframe(df, index_col=\"regionname\", column_col=\"year\", value_col=\"gdpcap\")\n", - "\n", - "Z_df = create_z_dataframe(Y_df, treated_entity='Basque Country (Pais Vasco)', treatment_start_year=1975)\n", - "\n", - "cols_to_avg = ['invest', 'secagriculture',\n", - " 'secenergy', 'secindustry', 'secconstruction', 'secservicesventa',\n", - " 'secservicesnonventa', 'schoolillit', 'schoolprim', 'schoolmed',\n", - " 'schoolhigh', 'schoolposthigh', 'popdens']\n", - "\n", - "X_df = create_x_dataframe(\n", - " df, Y_df,\n", - " index_col='regionname',\n", - " time_col='year',\n", - " covariate_cols=cols_to_avg,\n", - " avg_start_year=1964,\n", - " avg_end_year=1969,\n", - " additional_cols={'gdpcap1960': 1960, 'gdpcap1965': 1965, 'gdpcap1970': 1970}\n", - ")\n", - "\n" - ] - }, - { - "cell_type": "code", - "execution_count": 3, - "id": "eb363b4f", + "id": "e8453a1a", "metadata": {}, "outputs": [ { "data": { "text/plain": [ - "(18, 43)" + "('smoking',\n", + " 'basque',\n", + " 'german_reunification',\n", + " 'texas',\n", + " 'pwt_spain_eu',\n", + " 'pwt_chile_trade',\n", + " 'pwt_korea_democracy',\n", + " 'pwt_norway_oil',\n", + " 'retailrocket',\n", + " 'dunnhumby',\n", + " 'truus',\n", + " 'movielens')" ] }, - "execution_count": 3, + "execution_count": 2, "metadata": {}, "output_type": "execute_result" } ], "source": [ - "Y_df.shape" - ] - }, - { - "cell_type": "markdown", - "id": "acdfb66e", - "metadata": {}, - "source": [ - "### German Reunification Dataset" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "94fe7371", - "metadata": {}, - "outputs": [], - "source": [ - "df = pd.read_csv('../src/causaltensor/datasets/raw/german_reunification.csv')\n", + "# Use the dataset loader from the package instead of duplicating helper functions here.\n", + "# When this notebook is run from a source checkout, make the local src/ package importable.\n", + "from pathlib import Path\n", + "import sys\n", "\n", "\n", - "# Create Y_df, Z_df, and X_df using helper functions\n", - "Y_df = create_y_dataframe(df, index_col=\"country\", column_col=\"year\", value_col=\"gdp\")\n", - "Y_df\n", + "def find_project_root(start: Path) -> Path | None:\n", + " for candidate in (start, *start.parents):\n", + " if (candidate / \"src\" / \"causaltensor\" / \"datasets\" / \"dataset_loader.py\").exists():\n", + " return candidate\n", + " return None\n", "\n", - "Z_df = create_z_dataframe(Y_df, treated_entity='West Germany', treatment_start_year=1990)\n", "\n", - "cols_to_avg = ['infrate', 'trade', 'schooling', 'industry']\n", + "PROJECT_ROOT = find_project_root(Path.cwd().resolve())\n", + "if PROJECT_ROOT is not None:\n", + " sys.path.insert(0, str(PROJECT_ROOT / \"src\"))\n", "\n", - "X_df = create_x_dataframe(\n", - " df, Y_df,\n", - " index_col='country',\n", - " time_col='year',\n", - " covariate_cols=cols_to_avg,\n", - " avg_start_year=1980,\n", - " avg_end_year=1985,\n", - " additional_cols={'gdp1960': 1960, 'gdp1970': 1970, 'gdp1980': 1980, 'gdp1985': 1985}\n", + "from causaltensor.datasets import dataset_loader\n", + "from causaltensor.datasets.dataset_loader import (\n", + " available_datasets,\n", + " create_x_dataframe,\n", + " create_y_dataframe,\n", + " create_z_dataframe,\n", + " load_dataset,\n", ")\n", "\n", - "# Add investment columns (these are pre-existing in the original data)\n", - "X_df['invest60'] = df[~df['invest60'].isna()]['invest60'].values\n", - "X_df['invest70'] = df[~df['invest70'].isna()]['invest70'].values\n", - "X_df['invest80'] = df[~df['invest80'].isna()]['invest80'].values\n" - ] - }, - { - "cell_type": "markdown", - "id": "de1b4bb9", - "metadata": {}, - "source": [ - "### Texas Prison" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "50ea573f", - "metadata": {}, - "outputs": [], - "source": [ - "result = pyreadr.read_r('../src/causaltensor/datasets/raw/texas.rda')\n", - "df = list(result.values())[0]\n", - "\n", - "\n", - "fips_map = {\n", - " 1: \"Alabama\", 2: \"Alaska\", 4: \"Arizona\", 5: \"Arkansas\", 6: \"California\",\n", - " 8: \"Colorado\", 9: \"Connecticut\", 10: \"Delaware\", 11: \"District of Columbia\",\n", - " 12: \"Florida\", 13: \"Georgia\", 15: \"Hawaii\", 16: \"Idaho\", 17: \"Illinois\",\n", - " 18: \"Indiana\", 19: \"Iowa\", 20: \"Kansas\", 21: \"Kentucky\", 22: \"Louisiana\",\n", - " 23: \"Maine\", 24: \"Maryland\", 25: \"Massachusetts\", 26: \"Michigan\",\n", - " 27: \"Minnesota\", 28: \"Mississippi\", 29: \"Missouri\", 30: \"Montana\",\n", - " 31: \"Nebraska\", 32: \"Nevada\", 33: \"New Hampshire\", 34: \"New Jersey\",\n", - " 35: \"New Mexico\", 36: \"New York\", 37: \"North Carolina\", 38: \"North Dakota\",\n", - " 39: \"Ohio\", 40: \"Oklahoma\", 41: \"Oregon\", 42: \"Pennsylvania\", 44: \"Rhode Island\",\n", - " 45: \"South Carolina\", 46: \"South Dakota\", 47: \"Tennessee\", 48: \"Texas\",\n", - " 49: \"Utah\", 50: \"Vermont\", 51: \"Virginia\", 53: \"Washington\", 54: \"West Virginia\",\n", - " 55: \"Wisconsin\", 56: \"Wyoming\"\n", - "}\n", - "\n", - "df[\"state\"] = df[\"statefip\"].map(fips_map)\n", - "\n", - "# Create Y_df, Z_df, and X_df using helper functions\n", - "Y_df = create_y_dataframe(df, index_col=\"state\", column_col=\"year\", value_col=\"bmprate\")\n", - "\n", - "Z_df = create_z_dataframe(Y_df, treated_entity='Texas', treatment_start_year=1993)\n", + "DATASETS_PATH = str(Path(dataset_loader.__file__).resolve().parent / \"raw\") + \"/\"\n", "\n", - "cols_to_avg = [\"income\", \"ur\", \"poverty\", \"black\", \"perc1519\",\n", - " \"aidscapita\", \"crack\", \"alcohol\", \"parole\",\n", - " \"probation\", \"capacity_operational\"]\n", - "\n", - "X_df = create_x_dataframe(\n", - " df, Y_df,\n", - " index_col='state',\n", - " time_col='year',\n", - " covariate_cols=cols_to_avg,\n", - " avg_start_year=1985,\n", - " avg_end_year=1993,\n", - " additional_cols={'bmprate1985': 1985, 'bmprate1990': 1990, 'bmprate1993': 1993}\n", - ")\n", - "\n", - "\n" + "available_datasets()\n" ] }, { "cell_type": "markdown", - "id": "3c069ce8", + "id": "d7345809", "metadata": {}, "source": [ - "### PWT" + "### Smoking Dataset" ] }, { "cell_type": "code", - "execution_count": 28, - "id": "c3d415d0", + "execution_count": 3, + "id": "43c779c7", "metadata": {}, "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "(39, 31) (39, 31) (39, 7)\n" + ] + }, { "data": { "text/html": [ @@ -378,593 +101,2413 @@ "\n", " \n", " \n", - " \n", - " \n", - " \n", - " \n", " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", " \n", " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", " \n", + " \n", + " \n", " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", " \n", " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", " \n", " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", " \n", " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", " \n", " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", " \n", " \n", "
countrycodecountrycurrency_unityearrgdpergdpopopempavhhc1970197119721973197419751976197719781979...csh_xcsh_mcsh_rpl_cpl_ipl_gpl_xpl_mpl_kopenness
0ABWArubaAruban Guilder1950NaNNaNNaNNaNNaNNaN...NaNNaNNaNNaNNaNNaNNaNNaNNaNNaN1991199219931994199519961997199819992000
1ABWArubaAruban Guilder1951NaNNaNNaNNaNNaNNaN...NaNNaNNaNNaNNaNNaNNaNNaNNaNNaNstate
2ABWArubaAruban Guilder1952NaNNaNNaNNaNNaNNaNAlabama89.80000395.400002101.099998102.900002108.199997111.699997116.199997117.099998123.000000121.400002...NaNNaNNaNNaNNaNNaNNaNNaNNaNNaN107.900002109.099998108.500000107.099998102.599998101.400002104.900002106.199997100.69999796.199997
3ABWArubaAruban Guilder1953NaNNaNNaNNaNNaNNaNArkansas100.300003104.099998103.900002108.000000109.699997114.800003119.099998122.599998127.300003126.500000...NaNNaNNaNNaNNaNNaNNaNNaNNaNNaN116.800003126.000000113.800003108.800003113.000000110.699997108.699997109.500000104.80000399.400002
4ABWArubaAruban Guilder1954NaNNaNNaNNaNNaNNaNCalifornia123.000000121.000000123.500000124.400002126.699997127.099998128.000000126.400002126.099998121.900002...NaNNaNNaNNaNNaNNaNNaNNaNNaNNaN68.69999767.50000063.40000258.59999856.40000254.50000053.79999952.29999947.20000141.599998
...............................................................Colorado124.800003125.500000134.300003137.899994132.800003131.000000134.199997132.000000129.199997131.500000...90.19999788.30000388.59999889.09999885.40000283.09999881.30000381.19999779.59999873.000000
11825ZWEZimbabweUS Dollar201020652.71875021053.85546913.9738976.298438NaN2.372605Connecticut120.000000117.599998110.800003109.300003112.400002110.199997113.400002117.300003117.500000117.400002...0.214657-0.4544970.0144620.4471700.5431000.4113160.7017970.6063241.015145-0.239839
11826ZWEZimbabweUS Dollar201120720.43554721592.29882814.2555926.518841NaN2.415823...0.219809-0.6251700.0043900.5310290.6060650.4402520.7399890.6370350.470333-0.405361
11827ZWEZimbabweUS Dollar201223708.65429724360.52734414.5654826.248271NaN2.459828...0.225631-0.479897-0.0769980.4740471.3631670.4583150.7120360.6348580.608320-0.254266
11828ZWEZimbabweUS Dollar201327011.98828128157.88671914.8980926.287056NaN2.504635...0.174443-0.436145-0.0000050.4980610.5758700.4650310.7178840.6307120.414526-0.261702
11829ZWEZimbabweUS Dollar201428495.55468829149.70898415.2458556.499974NaN2.550258...0.147346-0.349806-0.0200680.5280130.5501100.4646990.7169630.6288690.386039-0.20246086.69999783.50000079.09999876.59999879.30000376.00000075.90000275.50000073.40000271.400002
\n", - "

11830 rows × 48 columns

\n", + "

5 rows × 31 columns

\n", "" ], "text/plain": [ - " countrycode country currency_unit year rgdpe rgdpo \\\n", - "0 ABW Aruba Aruban Guilder 1950 NaN NaN \n", - "1 ABW Aruba Aruban Guilder 1951 NaN NaN \n", - "2 ABW Aruba Aruban Guilder 1952 NaN NaN \n", - "3 ABW Aruba Aruban Guilder 1953 NaN NaN \n", - "4 ABW Aruba Aruban Guilder 1954 NaN NaN \n", - "... ... ... ... ... ... ... \n", - "11825 ZWE Zimbabwe US Dollar 2010 20652.718750 21053.855469 \n", - "11826 ZWE Zimbabwe US Dollar 2011 20720.435547 21592.298828 \n", - "11827 ZWE Zimbabwe US Dollar 2012 23708.654297 24360.527344 \n", - "11828 ZWE Zimbabwe US Dollar 2013 27011.988281 28157.886719 \n", - "11829 ZWE Zimbabwe US Dollar 2014 28495.554688 29149.708984 \n", - "\n", - " pop emp avh hc ... csh_x csh_m csh_r \\\n", - "0 NaN NaN NaN NaN ... NaN NaN NaN \n", - "1 NaN NaN NaN NaN ... NaN NaN NaN \n", - "2 NaN NaN NaN NaN ... NaN NaN NaN \n", - "3 NaN NaN NaN NaN ... NaN NaN NaN \n", - "4 NaN NaN NaN NaN ... NaN NaN NaN \n", - "... ... ... ... ... ... ... ... ... \n", - "11825 13.973897 6.298438 NaN 2.372605 ... 0.214657 -0.454497 0.014462 \n", - "11826 14.255592 6.518841 NaN 2.415823 ... 0.219809 -0.625170 0.004390 \n", - "11827 14.565482 6.248271 NaN 2.459828 ... 0.225631 -0.479897 -0.076998 \n", - "11828 14.898092 6.287056 NaN 2.504635 ... 0.174443 -0.436145 -0.000005 \n", - "11829 15.245855 6.499974 NaN 2.550258 ... 0.147346 -0.349806 -0.020068 \n", - "\n", - " pl_c pl_i pl_g pl_x pl_m pl_k openness \n", - "0 NaN NaN NaN NaN NaN NaN NaN \n", - "1 NaN NaN NaN NaN NaN NaN NaN \n", - "2 NaN NaN NaN NaN NaN NaN NaN \n", - "3 NaN NaN NaN NaN NaN NaN NaN \n", - "4 NaN NaN NaN NaN NaN NaN NaN \n", - "... ... ... ... ... ... ... ... \n", - "11825 0.447170 0.543100 0.411316 0.701797 0.606324 1.015145 -0.239839 \n", - "11826 0.531029 0.606065 0.440252 0.739989 0.637035 0.470333 -0.405361 \n", - "11827 0.474047 1.363167 0.458315 0.712036 0.634858 0.608320 -0.254266 \n", - "11828 0.498061 0.575870 0.465031 0.717884 0.630712 0.414526 -0.261702 \n", - "11829 0.528013 0.550110 0.464699 0.716963 0.628869 0.386039 -0.202460 \n", - "\n", - "[11830 rows x 48 columns]" + "year 1970 1971 1972 1973 1974 \\\n", + "state \n", + "Alabama 89.800003 95.400002 101.099998 102.900002 108.199997 \n", + "Arkansas 100.300003 104.099998 103.900002 108.000000 109.699997 \n", + "California 123.000000 121.000000 123.500000 124.400002 126.699997 \n", + "Colorado 124.800003 125.500000 134.300003 137.899994 132.800003 \n", + "Connecticut 120.000000 117.599998 110.800003 109.300003 112.400002 \n", + "\n", + "year 1975 1976 1977 1978 1979 ... \\\n", + "state ... \n", + "Alabama 111.699997 116.199997 117.099998 123.000000 121.400002 ... \n", + "Arkansas 114.800003 119.099998 122.599998 127.300003 126.500000 ... \n", + "California 127.099998 128.000000 126.400002 126.099998 121.900002 ... \n", + "Colorado 131.000000 134.199997 132.000000 129.199997 131.500000 ... \n", + "Connecticut 110.199997 113.400002 117.300003 117.500000 117.400002 ... \n", + "\n", + "year 1991 1992 1993 1994 1995 \\\n", + "state \n", + "Alabama 107.900002 109.099998 108.500000 107.099998 102.599998 \n", + "Arkansas 116.800003 126.000000 113.800003 108.800003 113.000000 \n", + "California 68.699997 67.500000 63.400002 58.599998 56.400002 \n", + "Colorado 90.199997 88.300003 88.599998 89.099998 85.400002 \n", + "Connecticut 86.699997 83.500000 79.099998 76.599998 79.300003 \n", + "\n", + "year 1996 1997 1998 1999 2000 \n", + "state \n", + "Alabama 101.400002 104.900002 106.199997 100.699997 96.199997 \n", + "Arkansas 110.699997 108.699997 109.500000 104.800003 99.400002 \n", + "California 54.500000 53.799999 52.299999 47.200001 41.599998 \n", + "Colorado 83.099998 81.300003 81.199997 79.599998 73.000000 \n", + "Connecticut 76.000000 75.900002 75.500000 73.400002 71.400002 \n", + "\n", + "[5 rows x 31 columns]" ] }, - "execution_count": 28, + "execution_count": 3, "metadata": {}, "output_type": "execute_result" } ], "source": [ - "df = pd.read_csv('../src/causaltensor/datasets/raw/PWT.csv')\n", - "df['openness'] = df['csh_x'] + df['csh_m']\n", - "df" - ] - }, - { - "cell_type": "markdown", - "id": "9b7ecc54", - "metadata": {}, - "source": [ - "##### Effect of Spain joining EU in 1986" - ] - }, - { - "cell_type": "code", - "execution_count": 29, - "id": "a5408b30", - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Removed 26 entities (14.3%) with NaN values, losing 806/5642 data points (14.3%)\n" - ] - } - ], - "source": [ - "df1 = df[(df['year'] >= 1970) & (df['year'] <= 2000)]\n", - "Y_df = create_y_dataframe(df1, index_col=\"country\", column_col=\"year\", value_col=\"rgdpe\")\n", + "Y_df, Z_df, X_df = load_dataset(\"smoking\", datasets_path=DATASETS_PATH)\n", "\n", - "Z_df = create_z_dataframe(Y_df, treated_entity='Spain', treatment_start_year=1986)\n", - "\n", - "cols_to_avg = [\"hc\",\"csh_i\",\"csh_c\",\"csh_g\",\"openness\",\"pl_gdpo\", \"pop\"]\n", - "\n", - "X_df = create_x_dataframe(\n", - " df1, Y_df,\n", - " index_col='country',\n", - " time_col='year',\n", - " covariate_cols=cols_to_avg,\n", - " avg_start_year=1970,\n", - " avg_end_year=1980,\n", - " additional_cols={'rgdpe1970': 1970, 'rgdpe1980': 1980, 'rgdpe1985': 1985}\n", - ")" + "print(Y_df.shape, Z_df.shape, X_df.shape)\n", + "Y_df.head()\n" ] }, { "cell_type": "markdown", - "id": "9a89736b", + "id": "b6743cf2", "metadata": {}, "source": [ - "##### Effect of Trade Liberalization in Chile 1976" + "### Basque Dataset" ] }, { "cell_type": "code", - "execution_count": 30, - "id": "80749e40", + "execution_count": 4, + "id": "c42300a2", "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ - "Removed 71 entities (39.0%) with NaN values, losing 2556/6552 data points (39.0%)\n" + "(18, 43) (18, 43) (18, 16)\n" ] - } - ], - "source": [ - "df1 = df[(df['year'] >= 1960) & (df['year'] <= 1995)]\n", - "\n", - "\n", - "Y_df = create_y_dataframe(df1, index_col=\"country\", column_col=\"year\", value_col=\"rgdpo\")\n", - "\n", - "\n", - "Z_df = create_z_dataframe(Y_df, treated_entity='Chile', treatment_start_year=1976)\n", - "\n", - "cols_to_avg = [\"hc\",\"csh_i\",\"csh_c\",\"csh_g\",\"openness\",\"pl_gdpo\", \"rkna\"]\n", - "\n", - "X_df = create_x_dataframe(\n", - " df1, Y_df,\n", - " index_col='country',\n", - " time_col='year',\n", - " covariate_cols=cols_to_avg,\n", - " avg_start_year=1970,\n", - " avg_end_year=1975,\n", - " additional_cols={'rgdpo1970': 1970, 'rgdpo1975': 1975}\n", - ")" - ] - }, - { - "cell_type": "markdown", - "id": "19584649", - "metadata": {}, - "source": [ - "##### Effect of Democratization in Republic of Korea in 1988" - ] - }, - { - "cell_type": "code", - "execution_count": 31, - "id": "0e5a1ae2", - "metadata": {}, - "outputs": [ + }, { - "name": "stdout", - "output_type": "stream", - "text": [ - "Removed 26 entities (14.3%) with NaN values, losing 806/5642 data points (14.3%)\n" - ] + "data": { + "text/html": [ + "
\n", + "\n", + "\n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
year1955195619571958195919601961196219631964...1988198919901991199219931994199519961997
regionname
Andalucia1.6887321.7584971.8276211.8527561.8780352.0101402.1291782.2803492.4310202.508855...5.1595975.4177385.5852615.7492155.6412455.5349185.6388175.7207235.9959306.300985
Aragon2.2887742.4451592.6033992.6390322.6770922.8814623.0995433.3591833.6141823.680091...7.8027708.2426458.4582988.6682388.4668668.2569278.5739788.8467589.0966869.518709
Baleares (Islas)3.1439593.3477583.5496293.6426733.7348624.0588404.3602544.6461734.9115255.050700...11.12039511.40816911.51242411.67952011.31962310.96972311.41959411.77377911.92659212.350043
Basque Country (Pais Vasco)3.8531853.9456584.0335624.0234224.0137824.2859184.5743364.8989575.1970155.338903...8.1205378.5097118.7767789.0252798.8738938.7182249.0181389.4408749.68651810.170666
Canarias1.9143822.0718372.2260782.2208652.2134392.3576842.4457302.6482432.8447592.951157...6.9770067.3379037.3450447.3471877.2200807.0921887.4107407.6163957.8170528.060555
\n", + "

5 rows × 43 columns

\n", + "
" + ], + "text/plain": [ + "year 1955 1956 1957 1958 1959 \\\n", + "regionname \n", + "Andalucia 1.688732 1.758497 1.827621 1.852756 1.878035 \n", + "Aragon 2.288774 2.445159 2.603399 2.639032 2.677092 \n", + "Baleares (Islas) 3.143959 3.347758 3.549629 3.642673 3.734862 \n", + "Basque Country (Pais Vasco) 3.853185 3.945658 4.033562 4.023422 4.013782 \n", + "Canarias 1.914382 2.071837 2.226078 2.220865 2.213439 \n", + "\n", + "year 1960 1961 1962 1963 1964 \\\n", + "regionname \n", + "Andalucia 2.010140 2.129178 2.280349 2.431020 2.508855 \n", + "Aragon 2.881462 3.099543 3.359183 3.614182 3.680091 \n", + "Baleares (Islas) 4.058840 4.360254 4.646173 4.911525 5.050700 \n", + "Basque Country (Pais Vasco) 4.285918 4.574336 4.898957 5.197015 5.338903 \n", + "Canarias 2.357684 2.445730 2.648243 2.844759 2.951157 \n", + "\n", + "year ... 1988 1989 1990 1991 \\\n", + "regionname ... \n", + "Andalucia ... 5.159597 5.417738 5.585261 5.749215 \n", + "Aragon ... 7.802770 8.242645 8.458298 8.668238 \n", + "Baleares (Islas) ... 11.120395 11.408169 11.512424 11.679520 \n", + "Basque Country (Pais Vasco) ... 8.120537 8.509711 8.776778 9.025279 \n", + "Canarias ... 6.977006 7.337903 7.345044 7.347187 \n", + "\n", + "year 1992 1993 1994 1995 \\\n", + "regionname \n", + "Andalucia 5.641245 5.534918 5.638817 5.720723 \n", + "Aragon 8.466866 8.256927 8.573978 8.846758 \n", + "Baleares (Islas) 11.319623 10.969723 11.419594 11.773779 \n", + "Basque Country (Pais Vasco) 8.873893 8.718224 9.018138 9.440874 \n", + "Canarias 7.220080 7.092188 7.410740 7.616395 \n", + "\n", + "year 1996 1997 \n", + "regionname \n", + "Andalucia 5.995930 6.300985 \n", + "Aragon 9.096686 9.518709 \n", + "Baleares (Islas) 11.926592 12.350043 \n", + "Basque Country (Pais Vasco) 9.686518 10.170666 \n", + "Canarias 7.817052 8.060555 \n", + "\n", + "[5 rows x 43 columns]" + ] + }, + "execution_count": 4, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "Y_df, Z_df, X_df = load_dataset(\"basque\", datasets_path=DATASETS_PATH)\n", + "\n", + "print(Y_df.shape, Z_df.shape, X_df.shape)\n", + "Y_df.head()\n" + ] + }, + { + "cell_type": "code", + "execution_count": 5, + "id": "eb363b4f", + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "(18, 43)" + ] + }, + "execution_count": 5, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "Y_df.shape\n" + ] + }, + { + "cell_type": "markdown", + "id": "acdfb66e", + "metadata": {}, + "source": [ + "### German Reunification Dataset" + ] + }, + { + "cell_type": "code", + "execution_count": 6, + "id": "94fe7371", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "(17, 44) (17, 44) (17, 11)\n" + ] + }, + { + "data": { + "text/html": [ + "
\n", + "\n", + "\n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
year1960196119621963196419651966196719681969...1994199519961997199819992000200120022003
country
Australia2373234625392717287329733230340437884162...20583217732256223649248532628327403284922981931273
Austria1796189919772074222423362537266829083239...22139229762400824472253142655828359288552994230796
Belgium1782188320182122228824142559271929583308...21340222482268723416241642479226631280012933030082
Denmark2329248526652700298031773377358038924352...21691226932378124878256692711328798298373031830853
France1858195920992205236725262728291531633531...20695215452228823370244122511126690280432882929210
\n", + "

5 rows × 44 columns

\n", + "
" + ], + "text/plain": [ + "year 1960 1961 1962 1963 1964 1965 1966 1967 1968 1969 ... \\\n", + "country ... \n", + "Australia 2373 2346 2539 2717 2873 2973 3230 3404 3788 4162 ... \n", + "Austria 1796 1899 1977 2074 2224 2336 2537 2668 2908 3239 ... \n", + "Belgium 1782 1883 2018 2122 2288 2414 2559 2719 2958 3308 ... \n", + "Denmark 2329 2485 2665 2700 2980 3177 3377 3580 3892 4352 ... \n", + "France 1858 1959 2099 2205 2367 2526 2728 2915 3163 3531 ... \n", + "\n", + "year 1994 1995 1996 1997 1998 1999 2000 2001 2002 \\\n", + "country \n", + "Australia 20583 21773 22562 23649 24853 26283 27403 28492 29819 \n", + "Austria 22139 22976 24008 24472 25314 26558 28359 28855 29942 \n", + "Belgium 21340 22248 22687 23416 24164 24792 26631 28001 29330 \n", + "Denmark 21691 22693 23781 24878 25669 27113 28798 29837 30318 \n", + "France 20695 21545 22288 23370 24412 25111 26690 28043 28829 \n", + "\n", + "year 2003 \n", + "country \n", + "Australia 31273 \n", + "Austria 30796 \n", + "Belgium 30082 \n", + "Denmark 30853 \n", + "France 29210 \n", + "\n", + "[5 rows x 44 columns]" + ] + }, + "execution_count": 6, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "Y_df, Z_df, X_df = load_dataset(\"german_reunification\", datasets_path=DATASETS_PATH)\n", + "\n", + "print(Y_df.shape, Z_df.shape, X_df.shape)\n", + "Y_df.head()\n" + ] + }, + { + "cell_type": "markdown", + "id": "de1b4bb9", + "metadata": {}, + "source": [ + "### Texas Prison" + ] + }, + { + "cell_type": "code", + "execution_count": 7, + "id": "50ea573f", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "(51, 16) (51, 16) (51, 14)\n" + ] + }, + { + "data": { + "text/html": [ + "
\n", + "\n", + "\n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
year1985198619871988198919901991199219931994199519961997199819992000
state
Alabama1340.7890621430.4223631557.2832031546.9344481718.0892331972.8787842122.4916992195.5344242313.0004882383.3034672499.5773932618.1457522661.9133302693.0205082890.2646482747.605469
Alaska1751.4373781798.1932371838.2041022253.4509282507.4819342275.7802732463.1315922438.6606452212.1704103130.1855473535.5563963975.1350104337.6601564063.8723143677.7446294113.869141
Arizona2613.9707032791.4487303065.0148933126.9819343460.1311043792.4218753874.4624024071.6762704233.9692384298.1538094137.5312503982.8232423927.1279303994.9426273957.4177254234.625000
Arkansas1229.1408691283.2348631454.2535401520.9344481796.5207522093.9748542372.4746092495.4846192564.8393552528.6196292623.8625492604.3642582773.1311042864.8586432530.0769042925.864990
California1603.9453121895.0395512096.7744142435.9208982696.2121582794.7001952818.1518552898.3461913070.2707523160.3405763320.1142583543.5742193705.4052733795.2573243768.6418464162.177734
\n", + "
" + ], + "text/plain": [ + "year 1985 1986 1987 1988 1989 \\\n", + "state \n", + "Alabama 1340.789062 1430.422363 1557.283203 1546.934448 1718.089233 \n", + "Alaska 1751.437378 1798.193237 1838.204102 2253.450928 2507.481934 \n", + "Arizona 2613.970703 2791.448730 3065.014893 3126.981934 3460.131104 \n", + "Arkansas 1229.140869 1283.234863 1454.253540 1520.934448 1796.520752 \n", + "California 1603.945312 1895.039551 2096.774414 2435.920898 2696.212158 \n", + "\n", + "year 1990 1991 1992 1993 1994 \\\n", + "state \n", + "Alabama 1972.878784 2122.491699 2195.534424 2313.000488 2383.303467 \n", + "Alaska 2275.780273 2463.131592 2438.660645 2212.170410 3130.185547 \n", + "Arizona 3792.421875 3874.462402 4071.676270 4233.969238 4298.153809 \n", + "Arkansas 2093.974854 2372.474609 2495.484619 2564.839355 2528.619629 \n", + "California 2794.700195 2818.151855 2898.346191 3070.270752 3160.340576 \n", + "\n", + "year 1995 1996 1997 1998 1999 \\\n", + "state \n", + "Alabama 2499.577393 2618.145752 2661.913330 2693.020508 2890.264648 \n", + "Alaska 3535.556396 3975.135010 4337.660156 4063.872314 3677.744629 \n", + "Arizona 4137.531250 3982.823242 3927.127930 3994.942627 3957.417725 \n", + "Arkansas 2623.862549 2604.364258 2773.131104 2864.858643 2530.076904 \n", + "California 3320.114258 3543.574219 3705.405273 3795.257324 3768.641846 \n", + "\n", + "year 2000 \n", + "state \n", + "Alabama 2747.605469 \n", + "Alaska 4113.869141 \n", + "Arizona 4234.625000 \n", + "Arkansas 2925.864990 \n", + "California 4162.177734 " + ] + }, + "execution_count": 7, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "Y_df, Z_df, X_df = load_dataset(\"texas\", datasets_path=DATASETS_PATH)\n", + "\n", + "print(Y_df.shape, Z_df.shape, X_df.shape)\n", + "Y_df.head()\n" + ] + }, + { + "cell_type": "markdown", + "id": "3c069ce8", + "metadata": {}, + "source": [ + "### PWT" + ] + }, + { + "cell_type": "code", + "execution_count": 8, + "id": "c3d415d0", + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "['pwt_spain_eu', 'pwt_chile_trade', 'pwt_korea_democracy', 'pwt_norway_oil']" + ] + }, + "execution_count": 8, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "[name for name in available_datasets() if name.startswith(\"pwt_\")]\n" + ] + }, + { + "cell_type": "markdown", + "id": "9b7ecc54", + "metadata": {}, + "source": [ + "##### Effect of Spain joining EU in 1986" + ] + }, + { + "cell_type": "code", + "execution_count": 9, + "id": "a5408b30", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "(156, 31) (156, 31) (156, 10)\n" + ] + }, + { + "data": { + "text/html": [ + "
\n", + "\n", + "\n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
year1970197119721973197419751976197719781979...1991199219931994199519961997199819992000
country
Albania7195.1362307484.0708017785.1469738094.2226568422.0996098762.2919929096.4677739488.2451179868.45898410175.361328...10943.8486338529.64355510397.22070312423.66796913408.30566415897.17187512886.21484412879.90039114811.45703115202.245117
Algeria78035.45312576008.90625086169.73437594097.140625133679.859375128089.218750138225.078125151840.703125165145.125000192594.437500...217913.921875211870.812500198044.656250194623.453125201560.718750223520.937500223795.171875220101.734375235706.593750292367.500000
Angola29908.92773431722.32617231588.73242234156.40234435161.25781233603.02734431978.71289132063.10156230359.81054730061.013672...27015.67187530068.55078127618.68359429808.39648429791.78710942065.92968837445.67968843470.89453140999.21484434137.144531
Anguilla57.17253555.74837562.20414764.82572964.68508966.83895167.92566768.21097673.27482679.869453...150.204834188.016861193.979630211.171829202.151077206.903473226.427460261.738708274.561401275.259064
Antigua and Barbuda294.362762316.143463339.413971366.885284383.829620360.888519326.909241350.598480353.902130439.012634...811.863037832.927429894.009094947.404114904.497864950.0932621011.6744381085.6427001141.3162841182.556885
\n", + "

5 rows × 31 columns

\n", + "
" + ], + "text/plain": [ + "year 1970 1971 1972 1973 \\\n", + "country \n", + "Albania 7195.136230 7484.070801 7785.146973 8094.222656 \n", + "Algeria 78035.453125 76008.906250 86169.734375 94097.140625 \n", + "Angola 29908.927734 31722.326172 31588.732422 34156.402344 \n", + "Anguilla 57.172535 55.748375 62.204147 64.825729 \n", + "Antigua and Barbuda 294.362762 316.143463 339.413971 366.885284 \n", + "\n", + "year 1974 1975 1976 \\\n", + "country \n", + "Albania 8422.099609 8762.291992 9096.467773 \n", + "Algeria 133679.859375 128089.218750 138225.078125 \n", + "Angola 35161.257812 33603.027344 31978.712891 \n", + "Anguilla 64.685089 66.838951 67.925667 \n", + "Antigua and Barbuda 383.829620 360.888519 326.909241 \n", + "\n", + "year 1977 1978 1979 ... \\\n", + "country ... \n", + "Albania 9488.245117 9868.458984 10175.361328 ... \n", + "Algeria 151840.703125 165145.125000 192594.437500 ... \n", + "Angola 32063.101562 30359.810547 30061.013672 ... \n", + "Anguilla 68.210976 73.274826 79.869453 ... \n", + "Antigua and Barbuda 350.598480 353.902130 439.012634 ... \n", + "\n", + "year 1991 1992 1993 \\\n", + "country \n", + "Albania 10943.848633 8529.643555 10397.220703 \n", + "Algeria 217913.921875 211870.812500 198044.656250 \n", + "Angola 27015.671875 30068.550781 27618.683594 \n", + "Anguilla 150.204834 188.016861 193.979630 \n", + "Antigua and Barbuda 811.863037 832.927429 894.009094 \n", + "\n", + "year 1994 1995 1996 \\\n", + "country \n", + "Albania 12423.667969 13408.305664 15897.171875 \n", + "Algeria 194623.453125 201560.718750 223520.937500 \n", + "Angola 29808.396484 29791.787109 42065.929688 \n", + "Anguilla 211.171829 202.151077 206.903473 \n", + "Antigua and Barbuda 947.404114 904.497864 950.093262 \n", + "\n", + "year 1997 1998 1999 \\\n", + "country \n", + "Albania 12886.214844 12879.900391 14811.457031 \n", + "Algeria 223795.171875 220101.734375 235706.593750 \n", + "Angola 37445.679688 43470.894531 40999.214844 \n", + "Anguilla 226.427460 261.738708 274.561401 \n", + "Antigua and Barbuda 1011.674438 1085.642700 1141.316284 \n", + "\n", + "year 2000 \n", + "country \n", + "Albania 15202.245117 \n", + "Algeria 292367.500000 \n", + "Angola 34137.144531 \n", + "Anguilla 275.259064 \n", + "Antigua and Barbuda 1182.556885 \n", + "\n", + "[5 rows x 31 columns]" + ] + }, + "execution_count": 9, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "Y_df, Z_df, X_df = load_dataset(\"pwt_spain_eu\", datasets_path=DATASETS_PATH)\n", + "\n", + "print(Y_df.shape, Z_df.shape, X_df.shape)\n", + "Y_df.head()\n" + ] + }, + { + "cell_type": "markdown", + "id": "9a89736b", + "metadata": {}, + "source": [ + "##### Effect of Trade Liberalization in Chile 1976" + ] + }, + { + "cell_type": "code", + "execution_count": 10, + "id": "80749e40", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "(111, 36) (111, 36) (111, 9)\n" + ] + }, + { + "data": { + "text/html": [ + "
\n", + "\n", + "\n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
year1960196119621963196419651966196719681969...1986198719881989199019911992199319941995
country
Algeria108244.14062595173.48437552905.28906260865.28906263954.38671969686.63281261610.58203169786.48437578230.18750085976.273438...232498.812500215471.062500194710.625000201886.734375213110.562500208132.890625206071.046875196900.218750197718.843750207264.703125
Argentina64673.57812566844.82812567655.26562565443.92187568879.07812577556.66406279047.07031281800.03125084209.66406292424.062500...163147.703125173890.609375184885.234375178384.078125199708.281250235515.265625277855.781250320473.875000372903.000000416118.812500
Australia147421.218750151806.828125160098.484375171474.812500179988.390625182392.375000194973.734375203872.703125219278.359375236060.640625...385013.000000417436.250000442874.000000458443.031250459148.718750459646.718750478489.281250496492.750000520231.062500549039.437500
Austria63902.94921967423.53125069297.47656272150.28906275660.67968878058.57031282049.54687584550.82031288224.21875092658.546875...147261.390625153703.625000163953.515625173181.687500183681.812500192484.171875201056.359375206013.796875216761.343750227580.296875
Bangladesh75697.08593875219.25781279701.10937585070.28125084589.89062583312.46093884111.78125081209.35937583826.07812587459.414062...118979.648438120109.031250125725.460938141489.187500148178.296875153358.093750157484.750000161486.921875169040.203125177051.921875
\n", + "

5 rows × 36 columns

\n", + "
" + ], + "text/plain": [ + "year 1960 1961 1962 1963 \\\n", + "country \n", + "Algeria 108244.140625 95173.484375 52905.289062 60865.289062 \n", + "Argentina 64673.578125 66844.828125 67655.265625 65443.921875 \n", + "Australia 147421.218750 151806.828125 160098.484375 171474.812500 \n", + "Austria 63902.949219 67423.531250 69297.476562 72150.289062 \n", + "Bangladesh 75697.085938 75219.257812 79701.109375 85070.281250 \n", + "\n", + "year 1964 1965 1966 1967 \\\n", + "country \n", + "Algeria 63954.386719 69686.632812 61610.582031 69786.484375 \n", + "Argentina 68879.078125 77556.664062 79047.070312 81800.031250 \n", + "Australia 179988.390625 182392.375000 194973.734375 203872.703125 \n", + "Austria 75660.679688 78058.570312 82049.546875 84550.820312 \n", + "Bangladesh 84589.890625 83312.460938 84111.781250 81209.359375 \n", + "\n", + "year 1968 1969 ... 1986 1987 \\\n", + "country ... \n", + "Algeria 78230.187500 85976.273438 ... 232498.812500 215471.062500 \n", + "Argentina 84209.664062 92424.062500 ... 163147.703125 173890.609375 \n", + "Australia 219278.359375 236060.640625 ... 385013.000000 417436.250000 \n", + "Austria 88224.218750 92658.546875 ... 147261.390625 153703.625000 \n", + "Bangladesh 83826.078125 87459.414062 ... 118979.648438 120109.031250 \n", + "\n", + "year 1988 1989 1990 1991 \\\n", + "country \n", + "Algeria 194710.625000 201886.734375 213110.562500 208132.890625 \n", + "Argentina 184885.234375 178384.078125 199708.281250 235515.265625 \n", + "Australia 442874.000000 458443.031250 459148.718750 459646.718750 \n", + "Austria 163953.515625 173181.687500 183681.812500 192484.171875 \n", + "Bangladesh 125725.460938 141489.187500 148178.296875 153358.093750 \n", + "\n", + "year 1992 1993 1994 1995 \n", + "country \n", + "Algeria 206071.046875 196900.218750 197718.843750 207264.703125 \n", + "Argentina 277855.781250 320473.875000 372903.000000 416118.812500 \n", + "Australia 478489.281250 496492.750000 520231.062500 549039.437500 \n", + "Austria 201056.359375 206013.796875 216761.343750 227580.296875 \n", + "Bangladesh 157484.750000 161486.921875 169040.203125 177051.921875 \n", + "\n", + "[5 rows x 36 columns]" + ] + }, + "execution_count": 10, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "Y_df, Z_df, X_df = load_dataset(\"pwt_chile_trade\", datasets_path=DATASETS_PATH)\n", + "\n", + "print(Y_df.shape, Z_df.shape, X_df.shape)\n", + "Y_df.head()\n" + ] + }, + { + "cell_type": "markdown", + "id": "19584649", + "metadata": {}, + "source": [ + "##### Effect of Democratization in Republic of Korea in 1988" + ] + }, + { + "cell_type": "code", + "execution_count": 11, + "id": "0e5a1ae2", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "(156, 31) (156, 31) (156, 7)\n" + ] + }, + { + "data": { + "text/html": [ + "
\n", + "\n", + "\n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
year1970197119721973197419751976197719781979...1991199219931994199519961997199819992000
country
Albania7195.1362307484.0708017785.1469738094.2226568422.0996098762.2919929096.4677739488.2451179868.45898410175.361328...10943.8486338529.64355510397.22070312423.66796913408.30566415897.17187512886.21484412879.90039114811.45703115202.245117
Algeria78035.45312576008.90625086169.73437594097.140625133679.859375128089.218750138225.078125151840.703125165145.125000192594.437500...217913.921875211870.812500198044.656250194623.453125201560.718750223520.937500223795.171875220101.734375235706.593750292367.500000
Angola29908.92773431722.32617231588.73242234156.40234435161.25781233603.02734431978.71289132063.10156230359.81054730061.013672...27015.67187530068.55078127618.68359429808.39648429791.78710942065.92968837445.67968843470.89453140999.21484434137.144531
Anguilla57.17253555.74837562.20414764.82572964.68508966.83895167.92566768.21097673.27482679.869453...150.204834188.016861193.979630211.171829202.151077206.903473226.427460261.738708274.561401275.259064
Antigua and Barbuda294.362762316.143463339.413971366.885284383.829620360.888519326.909241350.598480353.902130439.012634...811.863037832.927429894.009094947.404114904.497864950.0932621011.6744381085.6427001141.3162841182.556885
\n", + "

5 rows × 31 columns

\n", + "
" + ], + "text/plain": [ + "year 1970 1971 1972 1973 \\\n", + "country \n", + "Albania 7195.136230 7484.070801 7785.146973 8094.222656 \n", + "Algeria 78035.453125 76008.906250 86169.734375 94097.140625 \n", + "Angola 29908.927734 31722.326172 31588.732422 34156.402344 \n", + "Anguilla 57.172535 55.748375 62.204147 64.825729 \n", + "Antigua and Barbuda 294.362762 316.143463 339.413971 366.885284 \n", + "\n", + "year 1974 1975 1976 \\\n", + "country \n", + "Albania 8422.099609 8762.291992 9096.467773 \n", + "Algeria 133679.859375 128089.218750 138225.078125 \n", + "Angola 35161.257812 33603.027344 31978.712891 \n", + "Anguilla 64.685089 66.838951 67.925667 \n", + "Antigua and Barbuda 383.829620 360.888519 326.909241 \n", + "\n", + "year 1977 1978 1979 ... \\\n", + "country ... \n", + "Albania 9488.245117 9868.458984 10175.361328 ... \n", + "Algeria 151840.703125 165145.125000 192594.437500 ... \n", + "Angola 32063.101562 30359.810547 30061.013672 ... \n", + "Anguilla 68.210976 73.274826 79.869453 ... \n", + "Antigua and Barbuda 350.598480 353.902130 439.012634 ... \n", + "\n", + "year 1991 1992 1993 \\\n", + "country \n", + "Albania 10943.848633 8529.643555 10397.220703 \n", + "Algeria 217913.921875 211870.812500 198044.656250 \n", + "Angola 27015.671875 30068.550781 27618.683594 \n", + "Anguilla 150.204834 188.016861 193.979630 \n", + "Antigua and Barbuda 811.863037 832.927429 894.009094 \n", + "\n", + "year 1994 1995 1996 \\\n", + "country \n", + "Albania 12423.667969 13408.305664 15897.171875 \n", + "Algeria 194623.453125 201560.718750 223520.937500 \n", + "Angola 29808.396484 29791.787109 42065.929688 \n", + "Anguilla 211.171829 202.151077 206.903473 \n", + "Antigua and Barbuda 947.404114 904.497864 950.093262 \n", + "\n", + "year 1997 1998 1999 \\\n", + "country \n", + "Albania 12886.214844 12879.900391 14811.457031 \n", + "Algeria 223795.171875 220101.734375 235706.593750 \n", + "Angola 37445.679688 43470.894531 40999.214844 \n", + "Anguilla 226.427460 261.738708 274.561401 \n", + "Antigua and Barbuda 1011.674438 1085.642700 1141.316284 \n", + "\n", + "year 2000 \n", + "country \n", + "Albania 15202.245117 \n", + "Algeria 292367.500000 \n", + "Angola 34137.144531 \n", + "Anguilla 275.259064 \n", + "Antigua and Barbuda 1182.556885 \n", + "\n", + "[5 rows x 31 columns]" + ] + }, + "execution_count": 11, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "Y_df, Z_df, X_df = load_dataset(\"pwt_korea_democracy\", datasets_path=DATASETS_PATH)\n", + "\n", + "print(Y_df.shape, Z_df.shape, X_df.shape)\n", + "Y_df.head()\n" + ] + }, + { + "cell_type": "markdown", + "id": "25fd19da", + "metadata": {}, + "source": [ + "##### Resource Discovery: Norway 1971" + ] + }, + { + "cell_type": "code", + "execution_count": 12, + "id": "8384cb57", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "(111, 21) (111, 21) (111, 8)\n" + ] + }, + { + "data": { + "text/html": [ + "
\n", + "\n", + "\n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
year1960196119621963196419651966196719681969...1971197219731974197519761977197819791980
country
Algeria57859.01171952598.08593841043.75781249706.17968852888.89843857639.12109450519.28906258503.16796963260.29687568866.984375...76008.90625086169.73437594097.140625133679.859375128089.218750138225.078125151840.703125165145.125000192594.437500211956.031250
Argentina66006.76562569125.41406265920.74218865368.47656269836.62500080459.21093880040.85156283599.04687586008.75781293609.960938...99901.812500102289.156250108064.679688113038.726562111643.656250110320.273438114844.109375111297.921875121546.710938128656.695312
Australia148490.906250152266.343750161208.437500174909.515625182769.328125185704.812500198058.062500206108.390625222758.484375239781.453125...254754.093750267241.125000281354.312500272786.156250273733.375000285256.843750287133.843750302034.500000312480.343750322915.187500
Austria66254.42187570117.51562572212.85156275497.29687579308.44531282033.46093886199.98437588951.10937593062.77343897642.765625...108803.937500115845.101562122578.375000125235.554688125992.484375129840.906250135247.359375135275.656250140680.140625141431.765625
Bangladesh77779.47656277784.60156282569.39062587996.80468887750.57031286592.60937588017.16406285763.14062588174.63281291980.593750...97214.19531292048.44531277065.35937577225.92968873947.53125084864.66406288751.57812590830.05468896177.56250096436.890625
\n", + "

5 rows × 21 columns

\n", + "
" + ], + "text/plain": [ + "year 1960 1961 1962 1963 \\\n", + "country \n", + "Algeria 57859.011719 52598.085938 41043.757812 49706.179688 \n", + "Argentina 66006.765625 69125.414062 65920.742188 65368.476562 \n", + "Australia 148490.906250 152266.343750 161208.437500 174909.515625 \n", + "Austria 66254.421875 70117.515625 72212.851562 75497.296875 \n", + "Bangladesh 77779.476562 77784.601562 82569.390625 87996.804688 \n", + "\n", + "year 1964 1965 1966 1967 \\\n", + "country \n", + "Algeria 52888.898438 57639.121094 50519.289062 58503.167969 \n", + "Argentina 69836.625000 80459.210938 80040.851562 83599.046875 \n", + "Australia 182769.328125 185704.812500 198058.062500 206108.390625 \n", + "Austria 79308.445312 82033.460938 86199.984375 88951.109375 \n", + "Bangladesh 87750.570312 86592.609375 88017.164062 85763.140625 \n", + "\n", + "year 1968 1969 ... 1971 1972 \\\n", + "country ... \n", + "Algeria 63260.296875 68866.984375 ... 76008.906250 86169.734375 \n", + "Argentina 86008.757812 93609.960938 ... 99901.812500 102289.156250 \n", + "Australia 222758.484375 239781.453125 ... 254754.093750 267241.125000 \n", + "Austria 93062.773438 97642.765625 ... 108803.937500 115845.101562 \n", + "Bangladesh 88174.632812 91980.593750 ... 97214.195312 92048.445312 \n", + "\n", + "year 1973 1974 1975 1976 \\\n", + "country \n", + "Algeria 94097.140625 133679.859375 128089.218750 138225.078125 \n", + "Argentina 108064.679688 113038.726562 111643.656250 110320.273438 \n", + "Australia 281354.312500 272786.156250 273733.375000 285256.843750 \n", + "Austria 122578.375000 125235.554688 125992.484375 129840.906250 \n", + "Bangladesh 77065.359375 77225.929688 73947.531250 84864.664062 \n", + "\n", + "year 1977 1978 1979 1980 \n", + "country \n", + "Algeria 151840.703125 165145.125000 192594.437500 211956.031250 \n", + "Argentina 114844.109375 111297.921875 121546.710938 128656.695312 \n", + "Australia 287133.843750 302034.500000 312480.343750 322915.187500 \n", + "Austria 135247.359375 135275.656250 140680.140625 141431.765625 \n", + "Bangladesh 88751.578125 90830.054688 96177.562500 96436.890625 \n", + "\n", + "[5 rows x 21 columns]" + ] + }, + "execution_count": 12, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "Y_df, Z_df, X_df = load_dataset(\"pwt_norway_oil\", datasets_path=DATASETS_PATH)\n", + "\n", + "print(Y_df.shape, Z_df.shape, X_df.shape)\n", + "Y_df.head()\n" + ] + }, + { + "cell_type": "markdown", + "id": "8f6a3ed0", + "metadata": {}, + "source": [ + "### Retailrocket Recsys Dataset" + ] + }, + { + "cell_type": "code", + "execution_count": 13, + "id": "f702fe99", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "(19780, 139) None None\n" + ] + }, + { + "data": { + "text/html": [ + "
\n", + "\n", + "\n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
day0123456789...129130131132133134135136137138
itemid
60.00.00.02.00.00.00.00.00.00.0...0.00.00.00.00.00.00.00.00.00.0
250.00.00.00.00.01.00.00.01.02.0...0.00.01.01.00.00.00.00.00.00.0
321.00.00.02.01.00.01.01.00.00.0...0.00.00.01.04.01.00.00.00.00.0
421.00.00.02.01.00.00.00.00.00.0...0.00.00.00.00.00.00.00.00.00.0
1351.00.01.00.00.00.00.00.00.00.0...0.00.00.02.00.00.00.00.00.00.0
\n", + "

5 rows × 139 columns

\n", + "
" + ], + "text/plain": [ + "day 0 1 2 3 4 5 6 7 8 9 ... 129 130 131 \\\n", + "itemid ... \n", + "6 0.0 0.0 0.0 2.0 0.0 0.0 0.0 0.0 0.0 0.0 ... 0.0 0.0 0.0 \n", + "25 0.0 0.0 0.0 0.0 0.0 1.0 0.0 0.0 1.0 2.0 ... 0.0 0.0 1.0 \n", + "32 1.0 0.0 0.0 2.0 1.0 0.0 1.0 1.0 0.0 0.0 ... 0.0 0.0 0.0 \n", + "42 1.0 0.0 0.0 2.0 1.0 0.0 0.0 0.0 0.0 0.0 ... 0.0 0.0 0.0 \n", + "135 1.0 0.0 1.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 ... 0.0 0.0 0.0 \n", + "\n", + "day 132 133 134 135 136 137 138 \n", + "itemid \n", + "6 0.0 0.0 0.0 0.0 0.0 0.0 0.0 \n", + "25 1.0 0.0 0.0 0.0 0.0 0.0 0.0 \n", + "32 1.0 4.0 1.0 0.0 0.0 0.0 0.0 \n", + "42 0.0 0.0 0.0 0.0 0.0 0.0 0.0 \n", + "135 2.0 0.0 0.0 0.0 0.0 0.0 0.0 \n", + "\n", + "[5 rows x 139 columns]" + ] + }, + "execution_count": 13, + "metadata": {}, + "output_type": "execute_result" } ], "source": [ - "df1 = df[(df['year'] >= 1970) & (df['year'] <= 2000)]\n", - "\n", - "\n", - "Y_df = create_y_dataframe(df1, index_col=\"country\", column_col=\"year\", value_col=\"rgdpe\")\n", + "Y_df, Z_df, X_df = load_dataset(\"retailrocket\", datasets_path=DATASETS_PATH)\n", "\n", - "\n", - "Z_df = create_z_dataframe(Y_df, treated_entity='Republic of Korea', treatment_start_year=1988)\n", - "\n", - "cols_to_avg = [\"hc\",\"csh_i\",\"csh_g\",\"openness\",\"ctfp\"]\n", - "\n", - "X_df = create_x_dataframe(\n", - " df1, Y_df,\n", - " index_col='country',\n", - " time_col='year',\n", - " covariate_cols=cols_to_avg,\n", - " avg_start_year=1980,\n", - " avg_end_year=1987,\n", - " additional_cols={'rgdpe1980': 1980, 'rgdpe1988': 1985}\n", - ")" + "print(Y_df.shape, Z_df, X_df)\n", + "Y_df.head()\n" ] }, { "cell_type": "markdown", - "id": "25fd19da", + "id": "a484ddb3", "metadata": {}, "source": [ - "##### Resource Discovery: Norway 1971" + "### Dunnhumby Recsys Dataset" ] }, { "cell_type": "code", - "execution_count": 26, - "id": "8384cb57", + "execution_count": 14, + "id": "d940c477", "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ - "Removed 71 entities (39.0%) with NaN values, losing 1491/3822 data points (39.0%)\n" + "(19002, 692) (19002, 692) None\n" ] - } - ], - "source": [ - "df1 = df[(df['year'] >= 1960) & (df['year'] <= 1980)]\n", - "\n", - "\n", - "Y_df = create_y_dataframe(df1, index_col=\"country\", column_col=\"year\", value_col=\"rgdpe\")\n", - "\n", - "\n", - "Z_df = create_z_dataframe(Y_df, treated_entity='Norway', treatment_start_year=1971)\n", - "\n", - "cols_to_avg = [\"hc\",\"csh_i\",\"csh_g\",\"openness\",\"rkna\",\"pl_gdpo\"]\n", - "\n", - "X_df = create_x_dataframe(\n", - " df1, Y_df,\n", - " index_col='country',\n", - " time_col='year',\n", - " covariate_cols=cols_to_avg,\n", - " avg_start_year=1960,\n", - " avg_end_year=1970,\n", - " additional_cols={'rgdpe1965': 1965, 'rgdpe1970': 1970}\n", - ")" - ] - }, - { - "cell_type": "markdown", - "id": "8f6a3ed0", - "metadata": {}, - "source": [ - "### Retailrocket Recsys Dataset" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "f702fe99", - "metadata": {}, - "outputs": [], - "source": [ - "df = pd.read_csv('../src/causaltensor/datasets/raw/retailrocket.csv', engine=\"python\", sep=None)\n", - "df = df[df['event'] == 'view']\n", - "df['date'] = pd.to_datetime(df['timestamp'], unit='ms').dt.date\n", - "df['day'] = pd.to_numeric(df['date'].astype('category').cat.codes)\n", - "pop_items = df.groupby('itemid')['day'].nunique() > 20\n", - "items_to_keep = pop_items[pop_items].index\n", - "df = df[df['itemid'].isin(items_to_keep)]\n", - "df = df[['visitorid', 'itemid', 'day']]\n", - "df.to_csv('../src/causaltensor/datasets/raw/retailrocket_filtered.csv', index=False)\n", - "df = df.groupby(['itemid', 'day']).size().reset_index(name='count')\n", - "Y_df = create_y_dataframe(df, index_col=\"itemid\", column_col=\"day\", value_col=\"count\").fillna(0)" - ] - }, - { - "cell_type": "markdown", - "id": "a484ddb3", - "metadata": {}, - "source": [ - "### Dunnhumby Recsys Dataset" - ] - }, - { - "cell_type": "code", - "execution_count": 14, - "id": "d940c477", - "metadata": {}, - "outputs": [], - "source": [ - "df = pd.read_csv('../src/causaltensor/datasets/raw/dunnhumby.csv', engine=\"python\", sep=None)\n", - "df = df[df['STORE_ID'] == 367] # filter to most popular store\n", - "df = df.groupby(['PRODUCT_ID', 'DAY'])[['SALES_VALUE', 'RETAIL_DISC']].sum().reset_index()\n", - "df['PROMO'] = (df['RETAIL_DISC'] < 0).astype(int) # Use retail discount as treatment proxy\n", - "df.to_csv('../src/causaltensor/datasets/raw/dunnhumby_filtered.csv', index=False)\n", - "Y_df = create_y_dataframe(df, index_col=\"PRODUCT_ID\", column_col=\"DAY\", value_col=\"SALES_VALUE\").fillna(0)\n", - "Z_df = create_y_dataframe(df, index_col=\"PRODUCT_ID\", column_col=\"DAY\", value_col=\"PROMO\").fillna(0)" - ] - }, - { - "cell_type": "markdown", - "id": "04897490", - "metadata": {}, - "source": [ - "### Truus Recsys Dataset" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "7deba728", - "metadata": {}, - "outputs": [ + }, { "data": { "text/html": [ @@ -985,31 +2528,31 @@ "\n", " \n", " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", " \n", " \n", - " \n", + " \n", " \n", " \n", " \n", @@ -1035,16 +2578,16 @@ " \n", " \n", " \n", - " \n", - " \n", - " \n", + " \n", " \n", " \n", " \n", " \n", " \n", " \n", + " \n", " \n", + " \n", " \n", " \n", " \n", @@ -1059,16 +2602,16 @@ " \n", " \n", " \n", - " \n", - " \n", - " \n", + " \n", " \n", " \n", " \n", " \n", " \n", " \n", + " \n", " \n", + " \n", " \n", " \n", " \n", @@ -1083,46 +2626,46 @@ " \n", " \n", " \n", - " \n", + " \n", " \n", " \n", " \n", " \n", " \n", " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", " \n", " \n", " \n", " \n", - " \n", " \n", - " \n", " \n", - " \n", " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", " \n", " \n", + " \n", + " \n", + " \n", " \n", " \n", " \n", " \n", " \n", " \n", + " \n", " \n", + " \n", " \n", " \n", " \n", " \n", " \n", - " \n", + " \n", " \n", " \n", " \n", @@ -1131,55 +2674,158 @@ " \n", " \n", " \n", - " \n", + " \n", " \n", " \n", " \n", " \n", " \n", " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", " \n", " \n", " \n", " \n", - " \n", - " \n", " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", " \n", " \n", " \n", - " \n", + " \n", + "
day734473734474734475734476734477734479734481734482734483734484DAY34511121314151617...734938734939734940734941734942734943734944734945734946734947702703704705706707708709710711
sku_idPRODUCT_ID
10.00.08189800.00.00.00.00.00.00.790.00.000.0...0.00.0
20.00.08189810.00.00.00.00.00.00.000.00.000.0...0.00.0
38190630.00.00.00.00.00.00.000.01.750.0...0.00.00.00.00.0...0.02.00.01.00.01.01.01.01.01.0
40.00.0
8191150.00.00.00.00.00.00.000.00.000.0...0.00.00.01.00.00.00.00.00.0
58192100.00.00.00.00.00.00.000.00.000.0...0.00.00.00.00.00.00.0...1.00.01.01.01.01.03.03.00.00.0
\n", + "

5 rows × 692 columns

\n", + "" + ], + "text/plain": [ + "DAY 3 4 5 11 12 13 14 15 16 17 ... 702 703 \\\n", + "PRODUCT_ID ... \n", + "818980 0.0 0.0 0.0 0.0 0.0 0.0 0.79 0.0 0.00 0.0 ... 0.0 0.0 \n", + "818981 0.0 0.0 0.0 0.0 0.0 0.0 0.00 0.0 0.00 0.0 ... 0.0 0.0 \n", + "819063 0.0 0.0 0.0 0.0 0.0 0.0 0.00 0.0 1.75 0.0 ... 0.0 0.0 \n", + "819115 0.0 0.0 0.0 0.0 0.0 0.0 0.00 0.0 0.00 0.0 ... 0.0 0.0 \n", + "819210 0.0 0.0 0.0 0.0 0.0 0.0 0.00 0.0 0.00 0.0 ... 0.0 0.0 \n", + "\n", + "DAY 704 705 706 707 708 709 710 711 \n", + "PRODUCT_ID \n", + "818980 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 \n", + "818981 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 \n", + "819063 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 \n", + "819115 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 \n", + "819210 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 \n", + "\n", + "[5 rows x 692 columns]" + ] + }, + "execution_count": 14, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "Y_df, Z_df, X_df = load_dataset(\"dunnhumby\", datasets_path=DATASETS_PATH)\n", + "\n", + "print(Y_df.shape, Z_df.shape, X_df)\n", + "Y_df.head()\n" + ] + }, + { + "cell_type": "markdown", + "id": "04897490", + "metadata": {}, + "source": [ + "### Truus Recsys Dataset" + ] + }, + { + "cell_type": "code", + "execution_count": 15, + "id": "7deba728", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "(394, 447) None None\n" + ] + }, + { + "data": { + "text/html": [ + "
\n", + "\n", + "\n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", " \n", + " \n", + " \n", " \n", - " \n", + " \n", " \n", " \n", " \n", @@ -1197,13 +2843,13 @@ " \n", " \n", " \n", - " \n", + " \n", " \n", " \n", " \n", " \n", " \n", - " \n", + " \n", " \n", " \n", " \n", @@ -1227,7 +2873,7 @@ " \n", " \n", " \n", - " \n", + " \n", " \n", " \n", " \n", @@ -1240,20 +2886,20 @@ " \n", " \n", " \n", + " \n", " \n", + " \n", " \n", - " \n", - " \n", - " \n", - " \n", - " \n", + " \n", + " \n", + " \n", " \n", " \n", " \n", " \n", - " \n", + " \n", + " \n", " \n", - " \n", " \n", " \n", " \n", @@ -1275,7 +2921,7 @@ " \n", " \n", " \n", - " \n", + " \n", " \n", " \n", " \n", @@ -1287,20 +2933,20 @@ " \n", " \n", " \n", - " \n", " \n", " \n", - " \n", - " \n", - " \n", - " \n", - " \n", " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", " \n", " \n", " \n", "
day734473734474734475734476734477734479734481734482734483734484..................................................................734938734939734940734941734942734943734944734945734946734947
sku_id
39010.00.00.00.00.00.02.00.00.00.00.0
39120.00.00.00.0
39230.00.00.00.0...0.02.00.01.00.00.00.00.00.00.01.01.01.01.01.0
39340.00.01.00.00.00.00.0
39450.00.00.00.00.0...0.01.00.00.00.00.00.00.01.01.01.01.03.03.00.00.0
\n", - "

394 rows × 447 columns

\n", + "

5 rows × 447 columns

\n", "
" ], "text/plain": [ @@ -1311,12 +2957,6 @@ "3 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 \n", "4 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 \n", "5 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 \n", - "... ... ... ... ... ... ... ... ... \n", - "390 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 \n", - "391 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 \n", - "392 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 \n", - "393 0.0 1.0 0.0 0.0 0.0 0.0 0.0 0.0 \n", - "394 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 \n", "\n", "day 734483 734484 ... 734938 734939 734940 734941 734942 734943 \\\n", "sku_id ... \n", @@ -1325,12 +2965,6 @@ "3 0.0 0.0 ... 0.0 2.0 0.0 1.0 0.0 1.0 \n", "4 0.0 0.0 ... 0.0 0.0 0.0 1.0 0.0 0.0 \n", "5 0.0 0.0 ... 1.0 0.0 1.0 1.0 1.0 1.0 \n", - "... ... ... ... ... ... ... ... ... ... \n", - "390 0.0 0.0 ... 0.0 0.0 0.0 0.0 0.0 0.0 \n", - "391 0.0 0.0 ... 0.0 0.0 0.0 0.0 0.0 0.0 \n", - "392 0.0 0.0 ... 0.0 0.0 0.0 0.0 0.0 0.0 \n", - "393 0.0 0.0 ... 0.0 0.0 0.0 1.0 0.0 0.0 \n", - "394 0.0 0.0 ... 0.0 1.0 0.0 0.0 0.0 0.0 \n", "\n", "day 734944 734945 734946 734947 \n", "sku_id \n", @@ -1339,26 +2973,20 @@ "3 1.0 1.0 1.0 1.0 \n", "4 0.0 0.0 0.0 0.0 \n", "5 3.0 3.0 0.0 0.0 \n", - "... ... ... ... ... \n", - "390 2.0 0.0 0.0 0.0 \n", - "391 0.0 0.0 0.0 0.0 \n", - "392 0.0 0.0 1.0 1.0 \n", - "393 0.0 0.0 0.0 0.0 \n", - "394 0.0 0.0 1.0 0.0 \n", - "\n", - "[394 rows x 447 columns]" + "\n", + "[5 rows x 447 columns]" ] }, - "execution_count": 8, + "execution_count": 15, "metadata": {}, "output_type": "execute_result" } ], "source": [ - "df = pd.read_csv('../src/causaltensor/datasets/raw/truus.csv', engine=\"python\", sep=None)\n", - "df = df.groupby(['sku_id', 'day']).size().reset_index(name='count')\n", - "Y_df = create_y_dataframe(df, index_col=\"sku_id\", column_col=\"day\", value_col=\"count\").fillna(0)\n", - "Y_df" + "Y_df, Z_df, X_df = load_dataset(\"truus\", datasets_path=DATASETS_PATH)\n", + "\n", + "print(Y_df.shape, Z_df, X_df)\n", + "Y_df.head()\n" ] }, { @@ -1371,31 +2999,255 @@ }, { "cell_type": "code", - "execution_count": null, + "execution_count": 16, "id": "82c0647a", "metadata": {}, - "outputs": [], + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "(1682, 213) None None\n" + ] + }, + { + "data": { + "text/html": [ + "
\n", + "\n", + "\n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
day0123456789...203204205206207208209210211212
movie_id
13.06.04.01.02.03.06.05.01.02.0...1.03.03.02.04.00.00.01.01.02.0
22.01.00.00.01.00.02.01.00.01.0...0.00.00.00.02.00.01.01.01.00.0
31.02.00.00.01.00.03.01.00.00.0...0.00.00.00.03.00.00.00.00.00.0
44.02.02.01.01.00.05.03.01.00.0...0.00.00.00.02.00.00.01.01.01.0
51.02.01.00.01.00.02.02.00.00.0...0.00.00.00.01.01.00.00.01.00.0
\n", + "

5 rows × 213 columns

\n", + "
" + ], + "text/plain": [ + "day 0 1 2 3 4 5 6 7 8 9 ... 203 204 \\\n", + "movie_id ... \n", + "1 3.0 6.0 4.0 1.0 2.0 3.0 6.0 5.0 1.0 2.0 ... 1.0 3.0 \n", + "2 2.0 1.0 0.0 0.0 1.0 0.0 2.0 1.0 0.0 1.0 ... 0.0 0.0 \n", + "3 1.0 2.0 0.0 0.0 1.0 0.0 3.0 1.0 0.0 0.0 ... 0.0 0.0 \n", + "4 4.0 2.0 2.0 1.0 1.0 0.0 5.0 3.0 1.0 0.0 ... 0.0 0.0 \n", + "5 1.0 2.0 1.0 0.0 1.0 0.0 2.0 2.0 0.0 0.0 ... 0.0 0.0 \n", + "\n", + "day 205 206 207 208 209 210 211 212 \n", + "movie_id \n", + "1 3.0 2.0 4.0 0.0 0.0 1.0 1.0 2.0 \n", + "2 0.0 0.0 2.0 0.0 1.0 1.0 1.0 0.0 \n", + "3 0.0 0.0 3.0 0.0 0.0 0.0 0.0 0.0 \n", + "4 0.0 0.0 2.0 0.0 0.0 1.0 1.0 1.0 \n", + "5 0.0 0.0 1.0 1.0 0.0 0.0 1.0 0.0 \n", + "\n", + "[5 rows x 213 columns]" + ] + }, + "execution_count": 16, + "metadata": {}, + "output_type": "execute_result" + } + ], "source": [ - "df = pd.read_csv('../src/causaltensor/datasets/raw/movielens.data', sep='\\t', header=None, \n", - " names=['user_id', 'movie_id', 'rating', 'timestamp'])\n", - "df['date'] = pd.to_datetime(df['timestamp'], unit='s').dt.date\n", - "df['day'] = pd.to_numeric(df['date'].astype('category').cat.codes)\n", - "df = df.groupby(['movie_id', 'day']).size().reset_index(name='count')\n", - "Y_df = create_y_dataframe(df, index_col=\"movie_id\", column_col=\"day\", value_col=\"count\").fillna(0)" + "Y_df, Z_df, X_df = load_dataset(\"movielens\", datasets_path=DATASETS_PATH)\n", + "\n", + "print(Y_df.shape, Z_df, X_df)\n", + "Y_df.head()\n" ] }, { - "cell_type": "code", - "execution_count": null, + "cell_type": "markdown", "id": "59bd6427", "metadata": {}, - "outputs": [], - "source": [] + "source": [ + "For custom raw datasets, keep using the shared helpers imported above (`create_y_dataframe`, `create_z_dataframe`, and `create_x_dataframe`) rather than copying their definitions into the notebook.\n" + ] } ], "metadata": { "kernelspec": { - "display_name": "Python 3", + "display_name": ".venv", "language": "python", "name": "python3" }, @@ -1409,7 +3261,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.10.8" + "version": "3.13.5" } }, "nbformat": 4,