merkmal 0.1.0__tar.gz

merkmal-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2019-2026 Tiago Tresoldi
+
+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.

merkmal-0.1.0/PKG-INFO

@@ -0,0 +1,232 @@
+Metadata-Version: 2.4
+Name: merkmal
+Version: 0.1.0
+Summary: Standalone phonological feature systems for historical linguistics
+Author-email: Tiago Tresoldi <tiago.tresoldi@lingfil.uu.se>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/tresoldi/merkmal
+Project-URL: Documentation, https://github.com/tresoldi/merkmal#readme
+Project-URL: Repository, https://github.com/tresoldi/merkmal
+Project-URL: Bug Tracker, https://github.com/tresoldi/merkmal/issues
+Keywords: phonology,phonological features,historical linguistics,sequence alignment,cognate detection
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Text Processing :: Linguistic
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Dynamic: license-file
+
+# merkmal
+
+`merkmal` is a standalone Python package for manipulating phonological
+features. Zero runtime dependencies, Python 3.12+.
+
+It provides:
+
+- bundled phonological feature datasets
+- pluggable feature systems (9 built-in)
+- feature geometry and distance functions (Clements & Hume 1995)
+- tonal geometry (Yip/Bao)
+- query and analysis helpers for graphemes and feature sets
+- UPA transcription support
+
+## Installation
+
+Install from PyPI:
+
+```bash
+pip install merkmal
+```
+
+Development install:
+
+```bash
+git clone https://github.com/tresoldi/merkmal.git
+cd merkmal
+pip install -e ".[dev]"
+```
+
+Run checks:
+
+```bash
+ruff check .
+mypy src
+pytest -q
+```
+
+## Quick start
+
+```python
+import merkmal
+
+# Built-in systems
+print(merkmal.list_systems())
+# ['descriptive', 'broad', 'distinctive', 'pbase-hc', 'pbase-jfh',
+#  'pbase-spe', 'pbase-uftc', 'phoible', 'classfeat']
+
+# Basic grapheme lookup
+print(merkmal.get_features("p"))
+# frozenset({'consonant', 'voiceless', 'bilabial', 'stop'})
+
+# Predefined sound classes
+print(merkmal.get_class_features("V"))
+# frozenset({'vowel'})
+
+# Distance
+print(merkmal.distance("a", "e"))
+print(merkmal.distance("p", "b", system="classfeat"))
+```
+
+## Systems
+
+| System | Type | Features | Distance |
+|--------|------|----------|----------|
+| `descriptive` | categorical | articulatory | geometry-weighted |
+| `broad` | categorical | simplified | geometry-weighted |
+| `distinctive` | privative | Clements & Hume | geometry-weighted |
+| `pbase-hc`, `-jfh`, `-spe`, `-uftc` | multi-state | 4 theoretical families | geometry-weighted |
+| `phoible` | binary | 37 features | Hamming |
+| `classfeat` | hybrid | sound classes + continuous | trained weights |
+
+All systems implement the same `FeatureSystem` protocol. Distances, queries,
+matrices, and natural class derivation work across all of them.
+
+## Working with systems
+
+You can use the lazy default registry through top-level helpers, or work
+with a specific system object.
+
+```python
+import merkmal
+
+descriptive = merkmal.get_system("descriptive")
+distinctive = merkmal.get_system("distinctive")
+pbase = merkmal.get_system("pbase-hc")
+
+print(descriptive.grapheme_to_features("a"))
+print(distinctive.grapheme_to_features("a"))
+print(pbase.grapheme_to_representation("a"))
+```
+
+Exact reverse lookup is available when a native representation maps directly to
+a known grapheme.
+
+```python
+descriptive = merkmal.get_system("descriptive")
+
+grapheme = descriptive.features_to_grapheme(
+    frozenset({"consonant", "voiced", "bilabial", "stop"})
+)
+print(grapheme)
+# 'b'
+```
+
+## Feature queries
+
+Use `features_to_graphemes(...)` to find all graphemes matching a feature set.
+Matching is partial by default.
+
+```python
+import merkmal
+
+vowels = merkmal.features_to_graphemes(frozenset({"vowel"}))
+print(vowels[:10])
+
+# Exact matching
+features = merkmal.get_features("a")
+print(merkmal.features_to_graphemes(features, exact=True))
+```
+
+## Natural classes and matrices
+
+```python
+import merkmal
+
+# Shared features of a segment set
+print(merkmal.derive_class_features(["p", "t", "k"]))
+# frozenset({'consonant', 'voiceless', 'stop'})
+
+# Minimal distinguishing matrix
+matrix = merkmal.minimal_matrix(["t", "d", "s"])
+print(merkmal.tabulate_matrix(matrix))
+```
+
+```text
+grapheme | continuant | voiced
+---------+------------+-------
+t        | False      | False
+d        | False      | True
+s        | True       | False
+```
+
+## Distance
+
+```python
+import merkmal
+
+print(merkmal.distance("a", "e"))
+print(merkmal.distance("a", "u"))
+print(merkmal.distance("p", "b"))
+print(merkmal.distance("t", "d", system="pbase-hc"))
+```
+
+You can also supply a precomputed nested dictionary:
+
+```python
+precomputed = {"a": {"e": 1.5, "u": 2.0}, "p": {"b": 0.5}}
+print(merkmal.distance("a", "e", precomputed=precomputed))
+```
+
+## Multi-state systems (P-base)
+
+P-base-derived systems expose multi-state values (`+`, `-`, `n`, `.`, `o`, `x`)
+through `FeatureState`.
+
+```python
+import merkmal
+
+rep = merkmal.get_representation("a", system="pbase-hc")
+print(rep.values["syllabic"])
+# FeatureState.POSITIVE
+```
+
+The bundled P-base table is derived, not verbatim. Duplicate rows with
+conflicting values have the conflicting cells downgraded to `.`
+(`FeatureState.DOT`). The P-base data retains its own attribution and license
+notice in `src/merkmal/data/pbase/`.
+
+## Custom datasets
+
+```python
+from merkmal import create_registry, load_dataset
+
+dataset = load_dataset(directory="my_feature_data")
+registry = create_registry(dataset=dataset)
+system = registry.get_system("descriptive")
+print(system.grapheme_to_features("k"))
+```
+
+Expected files in `my_feature_data/`: `sounds.tsv`, `classes.tsv`, `features.tsv`.
+
+## Documentation
+
+See the [tutorials](docs/tutorials/) for worked examples covering phonological
+features, typology, historical linguistics, cognate detection, and UPA
+transcription.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

merkmal-0.1.0/README.md

@@ -0,0 +1,201 @@
+# merkmal
+
+`merkmal` is a standalone Python package for manipulating phonological
+features. Zero runtime dependencies, Python 3.12+.
+
+It provides:
+
+- bundled phonological feature datasets
+- pluggable feature systems (9 built-in)
+- feature geometry and distance functions (Clements & Hume 1995)
+- tonal geometry (Yip/Bao)
+- query and analysis helpers for graphemes and feature sets
+- UPA transcription support
+
+## Installation
+
+Install from PyPI:
+
+```bash
+pip install merkmal
+```
+
+Development install:
+
+```bash
+git clone https://github.com/tresoldi/merkmal.git
+cd merkmal
+pip install -e ".[dev]"
+```
+
+Run checks:
+
+```bash
+ruff check .
+mypy src
+pytest -q
+```
+
+## Quick start
+
+```python
+import merkmal
+
+# Built-in systems
+print(merkmal.list_systems())
+# ['descriptive', 'broad', 'distinctive', 'pbase-hc', 'pbase-jfh',
+#  'pbase-spe', 'pbase-uftc', 'phoible', 'classfeat']
+
+# Basic grapheme lookup
+print(merkmal.get_features("p"))
+# frozenset({'consonant', 'voiceless', 'bilabial', 'stop'})
+
+# Predefined sound classes
+print(merkmal.get_class_features("V"))
+# frozenset({'vowel'})
+
+# Distance
+print(merkmal.distance("a", "e"))
+print(merkmal.distance("p", "b", system="classfeat"))
+```
+
+## Systems
+
+| System | Type | Features | Distance |
+|--------|------|----------|----------|
+| `descriptive` | categorical | articulatory | geometry-weighted |
+| `broad` | categorical | simplified | geometry-weighted |
+| `distinctive` | privative | Clements & Hume | geometry-weighted |
+| `pbase-hc`, `-jfh`, `-spe`, `-uftc` | multi-state | 4 theoretical families | geometry-weighted |
+| `phoible` | binary | 37 features | Hamming |
+| `classfeat` | hybrid | sound classes + continuous | trained weights |
+
+All systems implement the same `FeatureSystem` protocol. Distances, queries,
+matrices, and natural class derivation work across all of them.
+
+## Working with systems
+
+You can use the lazy default registry through top-level helpers, or work
+with a specific system object.
+
+```python
+import merkmal
+
+descriptive = merkmal.get_system("descriptive")
+distinctive = merkmal.get_system("distinctive")
+pbase = merkmal.get_system("pbase-hc")
+
+print(descriptive.grapheme_to_features("a"))
+print(distinctive.grapheme_to_features("a"))
+print(pbase.grapheme_to_representation("a"))
+```
+
+Exact reverse lookup is available when a native representation maps directly to
+a known grapheme.
+
+```python
+descriptive = merkmal.get_system("descriptive")
+
+grapheme = descriptive.features_to_grapheme(
+    frozenset({"consonant", "voiced", "bilabial", "stop"})
+)
+print(grapheme)
+# 'b'
+```
+
+## Feature queries
+
+Use `features_to_graphemes(...)` to find all graphemes matching a feature set.
+Matching is partial by default.
+
+```python
+import merkmal
+
+vowels = merkmal.features_to_graphemes(frozenset({"vowel"}))
+print(vowels[:10])
+
+# Exact matching
+features = merkmal.get_features("a")
+print(merkmal.features_to_graphemes(features, exact=True))
+```
+
+## Natural classes and matrices
+
+```python
+import merkmal
+
+# Shared features of a segment set
+print(merkmal.derive_class_features(["p", "t", "k"]))
+# frozenset({'consonant', 'voiceless', 'stop'})
+
+# Minimal distinguishing matrix
+matrix = merkmal.minimal_matrix(["t", "d", "s"])
+print(merkmal.tabulate_matrix(matrix))
+```
+
+```text
+grapheme | continuant | voiced
+---------+------------+-------
+t        | False      | False
+d        | False      | True
+s        | True       | False
+```
+
+## Distance
+
+```python
+import merkmal
+
+print(merkmal.distance("a", "e"))
+print(merkmal.distance("a", "u"))
+print(merkmal.distance("p", "b"))
+print(merkmal.distance("t", "d", system="pbase-hc"))
+```
+
+You can also supply a precomputed nested dictionary:
+
+```python
+precomputed = {"a": {"e": 1.5, "u": 2.0}, "p": {"b": 0.5}}
+print(merkmal.distance("a", "e", precomputed=precomputed))
+```
+
+## Multi-state systems (P-base)
+
+P-base-derived systems expose multi-state values (`+`, `-`, `n`, `.`, `o`, `x`)
+through `FeatureState`.
+
+```python
+import merkmal
+
+rep = merkmal.get_representation("a", system="pbase-hc")
+print(rep.values["syllabic"])
+# FeatureState.POSITIVE
+```
+
+The bundled P-base table is derived, not verbatim. Duplicate rows with
+conflicting values have the conflicting cells downgraded to `.`
+(`FeatureState.DOT`). The P-base data retains its own attribution and license
+notice in `src/merkmal/data/pbase/`.
+
+## Custom datasets
+
+```python
+from merkmal import create_registry, load_dataset
+
+dataset = load_dataset(directory="my_feature_data")
+registry = create_registry(dataset=dataset)
+system = registry.get_system("descriptive")
+print(system.grapheme_to_features("k"))
+```
+
+Expected files in `my_feature_data/`: `sounds.tsv`, `classes.tsv`, `features.tsv`.
+
+## Documentation
+
+See the [tutorials](docs/tutorials/) for worked examples covering phonological
+features, typology, historical linguistics, cognate detection, and UPA
+transcription.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

merkmal-0.1.0/pyproject.toml

@@ -0,0 +1,75 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "merkmal"
+version = "0.1.0"
+description = "Standalone phonological feature systems for historical linguistics"
+authors = [
+    {name = "Tiago Tresoldi", email = "tiago.tresoldi@lingfil.uu.se"}
+]
+license = "MIT"
+license-files = ["LICENSE"]
+readme = "README.md"
+requires-python = ">=3.12"
+keywords = [
+    "phonology",
+    "phonological features",
+    "historical linguistics",
+    "sequence alignment",
+    "cognate detection",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering",
+    "Topic :: Text Processing :: Linguistic",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = []
+
+[project.optional-dependencies]
+dev = ["pytest>=7.0", "pytest-cov", "ruff", "mypy", "build"]
+
+[project.urls]
+Homepage = "https://github.com/tresoldi/merkmal"
+Documentation = "https://github.com/tresoldi/merkmal#readme"
+Repository = "https://github.com/tresoldi/merkmal"
+"Bug Tracker" = "https://github.com/tresoldi/merkmal/issues"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+include-package-data = true
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["merkmal*"]
+
+[tool.setuptools.package-data]
+merkmal = ["data/*.tsv", "data/pbase/*", "data/phoible/*", "data/classfeat/*", "data/transcriptions/*"]
+
+[tool.ruff]
+target-version = "py312"
+line-length = 99
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "N", "UP", "B", "A", "SIM", "TCH"]
+
+[tool.mypy]
+python_version = "3.12"
+strict = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+
+[tool.coverage.run]
+source = ["merkmal"]
+omit = ["*/tests/*", "*/test_*"]

merkmal-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

merkmal-0.1.0/src/merkmal/__init__.py

@@ -0,0 +1,119 @@
+"""Public API for the merkmal package."""
+
+__version__ = "0.1.0"
+
+from merkmal.analysis import (
+    FeatureMatrix,
+    derive_class_features,
+    distance,
+    features_to_graphemes,
+    minimal_matrix,
+    tabulate_matrix,
+    valued_distance,
+    valued_matches,
+)
+from merkmal.audit import DatasetAuditReport, audit_dataset
+from merkmal.dataset import FeatureDataset, dataset_from_rows, load_builtin_dataset, load_dataset
+from merkmal.exporters import export_class_features, export_distances, export_matrix
+from merkmal.geometry import DEFAULT_GEOMETRY, FeatureNode, GeometryNode
+from merkmal.protocol import FeatureSystem
+from merkmal.registry import (
+    Registry,
+    add_features,
+    create_registry,
+    feature_distance,
+    features_to_grapheme,
+    get_class_features,
+    get_class_representation,
+    get_features,
+    get_registry,
+    get_representation,
+    get_system,
+    is_class,
+    list_systems,
+    matches,
+    partial_match,
+    register,
+    reset_registry,
+    segment_distance,
+    set_default,
+    set_registry,
+    sound_distance,
+)
+from merkmal.representations import (
+    CategoricalFeatures,
+    FeatureRepresentation,
+    FeatureState,
+    ValuedFeatures,
+)
+from merkmal.segmentation import merge_tone_digits, parse_chao_digits
+from merkmal.upa import adapt as adapt_upa
+from merkmal.upa import adapt_segment as adapt_upa_segment
+from merkmal.upa import segment_upa
+from merkmal.systems.broad import BroadFeatureSystem
+from merkmal.systems.descriptive import DescriptiveFeatureSystem
+from merkmal.systems.distinctive import DistinctiveFeatureSystem
+from merkmal.systems.pbase import PBaseFeatureSystem
+from merkmal.systems.classfeat import ClassFeatFeatureSystem
+from merkmal.systems.phoible import PhoibleFeatureSystem
+
+__all__ = [
+    "__version__",
+    "DEFAULT_GEOMETRY",
+    "BroadFeatureSystem",
+    "DescriptiveFeatureSystem",
+    "DistinctiveFeatureSystem",
+    "ClassFeatFeatureSystem",
+    "CategoricalFeatures",
+    "DatasetAuditReport",
+    "FeatureDataset",
+    "FeatureMatrix",
+    "FeatureNode",
+    "FeatureRepresentation",
+    "FeatureState",
+    "FeatureSystem",
+    "GeometryNode",
+    "PBaseFeatureSystem",
+    "PhoibleFeatureSystem",
+    "Registry",
+    "ValuedFeatures",
+    "adapt_upa",
+    "adapt_upa_segment",
+    "add_features",
+    "audit_dataset",
+    "create_registry",
+    "dataset_from_rows",
+    "derive_class_features",
+    "distance",
+    "feature_distance",
+    "export_class_features",
+    "export_distances",
+    "export_matrix",
+    "features_to_grapheme",
+    "features_to_graphemes",
+    "get_class_features",
+    "get_class_representation",
+    "get_features",
+    "get_registry",
+    "get_representation",
+    "get_system",
+    "is_class",
+    "list_systems",
+    "matches",
+    "merge_tone_digits",
+    "load_builtin_dataset",
+    "load_dataset",
+    "minimal_matrix",
+    "parse_chao_digits",
+    "partial_match",
+    "register",
+    "reset_registry",
+    "segment_distance",
+    "set_default",
+    "segment_upa",
+    "set_registry",
+    "sound_distance",
+    "tabulate_matrix",
+    "valued_distance",
+    "valued_matches",
+]