Metadata-Version: 2.4
Name: ncapackage
Version: 1.0.0
Summary: Necessary Condition Analysis (NCA) - Python implementation for identifying necessary conditions in datasets
Author-email: Gerandi Matraku <gerandi.matraku@phdtools.com>
Maintainer-email: Gerandi Matraku <gerandi.matraku@phdtools.com>
License-Expression: GPL-3.0-only
Project-URL: Homepage, https://github.com/Gerandi/nca-package
Project-URL: Documentation, https://github.com/Gerandi/nca-package#readme
Project-URL: Repository, https://github.com/Gerandi/nca-package
Project-URL: Issues, https://github.com/Gerandi/nca-package/issues
Project-URL: Original R Package, https://www.erim.nl/nca
Keywords: nca,necessary condition analysis,statistics,data analysis,ceiling line,effect size,research methods
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.20.0
Requires-Dist: pandas>=1.3.0
Requires-Dist: scipy>=1.7.0
Requires-Dist: statsmodels>=0.13.0
Requires-Dist: matplotlib>=3.4.0
Requires-Dist: plotly>=5.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: isort>=5.12.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: sphinx>=6.0.0; extra == "dev"
Requires-Dist: sphinx-rtd-theme>=1.0.0; extra == "dev"
Requires-Dist: sphinx-autodoc-typehints>=1.0.0; extra == "dev"
Requires-Dist: build>=1.0.0; extra == "dev"
Requires-Dist: twine>=4.0.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=6.0.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=1.0.0; extra == "docs"
Requires-Dist: sphinx-autodoc-typehints>=1.0.0; extra == "docs"
Requires-Dist: myst-parser>=2.0.0; extra == "docs"
Dynamic: license-file

# NCA - Necessary Condition Analysis

[![PyPI version](https://badge.fury.io/py/ncapackage.svg)](https://badge.fury.io/py/ncapackage)
[![Python Versions](https://img.shields.io/pypi/pyversions/ncapackage.svg)](https://pypi.org/project/ncapackage/)
[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)

A Python implementation of Necessary Condition Analysis (NCA), a methodology for identifying necessary conditions in datasets.

**Author:** Gerandi Matraku  
**Based on:** The original R package by Jan Dul

## Overview

Necessary Condition Analysis (NCA) is a data analysis approach that can identify necessary conditions in datasets. Unlike traditional correlation or regression analysis which identifies conditions that contribute to an outcome (sufficiency), NCA identifies conditions that must be present for an outcome to occur (necessity).

This package is a complete Python port of the [NCA R package](https://cran.r-project.org/package=NCA) (v4.0.4) by Jan Dul.

## Installation

```bash
pip install ncapackage
```

## Quick Start

```python
import pandas as pd
from nca import nca_analysis, nca_output

# Load your data
data = pd.DataFrame({
    'X': [1, 2, 3, 4, 5, 6, 7, 8, 9, 10],
    'Y': [2, 3, 4, 5, 6, 7, 8, 9, 10, 11]
})

# Run NCA analysis
model = nca_analysis(data, 'X', 'Y')

# Display results
nca_output(model)
```

## Features

- **Multiple ceiling techniques**: CE-FDH, CR-FDH, CE-VRS, CR-VRS, and more
- **Effect size calculation**: Quantify the size of the necessity effect
- **Statistical significance testing**: Permutation tests for p-values
- **Bottleneck analysis**: Identify minimum necessary levels
- **Visualization**: Plot ceiling lines and data points
- **Confidence intervals**: Bootstrap confidence intervals for ceiling lines

## Main Functions

### `nca_analysis()`

Performs the core NCA analysis:

```python
model = nca_analysis(
    data,           # DataFrame with X and Y variables
    x='X',          # Independent variable(s)
    y='Y',          # Dependent variable
    ceilings=['ce_fdh', 'cr_fdh'],  # Ceiling techniques
    test_rep=1000   # Number of permutation test repetitions
)
```

### `nca_output()`

Displays analysis results:

```python
nca_output(
    model,
    plots=True,        # Show scatter plots
    summaries=True,    # Show summary statistics
    bottlenecks=True   # Show bottleneck tables
)
```

## Ceiling Techniques

| Technique | Description |
|-----------|-------------|
| `ce_fdh` | Ceiling Envelopment - Free Disposal Hull |
| `cr_fdh` | Ceiling Regression - Free Disposal Hull |
| `ce_vrs` | Ceiling Envelopment - Variable Returns to Scale |
| `cr_vrs` | Ceiling Regression - Variable Returns to Scale |
| `ols` | Ordinary Least Squares (for comparison) |

## Output Metrics

- **Effect size**: The proportion of the scope above the ceiling line (0-1)
- **Ceiling zone**: The area above the ceiling line
- **c-accuracy**: Percentage of observations on or below the ceiling
- **Fit**: How well the ceiling fits the data
- **p-value**: Statistical significance from permutation tests
- **Inefficiency**: Various inefficiency measures

## Documentation

For detailed documentation, see:
- [Quick Start Guide](https://repub.eur.nl/pub/78323/)
- [NCA Website](https://www.erim.nl/nca)

## Citation

If you use this package, please cite:

```bibtex
@software{matraku2025nca,
  title={NCA: Necessary Condition Analysis for Python},
  author={Matraku, Gerandi},
  year={2025},
  url={https://github.com/Gerandi/nca-package},
  note={Python implementation of NCA}
}
```

And the original methodology:

```bibtex
@article{dul2016necessary,
  title={Necessary Condition Analysis (NCA): Logic and methodology of "Necessary but Not Sufficient" causality},
  author={Dul, Jan},
  journal={Organizational Research Methods},
  volume={19},
  number={1},
  pages={10--52},
  year={2016},
  publisher={SAGE Publications}
}
```

## References

- Dul, J. (2016). "Necessary Condition Analysis (NCA): Logic and Methodology of 'Necessary but Not Sufficient' Causality." Organizational Research Methods 19(1), 10-52.
- Dul, J. (2020). "Conducting Necessary Condition Analysis." SAGE Publications.
- Dul, J., van der Laan, E., & Kuik, R. (2020). "A statistical significance test for Necessary Condition Analysis." Organizational Research Methods, 23(2), 385-395.

## License

This project is licensed under the GPL-3.0 License - see the [LICENSE](LICENSE) file for details.

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.
