iita-python 0.0.post42__tar.gz

iita_python-0.0.post42/.github/workflows/release.yaml

@@ -0,0 +1,136 @@
+name: release
+
+on:
+  push:
+    tags:
+      - 'v*.*'
+      - 'v*.*.*'
+
+env:
+  PACKAGE_NAME: "iita_python"
+  OWNER: "Alexe1900"
+
+jobs:
+  details:
+    runs-on: ubuntu-latest
+    outputs:
+      new_version: ${{ steps.release.outputs.new_version }}
+      suffix: ${{ steps.release.outputs.suffix }}
+      tag_name: ${{ steps.release.outputs.tag_name }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Extract tag and Details
+        id: release
+        run: |
+          if [ "${{ github.ref_type }}" = "tag" ]; then
+            TAG_NAME=${GITHUB_REF#refs/tags/}
+            NEW_VERSION=$(echo $TAG_NAME | awk -F'-' '{print $1}')
+            SUFFIX=$(echo $TAG_NAME | grep -oP '[a-z]+[0-9]+' || echo "")
+            echo "new_version=$NEW_VERSION" >> "$GITHUB_OUTPUT"
+            echo "suffix=$SUFFIX" >> "$GITHUB_OUTPUT"
+            echo "tag_name=$TAG_NAME" >> "$GITHUB_OUTPUT"
+            echo "Version is $NEW_VERSION"
+            echo "Suffix is $SUFFIX"
+            echo "Tag name is $TAG_NAME"
+          else
+            echo "No tag found"
+            exit 1
+          fi
+
+  check_pypi:
+    needs: details
+    runs-on: ubuntu-latest
+    steps:
+      - name: Fetch information from PyPI
+        run: |
+          response=$(curl -s https://pypi.org/pypi/${{ env.PACKAGE_NAME }}/json || echo "{}")
+          latest_previous_version=$(echo $response | jq --raw-output "select(.releases != null) | .releases | keys_unsorted | last")
+          if [ -z "$latest_previous_version" ]; then
+            echo "Package not found on PyPI."
+            latest_previous_version="0.0.0"
+          fi
+          echo "Latest version on PyPI: $latest_previous_version"
+          echo "latest_previous_version=$latest_previous_version" >> $GITHUB_ENV
+
+      - name: Compare versions and exit if not newer
+        run: |
+          NEW_VERSION=${{ needs.details.outputs.new_version }}
+          LATEST_VERSION=$latest_previous_version
+          if [ "$(printf '%s\n' "$LATEST_VERSION" "$NEW_VERSION" | sort -rV | head -n 1)" != "$NEW_VERSION" ] || [ "$NEW_VERSION" == "$LATEST_VERSION" ]; then
+            echo "The new version $NEW_VERSION is not greater than the latest version $LATEST_VERSION on PyPI."
+            exit 1
+          else
+            echo "The new version $NEW_VERSION is greater than the latest version $LATEST_VERSION on PyPI."
+          fi
+
+  setup_and_build:
+    needs: [details, check_pypi]
+    runs-on: ubuntu-latest
+    steps:      
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: |
+          python -m pip install --upgrade pip
+          pip install build twine setuptools_scm
+      
+      - name: Build package
+        run: |
+          python -m build
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  pypi_publish:
+    name: Upload release to PyPI
+    needs: [setup_and_build, details]
+    runs-on: ubuntu-latest
+    environment:
+      name: release
+    permissions:
+      id-token: write
+    steps:
+      - name: Download artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish distribution to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  github_release:
+    name: Create GitHub Release
+    needs: [setup_and_build, details]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Download artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Create GitHub Release
+        id: create_release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          gh release create ${{ needs.details.outputs.tag_name }} dist/* --title ${{ needs.details.outputs.tag_name }} --generate-notes

iita_python-0.0.post42/.gitignore

@@ -0,0 +1,6 @@
+__pycache__
+test_data
+test.py
+build
+dist
+*.egg-info

iita_python-0.0.post42/PKG-INFO

@@ -0,0 +1,148 @@
+Metadata-Version: 2.4
+Name: iita_python
+Version: 0.0.post42
+Summary: IITA algorithm in python
+Author-email: Aliaksei Badnarchuk <alexejbodnarchuk@gmail.com>
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: numpy
+Requires-Dist: pandas
+
+# IITA_Python
+
+A Python implementation of the Inductive ITem Tree Analysis (IITA) algorithm for analyzing and validating quasi-orderings in psychometric data.
+
+Intended to replicate the functionality DAKS package from R, with an OOP-style interface for simpler functionality expansion
+
+## Installation
+
+### From PyPI
+
+```bash
+pip install iita_python
+```
+
+## Quick Start
+
+```python
+from iita_python import Dataset, ind_gen, unfold_examples, orig_iita_fit
+import iita_python.utils as utils
+
+# Load response patterns from CSV
+response_patterns = utils.read_rp('data.csv')
+
+# Create Dataset: computes counterexamples and equivalence examples
+data = Dataset(response_patterns)
+
+# Extract counterexamples and generate quasi-orderings
+ce = unfold_examples(data.ce)
+qos = ind_gen(ce, data.items)
+
+# Evaluate fit for each quasi-order
+for i, qo in enumerate(qos):
+    fit = orig_iita_fit(data, qo)
+    print(f"Quasi-order {i}: fit = {fit:.2f}")
+```
+
+## Data Format
+
+### Input: Response Patterns
+
+Response patterns should be a 2D array where:
+- **Rows** represent subjects (respondents)
+- **Columns** represent items (questions/tasks)
+- **Values** are 0 (incorrect) or 1 (correct), with NaN for missing responses
+
+Example (CSV):
+```
+1,0,1,0,1
+0,0,1,0,1
+1,1,1,1,1
+```
+
+When reading from a file with `utils.read_rp()`, missing data can be specified via the `nan_vals` parameter.
+
+## Core Modules
+
+### `dataset.py`
+
+**`Dataset` class**
+
+Stores response patterns and computes derived metrics:
+
+- `rp`: response patterns (DataFrame)
+- `ce`: counterexamples - pairs (i, j) where subject has item i incorrect but item j correct
+- `eqe`: equivalence examples - pairs (i, j) where subject answered items i and j identically
+- `items`: number of items
+- `subjects`: number of subjects
+- `filled_vals`: number of non-missing responses per item
+
+### `quasiorder.py`
+
+**`unfold_examples(matrix, relativity=None, dtype=np.float32)`**
+
+Converts a 2D matrix (e.g., counterexamples or equivalence examples) into a list of (value, i, j) tuples, excluding diagonal entries. Optionally normalizes by a relativity matrix.
+
+**`ind_gen(counterexamples, n)`**
+
+Generates candidate quasi-orderings from counterexample data. Returns a list of quasi-order matrices (numpy arrays) that progressively include edges.
+
+**`get_edge_list(qo_matrix, buff=0)`**
+
+Extracts the edge list from a quasi-order matrix as a list of (i, j) pairs.
+
+### `fit_metrics.py`
+
+**`orig_iita_fit(data, qo)`**
+
+Computes the fit of a quasi-order to observed data using Schrepp's method:
+
+1. Estimates an error rate from counterexamples on edges in the quasi-order
+2. Predicts expected counterexamples for all item pairs under the quasi-order
+3. Computes mean squared error between observed and expected counterexamples
+
+Returns: float (MSE, lower is better)
+
+## Requirements
+
+- Python >= 3.8
+- numpy
+- pandas
+
+## Testing
+
+See the `test_ipynbs` folder. You can open the Jupyter notebooks in Google Colab and run all cells to see test results.
+
+I am comparing my results on the PISA dataset to those of Milan Segedinac ([his implementation](https://github.com/milansegedinac/kst))
+
+Please report any test failures in an issue
+
+## Contributing
+
+Pull requests and issues are welcome. For major changes, please open an issue first to discuss.
+
+## IITA Overview
+
+Schrepp (1999, 2003) developed IITA (Inductive itemm Tree Analysis) as a means to derive a surmise relation from dichotomous response patterns. Sargin and Ünlü (2009; Ünlü & Sargin, 2010) implemented two advanced versions of that procedure.
+
+The three inductive item tree analysis algorithms are exploratory methods for extracting quasi orders (surmise relations) from data. In each algorithm, competing binary relations are generated (in the same way for all three versions), and a fit measure (differing from version to version) is computed for every relation of the selection set in order to find the quasi order that fits the data best. In all three algorithms, the idea is to estimate the numbers of counterexamples for each quasi order, and to find, over all competing quasi orders, the minimum value for the discrepancy between the observed and expected numbers of counterexamples.
+
+The three data analysis methods differ in their choices of estimates for the expected numbers of counterexamples. (For an item pair (i,j), the number of subjects solving item j but failing to solve item i, is the corresponding number of counterexamples. Their response patterns contradict the interpretation of (i,j) as `mastering item j implies mastering item i.')
+
+## References
+
+- Schrepp, M. (2001). IITA: A program for the analysis of individual item and step matrices. Unpublished technical report.
+- Knowledge Space Theory: https://en.wikipedia.org/wiki/Knowledge_space
+
+## Author
+
+Alexe1900, mentored and supervised by Peter Steiner from PHSG St. Gallen
+
+---
+
+## Roadmap
+
+- [ ] Full DAKS functionality
+- [ ] Performance optimizations for large datasets
+- [ ] Visualization tools for quasi-orderings
+- [ ] Comprehensive test suite (unit + integration)

iita_python-0.0.post42/README.md

@@ -0,0 +1,138 @@
+# IITA_Python
+
+A Python implementation of the Inductive ITem Tree Analysis (IITA) algorithm for analyzing and validating quasi-orderings in psychometric data.
+
+Intended to replicate the functionality DAKS package from R, with an OOP-style interface for simpler functionality expansion
+
+## Installation
+
+### From PyPI
+
+```bash
+pip install iita_python
+```
+
+## Quick Start
+
+```python
+from iita_python import Dataset, ind_gen, unfold_examples, orig_iita_fit
+import iita_python.utils as utils
+
+# Load response patterns from CSV
+response_patterns = utils.read_rp('data.csv')
+
+# Create Dataset: computes counterexamples and equivalence examples
+data = Dataset(response_patterns)
+
+# Extract counterexamples and generate quasi-orderings
+ce = unfold_examples(data.ce)
+qos = ind_gen(ce, data.items)
+
+# Evaluate fit for each quasi-order
+for i, qo in enumerate(qos):
+    fit = orig_iita_fit(data, qo)
+    print(f"Quasi-order {i}: fit = {fit:.2f}")
+```
+
+## Data Format
+
+### Input: Response Patterns
+
+Response patterns should be a 2D array where:
+- **Rows** represent subjects (respondents)
+- **Columns** represent items (questions/tasks)
+- **Values** are 0 (incorrect) or 1 (correct), with NaN for missing responses
+
+Example (CSV):
+```
+1,0,1,0,1
+0,0,1,0,1
+1,1,1,1,1
+```
+
+When reading from a file with `utils.read_rp()`, missing data can be specified via the `nan_vals` parameter.
+
+## Core Modules
+
+### `dataset.py`
+
+**`Dataset` class**
+
+Stores response patterns and computes derived metrics:
+
+- `rp`: response patterns (DataFrame)
+- `ce`: counterexamples - pairs (i, j) where subject has item i incorrect but item j correct
+- `eqe`: equivalence examples - pairs (i, j) where subject answered items i and j identically
+- `items`: number of items
+- `subjects`: number of subjects
+- `filled_vals`: number of non-missing responses per item
+
+### `quasiorder.py`
+
+**`unfold_examples(matrix, relativity=None, dtype=np.float32)`**
+
+Converts a 2D matrix (e.g., counterexamples or equivalence examples) into a list of (value, i, j) tuples, excluding diagonal entries. Optionally normalizes by a relativity matrix.
+
+**`ind_gen(counterexamples, n)`**
+
+Generates candidate quasi-orderings from counterexample data. Returns a list of quasi-order matrices (numpy arrays) that progressively include edges.
+
+**`get_edge_list(qo_matrix, buff=0)`**
+
+Extracts the edge list from a quasi-order matrix as a list of (i, j) pairs.
+
+### `fit_metrics.py`
+
+**`orig_iita_fit(data, qo)`**
+
+Computes the fit of a quasi-order to observed data using Schrepp's method:
+
+1. Estimates an error rate from counterexamples on edges in the quasi-order
+2. Predicts expected counterexamples for all item pairs under the quasi-order
+3. Computes mean squared error between observed and expected counterexamples
+
+Returns: float (MSE, lower is better)
+
+## Requirements
+
+- Python >= 3.8
+- numpy
+- pandas
+
+## Testing
+
+See the `test_ipynbs` folder. You can open the Jupyter notebooks in Google Colab and run all cells to see test results.
+
+I am comparing my results on the PISA dataset to those of Milan Segedinac ([his implementation](https://github.com/milansegedinac/kst))
+
+Please report any test failures in an issue
+
+## Contributing
+
+Pull requests and issues are welcome. For major changes, please open an issue first to discuss.
+
+## IITA Overview
+
+Schrepp (1999, 2003) developed IITA (Inductive itemm Tree Analysis) as a means to derive a surmise relation from dichotomous response patterns. Sargin and Ünlü (2009; Ünlü & Sargin, 2010) implemented two advanced versions of that procedure.
+
+The three inductive item tree analysis algorithms are exploratory methods for extracting quasi orders (surmise relations) from data. In each algorithm, competing binary relations are generated (in the same way for all three versions), and a fit measure (differing from version to version) is computed for every relation of the selection set in order to find the quasi order that fits the data best. In all three algorithms, the idea is to estimate the numbers of counterexamples for each quasi order, and to find, over all competing quasi orders, the minimum value for the discrepancy between the observed and expected numbers of counterexamples.
+
+The three data analysis methods differ in their choices of estimates for the expected numbers of counterexamples. (For an item pair (i,j), the number of subjects solving item j but failing to solve item i, is the corresponding number of counterexamples. Their response patterns contradict the interpretation of (i,j) as `mastering item j implies mastering item i.')
+
+## References
+
+- Schrepp, M. (2001). IITA: A program for the analysis of individual item and step matrices. Unpublished technical report.
+- Knowledge Space Theory: https://en.wikipedia.org/wiki/Knowledge_space
+
+## Author
+
+Alexe1900, mentored and supervised by Peter Steiner from PHSG St. Gallen
+
+---
+
+## Roadmap
+
+- [ ] Full DAKS functionality
+- [ ] Performance optimizations for large datasets
+- [ ] Visualization tools for quasi-orderings
+- [ ] Comprehensive test suite (unit + integration)

iita_python-0.0.post42/iita_python/__init__.py

@@ -0,0 +1,4 @@
+from .dataset import Dataset
+from .quasiorder import ind_gen, unfold_examples
+
+__all__ = ['Dataset', 'unfold_examples', 'ind_gen']

iita_python-0.0.post42/iita_python/_version.py

@@ -0,0 +1,34 @@
+# file generated by setuptools-scm
+# don't change, don't track in version control
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Tuple
+    from typing import Union
+
+    VERSION_TUPLE = Tuple[Union[int, str], ...]
+    COMMIT_ID = Union[str, None]
+else:
+    VERSION_TUPLE = object
+    COMMIT_ID = object
+
+version: str
+__version__: str
+__version_tuple__: VERSION_TUPLE
+version_tuple: VERSION_TUPLE
+commit_id: COMMIT_ID
+__commit_id__: COMMIT_ID
+
+__version__ = version = '0.0.post42'
+__version_tuple__ = version_tuple = (0, 0, 'post42')
+
+__commit_id__ = commit_id = 'ga5c158b2b'

iita_python-0.0.post42/iita_python/dataset.py

@@ -0,0 +1,82 @@
+import numpy as np
+import numpy.typing as npt
+from typing import Self, List
+import pandas as pd
+
+class Dataset():
+    #aliases for response_patterns, counterexamples, equiv_examples
+    @property
+    def rp(self) -> pd.DataFrame:
+        return self._rp
+    @rp.setter
+    def rp(self, inp: pd.DataFrame) -> None:
+        self._rp = inp
+    response_patterns = rp
+
+    @property
+    def ce(self) -> pd.DataFrame:
+        return self._ce
+    @ce.setter
+    def ce(self, inp: pd.DataFrame) -> None:
+        self._ce = inp
+    counterexamples = ce
+
+    @property
+    def eqe(self) -> pd.DataFrame:
+        return self._eqe
+    @eqe.setter
+    def eqe(self, inp: pd.DataFrame) -> None:
+        self._eqe = inp
+    equiv_examples = eqe
+
+    @property
+    def items(self):
+        return self.ce.shape[0]
+    
+    @property
+    def subjects(self):
+        return self.rp.shape[0]
+    
+    @property
+    def filled_vals(self):
+        return (~np.isnan(self.rp)).sum(axis=0)
+
+    def __init__(self, response_patterns: pd.DataFrame | npt.NDArray | List[List[int]]):
+        """
+        Computes the counterexamples and equivalence examples from response patterns\n
+        Supports pandas dataframes, numpy arrays, and python lists\n
+        Rows represent the subjects, columns - the items\n
+        """
+        self._rp = pd.DataFrame(response_patterns, index=None, columns=None)
+        self._ce = None
+        self._eqe = None
+        
+        #counterexamples computation   
+        self.ce = pd.DataFrame(0, index=np.arange(self.rp.shape[1]), columns=np.arange(self.rp.shape[1]))
+
+        for i in range(len(self.rp)):
+            #for subject i, find all cases where a=0 and b=1 (counterexamples to b->a or a <= b) and increment where they intersect
+            not_a = (self.rp.loc[i] == 0)
+            b = (self.rp.loc[i] == 1)
+            self.ce.loc[not_a, b] += 1
+        
+        #equivalence examples computation   
+        self.eqe = pd.DataFrame(0, index=np.arange(self.rp.shape[1]), columns=np.arange(self.rp.shape[1]))
+        for i in range(len(self.rp)):
+            #for subject i, increment all cases where a=b (examples of equivalence of a and b)
+            row = self.rp.loc[i].to_numpy()
+            self.eqe += np.equal.outer(row, row).astype(int)
+    
+    def add(self, dataset_to_add: Self):
+        """
+        Add a second IITA_Dataset: concatenate the response patterns, add counterexamples and equivalence examples\n
+        Item amounts must match, else ValueError
+        """
+        if (self.rp.shape[1] != dataset_to_add.shape[1]):
+            raise ValueError('Item amounts must match')
+        
+        self.rp = pd.concat(self.rp, dataset_to_add.rp)
+        self.ce = self.ce + dataset_to_add.ce
+        self.eqe = self.eqe + dataset_to_add.eqe
+    
+    __iadd__ = add

iita_python-0.0.post42/iita_python/fit_metrics.py

@@ -0,0 +1,64 @@
+import numpy as np
+import numpy.typing as npt
+import pandas as pd
+from .dataset import Dataset
+from .quasiorder import QuasiOrder
+
+def orig_iita_fit(data: Dataset, qo: QuasiOrder):
+    """
+    Calculates the original IITA fit metric for a given dataset and quasiorder\n
+    """
+    qo_edges = qo.get_edge_list()
+    p = data.rp.to_numpy().sum(axis=0) / data.subjects
+
+    error = 0
+    for a, b in qo_edges:
+        error += data.ce.iloc[a, b] / (p[b] * data.subjects)
+    
+    error /= len(qo_edges)
+
+    expected_ce = np.zeros(data.ce.shape)
+
+    for i in range(data.items):
+        for j in range(data.items):
+            if (i == j): continue
+
+            if (qo.full_matrix[i][j]):
+                expected_ce[i][j] = error * p[j] * data.subjects
+            else:
+                expected_ce[i][j] = (1 - p[i]) * p[j] * data.subjects * (1 - error)
+    
+    ce = data.ce.to_numpy().flatten()
+    expected_ce = expected_ce.flatten()
+    
+    return ((ce - expected_ce) ** 2).sum() / (data.items**2 - data.items)
+
+def corr_iita_fit(data: Dataset, qo: QuasiOrder):
+    """
+    Calculates the corrected IITA fit metric for a given dataset and quasiorder\n
+    """
+    qo_edges = qo.get_edge_list()
+    p = data.rp.to_numpy().sum(axis=0) / data.subjects
+
+    error = 0
+    for a, b in qo_edges:
+        error += data.ce.iloc[a, b] / (p[b] * data.subjects)
+    
+    error /= len(qo_edges)
+
+    expected_ce = np.zeros(data.ce.shape)
+
+    for i in range(data.items):
+        for j in range(data.items):
+            if (i == j): continue
+
+            if (qo.full_matrix[i][j]):
+                expected_ce[i][j] = error * p[j] * data.subjects
+            elif (not qo.full_matrix[j][i]):
+                expected_ce[i][j] = (1 - p[i]) * p[j] * data.subjects
+            else:
+                expected_ce[i][j] = (p[j] * data.subjects) - ((p[i] - p[i] * error) * data.subjects)
+    
+    ce = data.ce.to_numpy().flatten()
+    expected_ce = expected_ce.flatten()
+    return ((ce - expected_ce) ** 2).sum() / (data.items**2 - data.items)