mat-summarize 0.0.1__py3-none-any.whl

mat_summarize-0.0.1.dist-info/METADATA

@@ -0,0 +1,206 @@
+Metadata-Version: 2.5
+Name: mat-summarize
+Version: 0.0.1
+Summary: A package of methods to summarize MATs
+Project-URL: Homepage, https://github.com/RepresentantativeMAT/mat-summarization
+Project-URL: Issues, https://github.com/RepresentantativeMAT/mat-summarization/issues
+Author-email: Jonathan Roberto Fragoso Bonatto <jonrfbonatto@gmail.com>, Vanessa Lago Machado <vanessalagomachado@gmail.com>
+License-Expression: GPL-3.0-only
+License-File: LICENSE
+Requires-Python: >=3.9
+Requires-Dist: numpy>=2.0
+Requires-Dist: pandas>=2.2
+Requires-Dist: scipy>=1.14
+Description-Content-Type: text/markdown
+
+# MAT-data: Multiple Aspect Trajectory Summarization Modeling (MAT-SG & MAT-SGT)
+
+This repository contains the Python implementation for **Multiple Aspect Trajectory Summarization** algorithms. Initially based on Java, the **MAT-SG** (Multiple-Aspect Trajectories based on a spatial Grid) and **MAT-SGT** (Multi-Aspect Trajectories Based on Spatio-Temporal Segmentation) models were rewritten and optimized in object-oriented Python under the **Template Method** design pattern aiming at processing massive data of enriched trajectories.
+
+## 📌 Project Overview
+
+The central goal of this library is to reduce large volumes of trajectory points while maintaining spatial, temporal, and semantic fidelity through the agglomeration and definition of representative points that carry proportional semantics (e.g., Weather, POI locations, Prices, etc.).
+
+The semantic accumulation supports fusion of both **Numerical** variables that generate average scores via median, and **Categorical** variables, preserving the weighted/proportional distribution of values within the consolidated clusters.
+
+### 📍 Available Algorithm Patterns
+
+There are two fundamental variations of spatial analysis applied to this model. For a complete theoretical foundation, access the [Approaches (MAT-SG vs MAT-SGT)](docs/approaches.md) guide.
+
+1. **MAT-SG**: (Multiple-Aspect Trajectories based on a spatial Grid) agglomerates elements limited only to the **Spatial** threshold and grid, and fuses the semantics to generate mathematically calculated representative centroid points, discarding excessive points (`outliers`).
+2. **MAT-SGT**: (Multi-Aspect Trajectories Based on Spatio-Temporal Segmentation) also adds the **Temporal** threshold, partitioning sub-cells that besides being spatially close, also co-exist in the same contiguous time interval partition of the day, grouping sub-intervals that compose time and space (`STI - Spatial-Temporal Intervals`).
+
+---
+
+## 🏗 Repository Structure and Architecture
+
+The repository is architected following clean formal patterns focused on the **Template Method**. For a deep dive into the separation technique, refer to the [Architecture and Inheritance](docs/architecture.md) documentation.
+
+### Class Architecture (Template Method)
+
+```mermaid
+classDiagram
+    %% Core Algorithms (Method)
+    class MATSummarize {
+        <<abstract>>
+        # _trc: float
+        # _trv: float
+        # _points_in_cell: list
+        # _representative_trajectory: MultipleAspectTrajectory
+        + load()
+        + _compute_min_spatial_threshold()
+        + _allocate_points_in_grid()
+        + _fuse_aspects()
+        + _summarize_numerical_aspects()
+        + _summarize_categorical_aspects()
+        + execute() final
+        # process_cell_points(points, cell_id) *abstract*
+    }
+
+    class MATSGT {
+        - _compute_stis(times)
+        - _filter_outlier_differences()
+        - _create_centroids_from_stis()
+        # process_cell_points(points, cell_id) *override*
+    }
+
+    class MATSG {
+        - _define_ranking_temporal()
+        # process_cell_points(points, cell_id) *override*
+    }
+
+    %% Data Enitites (Model)
+    class MultipleAspectTrajectory {
+        + str trajectory_id
+        + list pointList
+    }
+
+    class Centroid {
+        + tuple cellReference
+        + STI sti
+        + addAttrValue()
+    }
+
+    class Point {
+        + float lat
+        + float lon
+        + TemporalAspect time
+    }
+    
+    class TemporalAspect {
+        + datetime startTime
+        + datetime endTime
+    }
+
+    class AttributeValue {
+        + any value
+    }
+
+    class SemanticAspect {
+        + str name
+        + SemanticType type
+    }
+
+    %% Inheritances and Relationships
+    MATSummarize <|-- MATSGT
+    MATSummarize <|-- MATSG
+    
+    MATSummarize --> MultipleAspectTrajectory : Populates
+    MultipleAspectTrajectory *-- Point : Contains 1..*
+    Centroid --|> Point : Extends
+    Point --> TemporalAspect : Has
+    Centroid *--> TemporalAspect : Has Multiple
+    Point *-- AttributeValue : Has Multiple
+    AttributeValue --> SemanticAspect : Maps to
+```
+
+### Directory Layout
+
+```text
+/
+├── README.md            # Entry point project documentation
+├── docs/                # Extended project documentation (approaches and architecture guides)
+├── logs/                # Directory reserved for execution streams and debugging
+├── data/                # Local datasets manipulation
+│   ├── input/           # CSV spreadsheet repository for raw modeling
+│   └── output/          # Representative trajectories extracted by the model (.csv)
+├── method/              # Contains the clustering and summarization methods logic
+│   ├── MATSummarize.py  # Base Abstract Class (Template Method Pattern)
+│   ├── MATSG.py         # Subclass applying Spatial heuristics
+│   ├── MATSGT.py        # Subclass adding partitioning via Time STIs
+│   └── MUITAS.py        # Algorithmic univariate scoring calculations
+├── model/               # Structural and Geometric Models
+│   ├── AttributeValue.py# Embedded dictionaries of <Aspect:Value> (e.g., {WEATHER: "CLOUDS"})
+│   ├── Centroid.py      # Groups Space-Time cuts
+│   ├── Point.py         # Abstract elements of raw Lat/Lon 
+│   ├── SemanticAspect.py# Dimensional treatment
+│   ├── TemporalAspect.py# Datetime utility wrapper 
+│   └── Util.py          # Global Euclidean distances and cKDTree mappings
+└── execution/           # Entry Point and Main Runner
+    └── runner.py        # Local script orchestrator
+```
+
+---
+
+## 🚀 How to Install and Run
+
+**Prerequisites**:
+*   Python 3.10+
+*   Libraries from `requirements.txt` (Ex: `pandas`, `numpy`, `scipy`)
+
+**1. Clone and Prepare the Environment**
+```bash
+git clone https://github.com/RepresentantativeMAT/mat-summarization.git
+pip install -r requirements.txt
+```
+
+**2. Running a Quick Test (`runner.py`)**
+
+A mock test environment and base orchestration are prepared in the `execution/` folder. It points the extractions directly to the input and output reciprocals of the `data/` folder.
+
+```python
+# In execution/runner.py
+from method.MATSGT import MATSGT
+
+# 1. Instantiate the class pointing the datasets dynamically
+model_sgt = MATSGT(
+    trc=0.25,
+    trv=0.25,
+    path=os.path.join(INPUT_DIR, 'Running_Example_v5.csv')
+)
+
+# 2. Execute the method passing base traits and dump location
+model_sgt.execute(
+    lst_categorical_pd=['price'],  # columns forced to act as discrete string
+    values_null=[-1, -999],        # Null/empty values of your raw dataset 
+    pattern_date_input='?',        # Date regex/patterns or ? for default full-day minute format (24h)
+    dir=f"{OUTPUT_DIR}/", # Automatic directory resolved by the OS for dump         
+    file='teste_saida',
+    rc=0.25,
+    trv=0.25,
+    ignore_columns=None
+)
+```
+
+**3. Resulting Output**
+The execution will export the dataset history under a CSV document:
+`teste_saida rc 25 rv 25 - zX.csv` 
+
+Upon opening it, it will display the list of points condensed numerically and temporally (with dict-like markings for varied attributes such as `{23:20 - 23:30 prop: 0.33}`). The header will detail the Method used, Coverage, and the amount of Reduction executed over the input root sample.
+
+---
+
+## 🛠️ Recent Refactoring Contributions (Changelog)
+
+-   Architectural migration based purely on base **Classic Python (`snake_case`)** OOP, eliminating legacy Java *camelCase* fragments;
+-   Integration of the **Template Method** encapsulation Pattern concentrating inheritance and abstraction in the parent file *`MATSummarize.py`*, reducing redundant code by >50%;
+-   Fixed the `Java Skip Indexing` bug, refining the accuracy with what the Outlier Removal Process eliminates (where before they were accidentally spared);
+-   100% reliable adherence to probability normalization to yield a real-mathematical `sum = 1.0`.
+-   Removal of Dead Code through scanning (`Vulture` specs).
+
+## 📄 Model Authors / Contact
+This research was partially funded by SoBigData++ Project - by Transnational Access (TNA),as well as the European Union’s Horizon 2020 research and inno-vation programme under GA N. 777695 (EU Project MASTER -Multiple ASpects TrajEctoRy management and analysis), until 2024. In present, the researcher is referenced in **Análise Avançada de Dados de Trajetórias: Uma ferramenta visual para identificação de padrões em dados de Mobilidade** project. Developed with academic support and adaptation via IFSUL and original MAT-data repository.
+
+For formal and architectural in-depth understanding based on the original research articles, refer to:
+- **MAT-SG ([Springer Link](https://link.springer.com/chapter/10.1007/978-3-031-12423-5_33))**: *Multiple-Aspect Trajectory Summarization based on a spatial Grid*
+- **MAT-SGT ([JIDM](https://journals-sol.sbc.org.br/index.php/jidm/article/view/4110))**: *Multiple-Aspect Trajectory Summarization via Grid and Time*

mat_summarize-0.0.1.dist-info/RECORD

@@ -0,0 +1,21 @@
+nome/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+nome/method/FeatureAggregator.py,sha256=LbuUEFunhC2aLiD3RY4wHU2nYlCLYlzkXj9Nf6k2hhk,3547
+nome/method/MATSG.py,sha256=4AfTZgvA8euZvU6dDGTDzPBt9xWB-wHwR0suhvHdOUc,4013
+nome/method/MATSGT.py,sha256=rm0OKO6N4hugu4VvQMnwR3rdu9XGlklof9ZOBjXqtgs,3638
+nome/method/MATSummarize.py,sha256=M8q6SGCKIVQQ9HnKG_P7TnySdW4VH6JrufOBcVA9UrU,21665
+nome/method/MUITAS.py,sha256=httsdAfk7NZJBGCbqT9xJuhbUlBIewo6X56xGjhnGWg,5947
+nome/method/__init__.py,sha256=sXQEt0Gcu1rt48QYsbAwgh8dUInBzDIh1ZWbhXUoljU,222
+nome/model/Centroid.py,sha256=AhVc-oJ0o8Sy8DFYfntcF_izF8ql8YFwyC_WU-dnoQw,4169
+nome/model/Feature.py,sha256=Ky7lurLMK6TXEnG5N4740H8TpfHLllMSBWNv24tNp04,1064
+nome/model/MultipleAspectTrajectory.py,sha256=l1qYTjMVEiKim5m5jD4BB9BBj-MdEDwbQ9x-edtcFUU,2518
+nome/model/Point.py,sha256=X8T1ak2biNUpnI5vLWaO6FinLS_stqAmIAopeYDz5Xg,5143
+nome/model/STI.py,sha256=3VZSbN1VX9JvTxRbpEkL7r-oKb9pbdOohUoIExkPVRA,2350
+nome/model/SemanticAspect.py,sha256=2BIEfAaeKAV-dWAXpyaBoCQ5mzUkry3eOoDKies6YBA,1398
+nome/model/SemanticType.py,sha256=rMYHqaQBpoD0xTRJiv6Tw9QFthp4uZXEEUgRsIpvJvk,559
+nome/model/TemporalAspect.py,sha256=P3EQJrVJnSJQohEeL3FJYxJ3CtTyRR-_p6FByd9ovYg,2604
+nome/model/Util.py,sha256=uH4XMJWLOFvrw7KUTQEa1kfZZLG6eAor3Py8eikuYEw,1162
+nome/model/__init__.py,sha256=r6nVVTSq-Fp7Jelv9X6ceP-yVuPf0x_3ftlCTmMeMHM,446
+mat_summarize-0.0.1.dist-info/METADATA,sha256=y5QbFcYwXlqxBxCdw8OzcupWdWZZDgZ62Ry-GSdAboY,9622
+mat_summarize-0.0.1.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+mat_summarize-0.0.1.dist-info/licenses/LICENSE,sha256=IwGE9guuL-ryRPEKi6wFPI_zOhg7zDZbTYuHbSt_SAk,35823
+mat_summarize-0.0.1.dist-info/RECORD,,

mat_summarize-0.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any