ga-matrix 0.1.0__tar.gz

ga_matrix-0.1.0/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## 0.1.0 - 2026-09-01
+
+- Prepared the package for GitHub and PyPI publication as `ga-matrix`.
+- Added README, MIT license, gitignore, package version source, and typed package marker.
+- Corrected packaging metadata, project URLs, coverage source, and GitHub Actions imports.
+- Reworked tests around `pytest` and removed heavyweight performance checks from unit tests.
+- Fixed in-place subtraction and division behavior in matrix operations.

ga_matrix-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 GA Matrix contributors
+
+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.

ga_matrix-0.1.0/MANIFEST.in

@@ -0,0 +1,2 @@
+include CHANGELOG.md
+recursive-include docs *.md

ga_matrix-0.1.0/PKG-INFO

@@ -0,0 +1,206 @@
+Metadata-Version: 2.4
+Name: ga-matrix
+Version: 0.1.0
+Summary: Label-aware origin-destination matrix utilities built on NumPy and pandas.
+Author: GA Matrix contributors
+License-Expression: MIT
+Project-URL: Documentation, https://github.com/andreagemma/matrix#readme
+Project-URL: Issues, https://github.com/andreagemma/matrix/issues
+Project-URL: Source, https://github.com/andreagemma/matrix
+Keywords: ga-matrix,matrix,origin-destination,numpy,pandas
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3 :: Only
+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: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Requires-Dist: pandas>=2.0
+Provides-Extra: test
+Requires-Dist: pytest>=8.0; extra == "test"
+Requires-Dist: pytest-cov>=5.0; extra == "test"
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+Requires-Dist: twine>=5.1; extra == "dev"
+Dynamic: license-file
+
+# GA Matrix
+
+[![CI](https://github.com/andreagemma/matrix/actions/workflows/ci.yml/badge.svg)](https://github.com/andreagemma/matrix/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/ga-matrix.svg)](https://pypi.org/project/ga-matrix/)
+[![Python](https://img.shields.io/pypi/pyversions/ga-matrix.svg)](https://pypi.org/project/ga-matrix/)
+
+GA Matrix provides small NumPy-backed matrix containers with label-based access,
+long-form pandas import/export helpers, and optional timestamp support for
+origin-destination data.
+
+The PyPI distribution is named `ga-matrix`; the import package is named `matrix`.
+
+## Installation
+
+```bash
+python -m pip install ga-matrix
+```
+
+Development and test tools are available as extras:
+
+```bash
+python -m pip install -e ".[test]"
+python -m pip install -e ".[dev]"
+```
+
+## Quick Start
+
+```python
+from matrix import MatrixOD
+
+rows = ["A", "B"]
+cols = ["X", "Y"]
+
+od = MatrixOD(rows, cols, init={"A": {"X": 10}, "B": {"Y": 5}})
+od["A", "Y"] = 3
+
+assert od["A", "X"] == 10
+assert od.sum() == 18
+```
+
+## MatrixOD
+
+`MatrixOD` stores a 2D origin-destination matrix. Rows and columns can be passed
+as label sequences or existing label-to-position mappings.
+
+```python
+import pandas as pd
+
+from matrix import MatrixOD
+
+df = pd.DataFrame(
+    [
+        {"origin": "A", "destination": "X", "trips": 10},
+        {"origin": "B", "destination": "Y", "trips": 5},
+    ]
+)
+
+od = MatrixOD.read_df(
+    rows=["A", "B"],
+    cols=["X", "Y"],
+    df=df,
+    o_field="origin",
+    d_field="destination",
+    value_field="trips",
+)
+
+roundtrip = od.write_df(o_field="origin", d_field="destination", value_field="trips")
+```
+
+Supported operations are element-wise addition, subtraction, multiplication, and
+division with either a scalar or another matrix with the same labels.
+
+```python
+scaled = od * 1.2
+delta = scaled - od
+col_totals = od.sum(axis=0)
+row_totals = od.sum(axis=1)
+```
+
+## MatrixODT
+
+`MatrixODT` stores one `MatrixOD` per timestamp.
+
+```python
+from matrix import MatrixODT
+
+odt = MatrixODT(
+    rows=["A", "B"],
+    cols=["X", "Y"],
+    timestamps=[0, 1],
+    init={
+        0: {"A": {"X": 10}},
+        1: {"B": {"Y": 5}},
+    },
+)
+
+assert odt["A", "X", 0] == 10
+assert odt["A", "X", 99] == 0
+assert odt.sum(axis=2)["A", "X"] == 10
+```
+
+`MatrixODT.read_df()` accepts a long-form DataFrame with origin, destination,
+timestamp, and value columns. If `timestamps` is omitted, timestamp labels are
+inferred from the DataFrame in first-seen order.
+
+## LabeledMatrix
+
+`LabeledMatrix` is a more generic 2D labeled array with `.loc` and `.iloc`
+indexers:
+
+```python
+from matrix import LabeledMatrix
+
+table = LabeledMatrix(
+    [[1, 2], [3, 4]],
+    row_index=["a", "b"],
+    col_index=["x", "y"],
+)
+
+assert table.loc["b", "y"] == 4
+```
+
+## API Summary
+
+- `MatrixOD(rows, cols, init=None, copy=False, mode=None)`
+- `MatrixOD.read_df(rows, cols, df, o_field="o", d_field="d", value_field="value")`
+- `MatrixOD.read_csv(rows, cols, file, ...)`
+- `MatrixOD.write_df(...)`
+- `MatrixOD.write_csv(file, ...)`
+- `MatrixODT(rows, cols, timestamps, init=None, copy=False, mode=None)`
+- `MatrixODT.read_df(rows, cols, timestamps=None, df=None, ...)`
+- `MatrixODT.read_csv(rows, cols, file, timestamps=None, ...)`
+- `MatrixODT.write_df(...)`
+- `MatrixODT.write_csv(file, ...)`
+- `LabeledMatrix(data, row_index=..., col_index=..., dtype=None, copy=False)`
+
+## Development
+
+GA Matrix supports Python 3.10 and newer.
+
+```bash
+python -m pip install -e ".[dev]"
+python -m compileall -q src
+python -m pytest --cov=matrix --cov-report=term-missing
+ruff check .
+mypy
+python -m pip check
+python -m build
+python -m twine check dist/*
+```
+
+## Releases
+
+`src/matrix/_version.py` is the only version source. To publish a release:
+
+1. Update `__version__` in `_version.py` and commit the release changes.
+2. Push `main` and wait for CI to pass.
+3. Configure the PyPI Trusted Publisher with project `ga-matrix`, owner
+   `andreagemma`, repository `matrix`, workflow `release.yml`, and environment
+   `pypi`.
+4. Run the **Create release** GitHub Actions workflow. With no override it creates
+   the `v<version>` tag, creates release notes, and dispatches the build and PyPI
+   publication workflow.
+
+PyPI versions are immutable. Increment `_version.py` before publishing different
+content.
+
+## License
+
+GA Matrix is distributed under the MIT License. See [LICENSE](LICENSE).

ga_matrix-0.1.0/README.md

@@ -0,0 +1,170 @@
+# GA Matrix
+
+[![CI](https://github.com/andreagemma/matrix/actions/workflows/ci.yml/badge.svg)](https://github.com/andreagemma/matrix/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/ga-matrix.svg)](https://pypi.org/project/ga-matrix/)
+[![Python](https://img.shields.io/pypi/pyversions/ga-matrix.svg)](https://pypi.org/project/ga-matrix/)
+
+GA Matrix provides small NumPy-backed matrix containers with label-based access,
+long-form pandas import/export helpers, and optional timestamp support for
+origin-destination data.
+
+The PyPI distribution is named `ga-matrix`; the import package is named `matrix`.
+
+## Installation
+
+```bash
+python -m pip install ga-matrix
+```
+
+Development and test tools are available as extras:
+
+```bash
+python -m pip install -e ".[test]"
+python -m pip install -e ".[dev]"
+```
+
+## Quick Start
+
+```python
+from matrix import MatrixOD
+
+rows = ["A", "B"]
+cols = ["X", "Y"]
+
+od = MatrixOD(rows, cols, init={"A": {"X": 10}, "B": {"Y": 5}})
+od["A", "Y"] = 3
+
+assert od["A", "X"] == 10
+assert od.sum() == 18
+```
+
+## MatrixOD
+
+`MatrixOD` stores a 2D origin-destination matrix. Rows and columns can be passed
+as label sequences or existing label-to-position mappings.
+
+```python
+import pandas as pd
+
+from matrix import MatrixOD
+
+df = pd.DataFrame(
+    [
+        {"origin": "A", "destination": "X", "trips": 10},
+        {"origin": "B", "destination": "Y", "trips": 5},
+    ]
+)
+
+od = MatrixOD.read_df(
+    rows=["A", "B"],
+    cols=["X", "Y"],
+    df=df,
+    o_field="origin",
+    d_field="destination",
+    value_field="trips",
+)
+
+roundtrip = od.write_df(o_field="origin", d_field="destination", value_field="trips")
+```
+
+Supported operations are element-wise addition, subtraction, multiplication, and
+division with either a scalar or another matrix with the same labels.
+
+```python
+scaled = od * 1.2
+delta = scaled - od
+col_totals = od.sum(axis=0)
+row_totals = od.sum(axis=1)
+```
+
+## MatrixODT
+
+`MatrixODT` stores one `MatrixOD` per timestamp.
+
+```python
+from matrix import MatrixODT
+
+odt = MatrixODT(
+    rows=["A", "B"],
+    cols=["X", "Y"],
+    timestamps=[0, 1],
+    init={
+        0: {"A": {"X": 10}},
+        1: {"B": {"Y": 5}},
+    },
+)
+
+assert odt["A", "X", 0] == 10
+assert odt["A", "X", 99] == 0
+assert odt.sum(axis=2)["A", "X"] == 10
+```
+
+`MatrixODT.read_df()` accepts a long-form DataFrame with origin, destination,
+timestamp, and value columns. If `timestamps` is omitted, timestamp labels are
+inferred from the DataFrame in first-seen order.
+
+## LabeledMatrix
+
+`LabeledMatrix` is a more generic 2D labeled array with `.loc` and `.iloc`
+indexers:
+
+```python
+from matrix import LabeledMatrix
+
+table = LabeledMatrix(
+    [[1, 2], [3, 4]],
+    row_index=["a", "b"],
+    col_index=["x", "y"],
+)
+
+assert table.loc["b", "y"] == 4
+```
+
+## API Summary
+
+- `MatrixOD(rows, cols, init=None, copy=False, mode=None)`
+- `MatrixOD.read_df(rows, cols, df, o_field="o", d_field="d", value_field="value")`
+- `MatrixOD.read_csv(rows, cols, file, ...)`
+- `MatrixOD.write_df(...)`
+- `MatrixOD.write_csv(file, ...)`
+- `MatrixODT(rows, cols, timestamps, init=None, copy=False, mode=None)`
+- `MatrixODT.read_df(rows, cols, timestamps=None, df=None, ...)`
+- `MatrixODT.read_csv(rows, cols, file, timestamps=None, ...)`
+- `MatrixODT.write_df(...)`
+- `MatrixODT.write_csv(file, ...)`
+- `LabeledMatrix(data, row_index=..., col_index=..., dtype=None, copy=False)`
+
+## Development
+
+GA Matrix supports Python 3.10 and newer.
+
+```bash
+python -m pip install -e ".[dev]"
+python -m compileall -q src
+python -m pytest --cov=matrix --cov-report=term-missing
+ruff check .
+mypy
+python -m pip check
+python -m build
+python -m twine check dist/*
+```
+
+## Releases
+
+`src/matrix/_version.py` is the only version source. To publish a release:
+
+1. Update `__version__` in `_version.py` and commit the release changes.
+2. Push `main` and wait for CI to pass.
+3. Configure the PyPI Trusted Publisher with project `ga-matrix`, owner
+   `andreagemma`, repository `matrix`, workflow `release.yml`, and environment
+   `pypi`.
+4. Run the **Create release** GitHub Actions workflow. With no override it creates
+   the `v<version>` tag, creates release notes, and dispatches the build and PyPI
+   publication workflow.
+
+PyPI versions are immutable. Increment `_version.py` before publishing different
+content.
+
+## License
+
+GA Matrix is distributed under the MIT License. See [LICENSE](LICENSE).

ga_matrix-0.1.0/docs/api.md

@@ -0,0 +1,66 @@
+# API Reference
+
+## `MatrixOD`
+
+```python
+MatrixOD(rows, cols, init=None, copy=False, mode=None)
+```
+
+Creates a NumPy-backed matrix addressed by row and column labels.
+
+Main methods:
+
+- `copy(copy_data=True)`
+- `transpose()`
+- `inverse()`
+- `get_diagonal()`
+- `set_diagonal(values)`
+- `nan_to_num(copy=True, nan=0.0, posinf=None, neginf=None)`
+- `sum(axis=None)`
+- `read_df(rows, cols, df, o_field="o", d_field="d", value_field="value")`
+- `read_csv(rows, cols, file, ...)`
+- `write_df(...)`
+- `write_csv(file, ...)`
+
+Arithmetic with scalars or label-aligned `MatrixOD` instances is element-wise.
+
+## `MatrixODT`
+
+```python
+MatrixODT(rows, cols, timestamps, init=None, copy=False, mode=None)
+```
+
+Creates a timestamp-indexed collection of `MatrixOD` objects. Scalar access uses
+`matrix[origin, destination, timestamp]`; timestamp access uses `matrix[timestamp]`.
+
+Main methods:
+
+- `copy(copy_data=True)`
+- `sum(axis=None)`
+- `nan_to_num(copy=True, nan=0.0, posinf=None, neginf=None)`
+- `read_df(rows, cols, timestamps=None, df=None, ...)`
+- `read_csv(rows, cols, file, timestamps=None, ...)`
+- `write_df(...)`
+- `write_csv(file, ...)`
+
+Arithmetic with scalars or label-aligned `MatrixODT` instances is element-wise.
+When two `MatrixODT` objects contain different timestamps, missing timestamps are
+treated as zero matrices.
+
+## `LabeledMatrix`
+
+```python
+LabeledMatrix(data, row_index=..., col_index=..., dtype=None, copy=False)
+```
+
+Creates a generic labeled 2D NumPy array. Use direct indexing for scalar access,
+`.loc` for label-based indexing, and `.iloc` for position-based indexing.
+
+Main methods:
+
+- `from_dict_of_dicts(data, dtype=None, row_order=None, col_order=None, fill_value=0)`
+- `reindex(rows=None, cols=None, fill_value=0)`
+- `rename(rows=None, cols=None)`
+- `tolist()`
+- `to_numpy(copy=False)`
+- `to_pandas()`

ga_matrix-0.1.0/docs/index.md

@@ -0,0 +1,8 @@
+# GA Matrix Documentation
+
+GA Matrix contains lightweight matrix containers for label-based origin-destination
+data.
+
+- See [API Reference](api.md) for the public classes and methods.
+- See the project [README](../README.md) for installation, quick start, and release
+  instructions.

ga_matrix-0.1.0/pyproject.toml

@@ -0,0 +1,86 @@
+[build-system]
+requires = ["setuptools>=77", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ga-matrix"
+dynamic = ["version"]
+description = "Label-aware origin-destination matrix utilities built on NumPy and pandas."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+  { name = "GA Matrix contributors" }
+]
+keywords = ["ga-matrix", "matrix", "origin-destination", "numpy", "pandas"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Typing :: Typed"
+]
+dependencies = [
+  "numpy>=1.24",
+  "pandas>=2.0"
+]
+
+[project.optional-dependencies]
+test = [
+  "pytest>=8.0",
+  "pytest-cov>=5.0"
+]
+dev = [
+  "build>=1.2",
+  "mypy>=1.10",
+  "pytest>=8.0",
+  "pytest-cov>=5.0",
+  "ruff>=0.5",
+  "twine>=5.1"
+]
+
+[project.urls]
+Documentation = "https://github.com/andreagemma/matrix#readme"
+Issues = "https://github.com/andreagemma/matrix/issues"
+Source = "https://github.com/andreagemma/matrix"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+matrix = ["py.typed"]
+
+[tool.setuptools.dynamic]
+version = {attr = "matrix._version.__version__"}
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra --strict-markers"
+
+[tool.coverage.run]
+branch = true
+source = ["matrix"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+
+[tool.mypy]
+python_version = "3.10"
+files = ["src"]
+warn_unused_configs = true
+check_untyped_defs = true
+follow_imports = "skip"
+no_site_packages = true
+ignore_missing_imports = true

ga_matrix-0.1.0/setup.cfg

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