pici 0.0.1

Package for Partially Identifiable Causal Inference

PICI -- Partially Identifiable Causal Inference

Table of Contents

1. About
2. Usage
   • Install and Import
   • Causal Model Creation
   • Identifiability Checker
   • Interventional Query
   • PN & PS Approximations
3. Theory
4. Developer Tools
   • Install
   • Virtual Environment
   • Running Examples
   • Linters
     • Black
     • Ruff
5. Acknowledgements

About

PICI stands for Partially Identifiable Causal Inference. It is a causal inference package that can handle discrete Partially Identifiable Queries in Quasi-Markovian Structural Causal Models.

This project was based on the work of João Pedro Arroyo and João Gabriel on GitHub.

Usage

Install and import

• Install the package

pip install pici

• Import the package

import pici

Causal model creation

• Create a causal model:

df = pd.read_csv(model_csv_path)
edges = "Z -> X, X -> Y, U1 -> X, U1 -> Y, U2 -> Z"
unobservable_variables = ["U1", "U2"]
custom_cardinalities = {"Z": 5, "X": 2, "Y": 16, "U1": 0, "U2": 0}
interventions=[('X',0)]
target=('Y',0)

model = pici.CausalModel(
  data=df,
  edges=edges,
  custom_cardinalities=custom_cardinalities,
  unobservables_labels=unobservable_variables,
  interventions=interventions,    # Optional in the model creation
  target=target,                  # Optional in the model creation
)

• You can set target and intervetions:

model.set_interventions([('X', 1)])
model.set_target(('Y', 1))

Indentifiability checker

• You can check if your intervention is identifiable by Backdoor criterion, Frontdoor criterion or ID algorithm:

edges = "U1 -> X, U1 -> Y, X -> W, W -> Y, U2 -> W"
unobservables_labels=["U1", "U2"]

model = CausalModel(
    data=df,
    edges=edges,
    unobservables_labels=unobservables_labels
)

is_identifiable, identifiable_method, additional_detail = model.is_identifiable_intervention(
    interventions=[("X", 0)], target=("Y", 1)
)

Interventional query

• You can make the query.

model.intervention_query()

Or you can pass the target and intervention as arguments:

model.intervention_query([('X', 1)], ('Y', 1))

• When intervention_query is called, it is automatically checked if your query is identifiable or partially identifiable.
• If your query is identifiable, the return value is a string.

exact_value = model.intervention_query()

• If your query is partially identifiable, the return value is a tuple of strings.

lower_bound, upper_bound = model.intervention_query()

PN and PS approximations

• You can make a PN and a PS approximation, that we called weak-pn and weak-ps. This approximation is based on the paper Laurentino et. al., 2025 (public link soon).

The same way as the intervention_query, if it's identifiable it will return a string otherwise a tuple of strings.

pn_value = model.weak_pn_inference(intervention_label='X', target_label='Y')
ps_value = model.weak_ps_inference(intervention_label='X', target_label='Y')

Theory behind

If you want to understand what is the theory of our approach, you can read the paper Arroyo et al., 2025.

Developer tools

All development tools are managed with Poetry.
To get started, install Poetry by following the official instructions, then activate the virtual environment.

Install

• Install dependencies. Once you have installed poetry, you can install the required packages:

poetry install

Virtual Environment

Activate the virtual environment:

• Activate poetry virtual environment

eval $(poetry env activate)

• To exit the poetry virtual environment run:

deactivate

Running Examples

Example:

python3 examples/example.py

• You also can run unit tests:

python3 tests/run_all_tests.py

Linters

This project uses some linters to follow a code standardization that improves code consistency and cleanliness.

Ruff

This project uses Ruff to remove unused imports and sort them.

Usage example for a file:

ruff check your_file.py --fix -s

For all files in the current directory and sub-directories:

ruff check . --fix -s

Running this command will change automatically. We suggest the use of flag -s to silence the countless print logs.

Black

This project uses Black for automatic Python code formatting. Black is an code formatter that ensures consistency by enforcing a uniform style.

Usage example for a file:

black your_file.py

For all files in the current directory and sub-directories:

black .

Running this command will change automatically.

Acknowledgements

We thank the ICTi, Instituto de Ciência e Tecnologia Itaú, for providing key funding for this work through the C2D - Centro de Ciência de Dados at Universidade de São Paulo.

Any opinions, findings, conclusions or recommendations expressed in this material are those of the authors and do not necessarily reflect the views of Itaú Unibanco and Instituto de Ciência e Tecnologia Itaú. All data used in this study comply with the Brazilian General Data Protection Law.