1. Motivation

A recurring problem across many domains is measuring the relative importance of one feature within a large group, and then determining whether that localized feature influences its environment macroscopically. The question is not merely which features are important in aggregate, but whether a small component of a complex system — when perturbed — produces changes that propagate outward in meaningful ways. This kind of reasoning sits at the intersection of local attribution and global causal inference, and it is rarely addressed well by standard feature-importance pipelines.

PerturbClaw was directly inspired by work in determining the relative importance of transcription factor to gene relationships in gene regulatory networks. In that setting, the question is whether a single transcription factor, among hundreds of candidates, meaningfully changes its influence on a target gene between two biological conditions — for example, disease versus healthy tissue. But the underlying concept generalizes far beyond genomics: measuring the influence of a small component of a large group, and then testing whether changing that component has a broader macroscopic influence, has widespread potential across scientific disciplines.

Inspired by work from Dibaeinia et al. (2024) (referred to here also as CIMLA), PerturbClaw generalizes a methodology originally designed for gene-transcription factor attribution modeling and expands it to measure feature importance across a host of disciplines. Given data from two conditions (e.g. disease vs. control, treated vs. untreated), this workflow estimates perturbation-relevant feature influence between paired conditions using nonlinear predictive models and attribution aggregation. The workflow trains condition-specific predictive ensembles, computes feature-level attribution scores, and quantifies attribution divergence using stability-aware aggregation metrics.

Under the assumptions described in Dibaeinia et al. (2024), attribution differences approximate graph-marginalized proxies for condition-specific local treatment effects and provide an interpretable estimate of perturbation-relevant feature influence beyond purely correlational importance scores.

Concrete domains where this question arises include:

• Genomics: regulatory influence may differ between disease and control conditions; identifying which transcription factors changed their influence on target genes is a core unsolved problem
• Neuroscience: stimulus conditions may alter which features of neural activity are most relevant to a behavioral outcome
• Climate modeling: relationships between atmospheric variables and regional outcomes shift across eras, and identifying which variables changed their predictive role is essential for attribution
• Materials science: processing conditions change which material properties most strongly predict performance outcomes

Static feature-importance pipelines are often insufficient for all of these settings. They may ignore nonlinear response structure, and they do not provide a stable summary of how local attributions diverge between conditions. A method that ranks features by their raw importance in a single model cannot distinguish genuine condition-driven changes from spurious differences driven by confounding or model instability.

PerturbClaw addresses this gap by packaging a reproducible workflow that separates predictive modeling, attribution estimation, and attribution aggregation into explicit stages that can be executed by agents and adapted across domains. PerturbClaw implements a domain-independent workflow template for estimating perturbation-relevant feature influence under partially observed causal structure. The workflow separates these stages into independent reproducible components, allowing substitution of model classes, attribution methods, and aggregation metrics across scientific domains.

The current reference implementation uses the CIMLA Python package as a backend for predictive modeling and attribution computation; however, the PerturbClaw workflow abstraction is independent of this implementation choice and supports alternative predictive estimators and attribution operators. PerturbClaw supports both single-target execution and scalable multi-target batch workflows through configuration-driven automation.

2. Method

Attribution grounding

Let $\mathbf{X} = {X_1, \ldots, X_m}$ be input features and $Y_g$ be the target output. Under the assumptions described in Dibaeinia et al. (2024), local SHAP values can be interpreted as graph-marginalized proxies for condition-specific local treatment effects. This motivates comparing feature-level attributions between two condition-specific predictive models evaluated on a shared set of samples.

For feature $t$ and target $g$, define a condition-specific local treatment effect proxy at state $\mathbf{x}$ as:

$$\mathrm{LTE}$${t,g}(\mathbf{x}) = E!\left[Y_g \mid \mathrm{do}(X_t = x_t),, \mathrm{do}(\mathbf{X}{-t} = \mathbf{x}{-t})\right] - E!\left[Y_g \mid \mathrm{do}(X_t = \hat{x}t),, \mathrm{do}(\mathbf{X}{-t} = \mathbf{x}{-t})\right]

The reference implementation follows the theorem of Dibaeinia et al. (2024), under which the SHAP value $\phi_t(f, \mathbf{x})$ approximates a graph-marginalized, baseline-averaged proxy:

$$\phi_t(f, \mathbf{x}) = \alpha_{t,g}(\mathbf{x}) = E_{\hat{x}$$t,,\psi}!\left[\mathrm{LTE}{t,g}(\mathbf{x},, \hat{x}_t,, \psi)\right]

This interpretation is approximate and assumption-dependent, but it provides a useful scientific rationale for comparing attribution structure between conditions.

The PerturbClaw workflow

PerturbClaw implements a domain-independent workflow template for estimating perturbation-relevant feature influence under partially observed causal structure. The workflow separates predictive modeling, attribution estimation, and attribution aggregation into independent reproducible stages, allowing substitution of model classes, attribution methods, and aggregation metrics across scientific domains.

The current reference implementation uses the CIMLA python package as a backend for predictive modeling and attribution computation; however, the PerturbClaw workflow abstraction is independent of this implementation choice and supports alternative predictive estimators and attribution operators. PerturbClaw supports both single-target execution and scalable multi-target batch workflows through configuration-driven automation.

The workflow follows a five-stage pipeline:

predict → attribute → aggregate → compare → rank

Step 1 — Predict. Paired-condition matrices are loaded, normalized, and split into train/test sets. If a target variable also appears as an input, its column is permuted to avoid leakage.

Step 2 — Attribute. Two independent nonlinear models are trained: $f_0$ on condition 0 and $f_1$ on condition 1. The package currently exposes Random Forest and Neural Network variants through the CIMLA backend.

Step 3 — Aggregate. Both models are evaluated on the same attribution dataset. For RF, TreeSHAP is used; for NN, DeepSHAP is used. The workflow then compares attribution vectors feature-by-feature between the two condition-specific models on the shared evaluation samples.

Step 4 — Compare. The reference aggregation metric is the RMS attribution divergence statistic (RAD) for feature $t$ and target $g$:

$$\mathrm{RAD}$${t,g} = \sqrt{\frac{1}{|X|}\sum{\mathbf{x} \in X}!\left[\phi_t(f_1, \mathbf{x}) - \phi_t(f_0, \mathbf{x})\right]^2}

Using RMS aggregation rather than a signed mean prevents heterogeneous local changes from cancelling out.

Step 5 — Rank. Features are ranked by $\mathrm{RAD}_{t,g}$ for downstream interpretation and follow-up analysis.

3. Skill Design and Executability

The SKILL.md is structured as an agent-executable workflow with explicit commands, expected outputs, and validation steps:

1. Install dependencies and create the conda environment
2. Prepare paired-condition CSV inputs and a target definition
3. Configure a YAML file for RF or NN execution
4. Run the backend command cimla --config config.yaml
5. Verify outputs with python verify_output.py and rank features by $\mathrm{RAD}_{t,g}$

This design aligns with the Claw4S review emphasis on executability, reproducibility, and clarity for agents. The package includes a lightweight example run, a verification script, and a synthetic batch workflow for submission-safe demonstrations.

The current executable backend is inherited from the upstream CIMLA package. For submission accuracy, the package documents the validated backend stack as Python 3.8.12 with the legacy CIMLA dependency set, rather than claiming a modernized environment that has not been verified.

Example run

The run_example.sh script executes the full PerturbClaw workflow on the provided example data end-to-end:

conda activate perturbclaw_env
bash run_example.sh
python verify_output.py

The script checks that the conda environment is active, verifies the CIMLA backend is installed, confirms all four required input files are present, runs cimla --config config_templates/config_rf.yaml, and prints the top features ranked by RMS attribution divergence statistic. Expected output files in example_results/:

global_feature_importance.csv   # RAD scores — one per input feature
performance_group1.csv          # R2/MSE on train and test, condition 0
performance_group2.csv          # R2/MSE on train and test, condition 1

A well-fit model should have $R^2 > 0.3$ on the test set. If $R^2$ is near zero for both conditions, the target may not be predictable from these features and results should be interpreted cautiously.

Synthetic batch workflow

For submission-safe demonstrations without real identifiers or real measurements, the package includes a fully synthetic workflow:

bash run_synthetic_pipeline.sh

This path uses only synthetic entity names (TF001...TF200, GENE001...GENE200) and synthetic measurements. The generator can be tuned via environment variables:

N_TF=200 N_GENE=200 N_G1=500 N_G2=500 SEED=7 \
  ./scripts/generate_synthetic_perturbclaw_inputs.sh

Default synthetic dataset parameters:

• 200 synthetic features (TF001...TF200)
• 200 synthetic targets (GENE001...GENE200)
• 600 samples in condition 0
• 800 samples in condition 1

The synthetic_batch/ directory is fully regenerable from the scripts if a reviewer wants a clean fresh run.

4. Validated Backend Environment

The reference backend in this package is the upstream CIMLA implementation and inherits its dependency constraints. This package has been reconciled to the working backend environment inspected from a successful installation:

Validated execution is currently tied to the legacy CIMLA stack. The inspected working environment is Linux-based. Apple Silicon (osx-arm64) support is not claimed by this package and may require Docker, x86 emulation, or upstream maintenance by the original CIMLA authors.

5. Generalizability

PerturbClaw is explicitly framed as a domain-general workflow abstraction. Although the current backend is derived from a genomics-motivated method, the workflow itself requires only paired conditions, tabular predictors, a continuous outcome, and an attribution-capable predictive model.

The package documents how to substitute any such dataset and highlights several application classes:

• Drug response: condition 0 = untreated cells, condition 1 = drug-treated; features = protein levels; target = cell viability
• Climate science: condition 0 = pre-2000 climate, condition 1 = post-2000; features = atmospheric variables; target = regional temperature
• Economics: condition 0 = pre-policy period, condition 1 = post-policy; features = economic indicators; target = unemployment rate
• Neuroscience: condition 0 = baseline stimulus, condition 1 = active stimulus; features = neural firing rates; target = behavioral outcome
• Materials science: condition 0 = standard processing, condition 1 = modified processing; features = material properties; target = yield strength

The core question — which features differ most in attributional influence between two conditions? — is domain-agnostic, and $\mathrm{RAD}_{t,g}$ provides a portable aggregation target for that question.

6. Evidence and Positioning

The reference implementation is grounded in the empirical results reported by Dibaeinia et al. (2024), where the underlying method was evaluated on synthetic and real biological datasets. On synthetic scRNA-seq data generated by the SERGIO simulator with known ground-truth regulatory networks, the method outperforms all competing approaches (GENIE3-diff, BoostDiff, DoubleML-diff, co-expression baselines) in both AUROC and AUPRC. The advantage is largest in the high-confounding condition, where competing methods degrade substantially while the attribution-based approach maintains high performance.

PerturbClaw does not claim to replace those experiments; instead, it turns the methodological pattern into an executable, reusable workflow suitable for CLAW-style review and adaptation across domains.

For this submission package, emphasis is placed on:

• Executable reproducibility of the workflow
• Portability through synthetic paired-condition data
• Clarity of the predict–attribute–aggregate–compare–rank decomposition
• Faithful documentation of the validated dependency stack

7. Limitations

The workflow should not be interpreted as exact causal identification. The attribution differences are assumption-dependent proxies, and latent confounding or model misspecification can distort them. Specifically:

• $\alpha_{t,g}$ averages the LTE over all allowed causal diagrams, including unrealistic ones — making it a statistical proxy rather than the true causal effect in the underlying network. Selecting attribution data strategically — for example, by restricting to matched samples, homogeneous subpopulations, or time-aligned observations — can reduce the influence of latent confounders and improve the interpretability of RAD scores across domains.
• Latent confounders such as unmeasured cell type composition are not fully removed by the intervention on observed features
• SHAP-based attribution is computationally expensive for large feature sets; sampling and batching strategies are important in practice

There is also an implementation-level limitation: the reference backend depends on a legacy Python 3.8.12 stack and has been validated in a Linux environment. Cross-platform support, especially on Apple Silicon, should be treated as a separate engineering problem rather than assumed from the current package.

References

• Dibaeinia P., Ojha A., Sinha S. (2024). Interpretable AI for inference of causal molecular relationships from omics data. Science Advances, 11(7), eadk0837.
• Pearl, J. (2009). Causality: Models, Reasoning, and Inference. Cambridge University Press.
• Lundberg, S.M. & Lee, S.I. (2017). A unified approach to interpreting model predictions. NeurIPS.
• Lundberg, S.M. et al. (2020). From local explanations to global understanding with explainable AI for trees. Nature Machine Intelligence (TreeSHAP).
• Dibaeinia P. & Sinha S. (2020). SERGIO: a single-cell expression simulator guided by gene regulatory networks. Cell Systems.

Reproducibility: Skill File

The full SKILL.md for this submission is included in the package. Key execution commands:

# Set up environment
conda env create -f environment.yml
conda activate perturbclaw_env

# Install backend
pip install CIMLA

# Run example
bash run_example.sh

# Verify outputs
python verify_output.py

# Run synthetic batch workflow
bash run_synthetic_pipeline.sh

All commands are run from the submission directory. No API keys or GPU are required for the RF backend. The synthetic workflow is the recommended demonstration path for external review as it avoids real identifiers and preserves package portability.