mathipy 0.1.0__tar.gz

mathipy-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mikyung Shin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mathipy-0.1.0/PKG-INFO

@@ -0,0 +1,85 @@
+Metadata-Version: 2.4
+Name: mathipy
+Version: 0.1.0
+Summary: Multimodal item feature extraction for K-12 math assessment
+Author-email: Mikyung Shin <shin.mikyung@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/mshin77/mathipy
+Project-URL: Repository, https://github.com/mshin77/mathipy
+Project-URL: Documentation, https://mshin77.github.io/mathipy
+Project-URL: Issues, https://github.com/mshin77/mathipy/issues
+Keywords: math,assessment,education,readability,k-12
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Education
+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 :: Education
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.20.0
+Provides-Extra: nlp
+Requires-Dist: textstat>=0.7.0; extra == "nlp"
+Requires-Dist: nltk>=3.8.0; extra == "nlp"
+Provides-Extra: vision
+Requires-Dist: pillow>=9.0.0; extra == "vision"
+Requires-Dist: opencv-python-headless>=4.5.0; extra == "vision"
+Provides-Extra: ocr
+Requires-Dist: httpx>=0.24.0; extra == "ocr"
+Provides-Extra: documents
+Requires-Dist: python-docx>=0.8.0; extra == "documents"
+Requires-Dist: pdfplumber>=0.7.0; extra == "documents"
+Provides-Extra: all
+Requires-Dist: mathipy[documents,nlp,ocr,vision]; extra == "all"
+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"
+Provides-Extra: docs
+Requires-Dist: sphinx>=8.2; extra == "docs"
+Requires-Dist: pydata-sphinx-theme>=0.16; extra == "docs"
+Requires-Dist: myst-parser>=3.0; extra == "docs"
+Dynamic: license-file
+
+<img src="docs_src/_static/logo.svg" alt="MathiPy Logo" align="right" width="220px"/>
+
+[![PyPI version](https://img.shields.io/pypi/v/mathipy)](https://pypi.org/project/mathipy/)
+[![Python versions](https://img.shields.io/pypi/pyversions/mathipy)](https://pypi.org/project/mathipy/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+Multimodal item feature extraction for K-12 math assessment. Analyze readability with math-aware normalization via [textstat](https://github.com/textstat/textstat) and [NLTK](https://www.nltk.org/), classify math content by [Common Core State Standards for Mathematics](https://www.thecorestandards.org/Math/) domain, estimate cognitive load components, extract visual complexity features from images using [OpenCV](https://opencv.org/) and [Pillow](https://pillow.readthedocs.io/), and perform multimodal optical character recognition (OCR) through [Gemini](https://ai.google.dev/) and [OpenAI](https://platform.openai.com/) vision APIs.
+
+## Installation
+
+```bash
+pip install mathipy
+```
+
+With optional dependencies:
+
+```bash
+pip install mathipy[nlp]        # readability (textstat, nltk)
+pip install mathipy[vision]     # visual analysis (opencv, pillow)
+pip install mathipy[ocr]        # OCR via vision LLMs (httpx)
+pip install mathipy[documents]  # document parsing (python-docx, pdfplumber)
+pip install mathipy[all]        # all features
+```
+
+From GitHub:
+
+```bash
+pip install git+https://github.com/mshin77/mathipy.git[all]
+```
+
+## Getting Started
+
+See [Quick Start](https://mshin77.github.io/mathipy/getting-started.html) and [Analyzing Math Items](https://mshin77.github.io/mathipy/vignettes/naep-demo.html) for tutorials.
+
+## Citation
+
+- Shin, M. (2026). *MathiPy: Multimodal item feature extraction for K-12 math assessment* (Python package version 0.1.0) [Computer software]. <https://github.com/mshin77/mathipy>

mathipy-0.1.0/README.md

@@ -0,0 +1,37 @@
+<img src="docs_src/_static/logo.svg" alt="MathiPy Logo" align="right" width="220px"/>
+
+[![PyPI version](https://img.shields.io/pypi/v/mathipy)](https://pypi.org/project/mathipy/)
+[![Python versions](https://img.shields.io/pypi/pyversions/mathipy)](https://pypi.org/project/mathipy/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+Multimodal item feature extraction for K-12 math assessment. Analyze readability with math-aware normalization via [textstat](https://github.com/textstat/textstat) and [NLTK](https://www.nltk.org/), classify math content by [Common Core State Standards for Mathematics](https://www.thecorestandards.org/Math/) domain, estimate cognitive load components, extract visual complexity features from images using [OpenCV](https://opencv.org/) and [Pillow](https://pillow.readthedocs.io/), and perform multimodal optical character recognition (OCR) through [Gemini](https://ai.google.dev/) and [OpenAI](https://platform.openai.com/) vision APIs.
+
+## Installation
+
+```bash
+pip install mathipy
+```
+
+With optional dependencies:
+
+```bash
+pip install mathipy[nlp]        # readability (textstat, nltk)
+pip install mathipy[vision]     # visual analysis (opencv, pillow)
+pip install mathipy[ocr]        # OCR via vision LLMs (httpx)
+pip install mathipy[documents]  # document parsing (python-docx, pdfplumber)
+pip install mathipy[all]        # all features
+```
+
+From GitHub:
+
+```bash
+pip install git+https://github.com/mshin77/mathipy.git[all]
+```
+
+## Getting Started
+
+See [Quick Start](https://mshin77.github.io/mathipy/getting-started.html) and [Analyzing Math Items](https://mshin77.github.io/mathipy/vignettes/naep-demo.html) for tutorials.
+
+## Citation
+
+- Shin, M. (2026). *MathiPy: Multimodal item feature extraction for K-12 math assessment* (Python package version 0.1.0) [Computer software]. <https://github.com/mshin77/mathipy>

mathipy-0.1.0/mathipy/__init__.py

@@ -0,0 +1,19 @@
+"""MathiPy - Multimodal item feature extraction for K-12 math assessment."""
+
+__version__ = "0.1.0"
+__author__ = "Mikyung Shin"
+__email__ = "shin.mikyung@gmail.com"
+
+from mathipy.readability import ReadabilityAnalyzer
+from mathipy.math_content import MathContentAnalyzer
+from mathipy.cognitive_load import CognitiveLoadEstimator
+from mathipy.visual import VisualFeatureExtractor
+from mathipy.ocr import MultimodalOCR
+
+__all__ = [
+    "ReadabilityAnalyzer",
+    "MathContentAnalyzer",
+    "CognitiveLoadEstimator",
+    "VisualFeatureExtractor",
+    "MultimodalOCR",
+]

mathipy-0.1.0/mathipy/cognitive_load.py

@@ -0,0 +1,106 @@
+"""Cognitive load estimation for mathematical assessment items."""
+
+import re
+import logging
+from typing import Any, Dict, List, Optional
+
+from mathipy.utils import extract_numbers, extract_variables
+
+logger = logging.getLogger(__name__)
+
+
+class CognitiveLoadEstimator:
+    """Estimate cognitive load components for math assessment items.
+
+    Computes intrinsic (item complexity), extraneous (linguistic demand),
+    and germane (schema-building) load from text features.
+    """
+
+    def estimate(
+        self,
+        text: str,
+        readability_grade: Optional[float] = None,
+        math_terms: Optional[List[str]] = None,
+    ) -> Dict[str, Any]:
+        """Estimate cognitive load for the given text.
+
+        Args:
+            text: Input text to analyze.
+            readability_grade: Optional Flesch-Kincaid grade level. Estimated from text if not provided.
+            math_terms: Optional list of math terms found in the text. Estimated from keywords if not provided.
+
+        Returns:
+            Dictionary with ``intrinsic_cognitive_load``, ``extraneous_cognitive_load``,
+            ``germane_cognitive_load``, ``total_cognitive_load``, and element counts.
+        """
+        if not text or not text.strip():
+            return self._empty_estimate()
+
+        numbers = extract_numbers(text)
+        variables = extract_variables(text)
+        operations = sum(1 for c in text if c in "+-*/^=<>")
+        word_count = len(text.split())
+
+        intrinsic = (len(numbers) + len(variables)) / word_count if word_count else 0
+        intrinsic = min(1.0, intrinsic * 2)
+
+        if readability_grade is not None:
+            extraneous = min(1.0, readability_grade / 12)
+        else:
+            extraneous = self._estimate_extraneous(text)
+
+        math_term_count = len(math_terms) if math_terms else 0
+        if math_term_count:
+            germane = min(1.0, math_term_count / 10)
+        else:
+            germane = self._estimate_germane(text)
+
+        total = intrinsic * 0.4 + extraneous * 0.3 + germane * 0.3
+
+        return {
+            "intrinsic_cognitive_load": round(intrinsic, 3),
+            "extraneous_cognitive_load": round(extraneous, 3),
+            "germane_cognitive_load": round(germane, 3),
+            "total_cognitive_load": round(total, 3),
+            "numeric_elements": len(numbers),
+            "variable_count": len(variables),
+            "operation_count": operations,
+        }
+
+    def _estimate_extraneous(self, text: str) -> float:
+        words = text.split()
+        word_count = len(words)
+        if not word_count:
+            return 0.0
+
+        avg_word_length = sum(len(w) for w in words) / word_count
+        sentences = re.split(r"[.!?]+", text)
+        sentences = [s for s in sentences if s.strip()]
+        avg_sentence_length = word_count / max(len(sentences), 1)
+
+        estimated_grade = (avg_word_length * 1.5) + (avg_sentence_length * 0.3) - 3
+        estimated_grade = max(1, min(16, estimated_grade))
+        return min(1.0, estimated_grade / 12)
+
+    def _estimate_germane(self, text: str) -> float:
+        math_keywords = {
+            "add", "subtract", "multiply", "divide", "sum", "difference",
+            "product", "quotient", "fraction", "decimal", "percent",
+            "equation", "variable", "solve", "function", "graph",
+            "area", "perimeter", "volume", "angle", "triangle", "circle",
+            "mean", "median", "mode", "probability", "ratio", "proportion",
+        }
+        text_lower = text.lower()
+        found = sum(1 for term in math_keywords if term in text_lower)
+        return min(1.0, found / 10) if found else 0.3
+
+    def _empty_estimate(self) -> Dict[str, Any]:
+        return {
+            "intrinsic_cognitive_load": 0.0,
+            "extraneous_cognitive_load": 0.0,
+            "germane_cognitive_load": 0.0,
+            "total_cognitive_load": 0.0,
+            "numeric_elements": 0,
+            "variable_count": 0,
+            "operation_count": 0,
+        }

mathipy-0.1.0/mathipy/data/SOURCE.md

@@ -0,0 +1,9 @@
+SOURCE: U.S. Department of Education, Institute of Education Sciences,
+National Center for Education Statistics, National Assessment of Educational
+Progress (NAEP), 2017, 2022, and 2024 Mathematics Assessments.
+
+Items obtained from the NAEP Questions Tool (https://www.nationsreportcard.gov/nqt/).
+
+NAEP released items are in the public domain per the NAEP Questions Tool
+Copyright Policy. This sample dataset contains 5 items selected to
+demonstrate MathiPy's feature extraction capabilities.

mathipy-0.1.0/mathipy/data/__init__.py

@@ -0,0 +1,26 @@
+"""Sample NAEP assessment items for demonstrating MathiPy features."""
+
+import re
+from pathlib import Path
+
+DATA_DIR = Path(__file__).parent
+
+
+def get_sample_csv() -> Path:
+    """Return the path to the sample NAEP CSV file."""
+    return DATA_DIR / "naep_sample.csv"
+
+
+def get_sample_image(item_id: str) -> Path:
+    """Return the path to a sample NAEP item image by item ID (e.g., ``"2024-4M10 #2"``)."""
+    if not re.match(r'^[a-zA-Z0-9_\-\s#]+$', item_id):
+        raise ValueError(f"Invalid item_id: {item_id}")
+    path = DATA_DIR / f"{item_id}.png"
+    if not path.resolve().is_relative_to(DATA_DIR.resolve()):
+        raise ValueError(f"Invalid item_id: {item_id}")
+    return path
+
+
+def list_sample_images() -> list:
+    """Return a sorted list of available sample image filenames."""
+    return sorted(p.name for p in DATA_DIR.glob("*.png"))

mathipy-0.1.0/mathipy/data/naep_sample.csv

@@ -0,0 +1,6 @@
+item_id,grade,year,difficulty,content,image_file
+2024-4M10 #2,4,2024,Easy,Algebra,2024-4M10 #2.png
+2017-4M1 #4,4,2017,Medium,Number Properties and Operations,2017-4M1 #4.png
+2024-4M13 #2,4,2024,Hard,Measurement,2024-4M13 #2.png
+2022-8M1 #2,8,2022,Easy,Geometry,2022-8M1 #2.png
+2017-8M3 #2,8,2017,Easy,"Data Analysis, Statistics, and Probability",2017-8M3 #2.png

mathipy-0.1.0/mathipy/math_content.py

@@ -0,0 +1,213 @@
+"""Mathematical content analysis and domain classification."""
+
+import re
+import logging
+from collections import Counter
+from typing import Any, Dict, List, Set, Union
+
+from mathipy.utils import extract_numbers
+
+logger = logging.getLogger(__name__)
+
+
+class MathContentAnalyzer:
+    """Analyze math content and classify by Common Core State Standards domain.
+
+    Detects math patterns (equations, fractions, operations), counts symbols,
+    extracts numbers and vocabulary, and classifies the primary math domain
+    (arithmetic, algebra, geometry, statistics, calculus, fractions).
+    """
+
+    def __init__(self):
+        self._init_patterns()
+        self._init_vocabulary()
+
+    def _init_patterns(self):
+        self.patterns = {
+            "addition": re.compile(r"\d+\s*\+\s*\d+"),
+            "subtraction": re.compile(r"\d+\s*[-−]\s*\d+"),
+            "multiplication": re.compile(r"\d+\s*[×*·]\s*\d+"),
+            "division": re.compile(r"\d+\s*[÷/]\s*\d+"),
+            "variable": re.compile(r"\b[a-zA-Z]\b(?!\w)"),
+            "equation": re.compile(r"[^=]+=\s*[^=]+"),
+            "inequality": re.compile(r"[^<>=]+\s*[<>≤≥]\s*[^<>=]+"),
+            "exponent": re.compile(r"\w+\^[\w\d{}]+|\w+\*\*[\w\d{}]+"),
+            "function": re.compile(r"\b[a-zA-Z]+\([^)]+\)"),
+            "polynomial": re.compile(r"[a-z]\^?\d*\s*[+\-]\s*[a-z]\^?\d*"),
+            "fraction": re.compile(r"\d+/\d+|\\frac\{\d+\}\{\d+\}"),
+            "decimal": re.compile(r"\d+\.\d+"),
+            "percentage": re.compile(r"\d+\.?\d*%"),
+            "ratio": re.compile(r"\d+:\d+"),
+            "scientific_notation": re.compile(r"\d+\.?\d*\s*[×x]\s*10\^[-]?\d+"),
+            "derivative": re.compile(r"d/dx|f'|\\frac\{d\}\{dx\}"),
+            "integral": re.compile(r"∫|\\int"),
+            "limit": re.compile(r"\\lim|lim_"),
+            "summation": re.compile(r"∑|\\sum"),
+        }
+
+        self.symbols = {
+            "+": "addition", "-": "subtraction", "×": "multiplication",
+            "*": "multiplication", "·": "multiplication", "÷": "division",
+            "/": "division", "=": "equals", "<": "less_than",
+            ">": "greater_than", "≤": "less_equal", "≥": "greater_equal",
+            "≠": "not_equal", "≈": "approximately", "√": "square_root",
+            "∑": "summation", "∫": "integral", "π": "pi", "∞": "infinity",
+        }
+
+    def _init_vocabulary(self):
+        self.domains = {
+            "arithmetic": {
+                "add", "subtract", "multiply", "divide", "sum", "difference",
+                "product", "quotient", "remainder", "factor", "multiple",
+                "even", "odd", "prime", "composite", "digit", "place value",
+            },
+            "algebra": {
+                "variable", "coefficient", "term", "expression", "equation",
+                "inequality", "solve", "simplify", "factor", "polynomial",
+                "linear", "quadratic", "function", "slope", "intercept",
+            },
+            "geometry": {
+                "point", "line", "ray", "segment", "angle", "triangle",
+                "rectangle", "square", "circle", "polygon", "area",
+                "perimeter", "volume", "parallel", "perpendicular", "congruent",
+            },
+            "statistics": {
+                "mean", "median", "mode", "range", "data", "graph", "chart",
+                "probability", "outcome", "sample", "population", "distribution",
+                "standard deviation", "variance", "correlation",
+            },
+            "calculus": {
+                "limit", "derivative", "integral", "differentiate", "integrate",
+                "continuous", "rate of change", "maximum", "minimum",
+                "optimization", "series", "convergence",
+            },
+            "fractions": {
+                "fraction", "numerator", "denominator", "mixed number",
+                "improper", "equivalent", "simplify", "common denominator",
+                "decimal", "percent", "ratio", "proportion",
+            },
+        }
+
+        self.all_terms: Set[str] = set()
+        for terms in self.domains.values():
+            self.all_terms.update(terms)
+
+    def analyze(self, text: str) -> Dict[str, Any]:
+        """Analyze math content in the given text.
+
+        Args:
+            text: Input text to analyze.
+
+        Returns:
+            Dictionary with ``pattern_matches``, ``symbol_counts``, ``numbers``,
+            ``vocabulary``, ``domain_classification``, and ``math_density``.
+        """
+        if not text or not text.strip():
+            return self._empty_analysis()
+
+        text_lower = text.lower()
+        pattern_matches = self._match_patterns(text)
+        symbol_counts = self._count_symbols(text)
+        numbers = extract_numbers(text)
+        term_matches = self._match_vocabulary(text_lower)
+        domain = self._classify_domain(text_lower, pattern_matches, term_matches)
+
+        word_count = len(text.split())
+        return {
+            "pattern_matches": pattern_matches,
+            "symbol_counts": symbol_counts,
+            "total_math_symbols": sum(symbol_counts.values()),
+            "unique_symbol_types": len(symbol_counts),
+            "numbers": {
+                "count": len(numbers),
+                "values": numbers[:20],
+                "range": max(numbers) - min(numbers) if numbers else 0,
+                "has_negative": any(n < 0 for n in numbers),
+                "has_decimal": any(isinstance(n, float) and n != int(n) for n in numbers),
+            },
+            "vocabulary": {
+                "math_terms": list(term_matches.keys()),
+                "term_count": sum(term_matches.values()),
+                "unique_terms": len(term_matches),
+            },
+            "domain_classification": domain,
+            "math_density": sum(pattern_matches.values()) / word_count if word_count else 0,
+        }
+
+    def _match_patterns(self, text: str) -> Dict[str, int]:
+        matches = {}
+        for name, pattern in self.patterns.items():
+            found = pattern.findall(text)
+            if found:
+                matches[name] = len(found)
+        return matches
+
+    def _count_symbols(self, text: str) -> Dict[str, int]:
+        counts = Counter()
+        for char in text:
+            if char in self.symbols:
+                counts[self.symbols[char]] += 1
+        return dict(counts)
+
+    def _match_vocabulary(self, text: str) -> Dict[str, int]:
+        matches = {}
+        for term in self.all_terms:
+            count = text.count(term)
+            if count > 0:
+                matches[term] = count
+        return matches
+
+    def _classify_domain(
+        self,
+        text: str,
+        patterns: Dict[str, int],
+        terms: Dict[str, int],
+    ) -> Dict[str, Any]:
+        domain_scores: Dict[str, float] = {}
+
+        for domain, vocab in self.domains.items():
+            score = 0
+            for term in vocab:
+                if term in terms:
+                    score += terms[term]
+            domain_scores[domain] = score
+
+        if patterns.get("derivative") or patterns.get("integral"):
+            domain_scores["calculus"] = domain_scores.get("calculus", 0) + 5
+
+        if patterns.get("fraction"):
+            domain_scores["fractions"] = domain_scores.get("fractions", 0) + 3
+
+        if patterns.get("equation") or patterns.get("variable"):
+            domain_scores["algebra"] = domain_scores.get("algebra", 0) + 2
+
+        primary = max(domain_scores, key=domain_scores.get) if domain_scores else "unknown"
+        total = sum(domain_scores.values()) or 1
+
+        return {
+            "primary": primary,
+            "confidence": domain_scores.get(primary, 0) / total,
+            "scores": domain_scores,
+            "secondary": sorted(
+                domain_scores.keys(),
+                key=lambda k: domain_scores[k],
+                reverse=True,
+            )[1:3] if len(domain_scores) > 1 else [],
+        }
+
+    def _empty_analysis(self) -> Dict[str, Any]:
+        return {
+            "pattern_matches": {},
+            "symbol_counts": {},
+            "total_math_symbols": 0,
+            "unique_symbol_types": 0,
+            "numbers": {
+                "count": 0, "values": [], "range": 0,
+                "has_negative": False, "has_decimal": False,
+            },
+            "vocabulary": {"math_terms": [], "term_count": 0, "unique_terms": 0},
+            "domain_classification": {
+                "primary": "unknown", "confidence": 0, "scores": {}, "secondary": [],
+            },
+            "math_density": 0,
+        }