Skip to main content

Setup & installation

This page gets your machine ready to run the toolkit: download the code, install Python 3.8+ and the required packages, and open the project in your editor. Once done, continue to Preparing your data.

One thing to get right The toolkit lives several levels deep in the repository, at examples/utility-python/causal-inference/copilot-causal-toolkit. Throughout setup, your working directory is that copilot-causal-toolkit folder — not the repository root. Opening the wrong folder is the most common cause of broken file paths later.

Step 1 — Get a copy of the toolkit

  1. Click the green Code button at the top of the repository.
  2. Select Download ZIP.
  3. Extract the ZIP to a location on your computer, e.g. C:\Users\YourName\Documents\viva-insights-sample-code.

  4. Navigate into the toolkit subdirectory:

    examples/utility-python/causal-inference/copilot-causal-toolkit

    For the example above, the full path would be:

    C:\Users\YourName\Documents\viva-insights-sample-code\examples\utility-python\causal-inference\copilot-causal-toolkit

git clone https://github.com/microsoft/viva-insights-sample-code.git
cd viva-insights-sample-code/examples/utility-python/causal-inference/copilot-causal-toolkit

Step 2 — Open the project in your editor

We recommend Visual Studio Code with the Python and Jupyter extensions.

  1. Open VS Code → File → Open Folder…
  2. Select the copilot-causal-toolkit folder itself (the one containing data/, script/, and output/).
  3. VS Code now shows the toolkit structure in the sidebar.

Opening the toolkit folder directly — rather than the parent repository — keeps all the relative file paths in the notebooks working.

What's inside the folder? 
copilot-causal-toolkit/
├── data/                 # Place your CSV exports here (Person Query or Super Users Report)
├── script/               # The five analysis notebooks
│   ├── CI-DML_AftCollabHours_PQ.ipynb / _SUR.ipynb
│   ├── CI-DML_ExtCollabHours_PQ.ipynb / _SUR.ipynb
│   ├── CI-DML_Engagement_PQ.ipynb
│   └── modules/          # Reusable helpers: data_processor, estimator,
│                         #   subgroup_analysis, sensitivity_analysis, visualizations …
├── output/               # Results, plots, and reports are written here
└── README.md
  • data/ — your Viva Insights exports (CSV).
  • script/ — the Jupyter notebooks you run.
  • script/modules/ — Python modules with the analysis functions.
  • output/ — all generated tables, plots, and HTML reports.

We recommend making a copy of the notebook you intend to use and renaming it to match your analysis (e.g. CI-DML_AftCollabHours_PQ - Contoso.ipynb).

Step 3 — Install the prerequisites

Python 3.8 or higher

Check whether Python is already installed:

python --version

If it’s missing or too old, download it from python.org. During installation, tick “Add Python to PATH”.

Jupyter

Jupyter runs the .ipynb notebooks interactively:

pip install jupyter

Alternatively, use VS Code with the Python and Jupyter extensions for a more integrated experience.

Required Python packages

A requirements.txt is provided in the toolkit directory. From the copilot-causal-toolkit folder:

pip install -r requirements.txt
Prefer to install packages individually? 
pip install numpy pandas matplotlib scipy scikit-learn econml vivainsights jupyter
Package Purpose
numpy, pandas Data manipulation and numerical computing
matplotlib Plots and visualizations
scipy Statistical functions and tests
scikit-learn ML models and preprocessing
econml Causal inference (Double Machine Learning)
vivainsights Viva Insights data loading and analysis
jupyter Running notebooks interactively

Installation time: roughly 5–10 minutes depending on your connection.

Installing for a specific Python environment

If you have multiple Python versions installed, target a specific one:

# Using the py launcher (Windows)
py -3.11 -m pip install -r requirements.txt

# Using the full path to a specific Python executable
C:\Path\To\Python\python.exe -m pip install -r requirements.txt

# For a virtual environment (after creating it)
C:\Path\To\venv\Scripts\python.exe -m pip install -r requirements.txt

# For conda environments
conda run -n <env_name> pip install -r requirements.txt

To check which Python you’re currently using:

python -c "import sys; print(sys.executable)"

Verify the installation

python -c "import numpy, pandas, matplotlib, scipy, sklearn, econml, vivainsights"

If this runs without error, you’re ready. You can run it in a terminal or a notebook cell.

If install or import fails (numpy / econml)

The most common failure is a numpy version clash: econml (the causal-inference engine) is not compatible with numpy 2.x, so a fresh install can fail at import econml. If you see numpy- or econml-related errors, pin numpy to the 1.x line and reinstall:

pip install "numpy<2.0"
pip install --force-reinstall econml

A clean virtual environment avoids clashes with other projects. On Windows, if econml fails to build, install the Microsoft C++ Build Tools and retry. Installing econml can take several minutes — let it finish.

Recommended: use a virtual environment

A virtual environment avoids package conflicts. Run these from the copilot-causal-toolkit directory:

python -m venv venv
venv\Scripts\activate
pip install -r requirements.txt

python -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Next With your environment ready, head to Preparing your data to export the right columns for your scenario.

Last updated: Jun 22, 2026 Edit this page on GitHub