temporal-normalization-spacy 1.0.0__tar.gz

temporal_normalization_spacy-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Ilie
+
+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.

temporal_normalization_spacy-1.0.0/MANIFEST.in

@@ -0,0 +1,6 @@
+include README.md
+include temporal_normalization/libs/temporal-normalization-1.6.jar
+
+recursive-include temporal_normalizer/commons *
+recursive-include temporal_normalizer/libs *
+recursive-include temporal_normalizer *

temporal_normalization_spacy-1.0.0/PKG-INFO

@@ -0,0 +1,251 @@
+Metadata-Version: 2.2
+Name: temporal_normalization_spacy
+Version: 1.0.0
+Summary: A spaCy plugin for identifying and parsing historical data in Romanian texts
+Home-page: https://github.com/iliedorobat/timespan-normalization-spacy
+Author: Ilie Cristian Dorobat
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.6
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: spacy>=3.0
+Requires-Dist: py4j
+Requires-Dist: langdetect
+Dynamic: author
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# Temporal Expressions Normalization spaCy (TeNs)
+
+<b>Temporal Expressions Normalization spaCy (TeNs)</b> is a powerful pipeline component for spaCy that seamlessly
+identifies and parses date entities in text. It leverages the <b>[Temporal Normalization Framework](
+https://github.com/iliedorobat/timespan-normalization)</b> to recognize a wide variety of date formats using an
+extensive set of regular expressions (RegEx), ensuring robust and adaptable date extraction across diverse
+textual sources.
+
+Unlike conventional solutions that primarily focus on well-structured date formats, TeNs excels in handling
+real-world text by <b>identifying</b> not only standard date representations but also <b>abbreviated, informal, or even
+misspelled temporal expressions.</b> This makes it particularly effective for processing noisy or unstructured data,
+such as historical records, user-generated content, and scanned documents with OCR inaccuracies.
+
+Moreover, TeNs is designed to <b>integrate seamlessly into existing NLP pipelines,</b> allowing for enhanced temporal
+information processing in tasks such as event extraction, timeline construction, and knowledge graph population.
+By providing a flexible and accurate approach to temporal data normalization, it significantly improves the
+quality and reliability of date-related information extracted from text.
+
+<b>Table I.</b> Types of temporal expressions which can be processed
+<table>
+    <tr>
+        <th>Type of Temporal Expressions</th>
+        <th>Examples of Temporal Expressions*</th>
+    </tr>
+    <tr>
+        <td>dates</td>
+        <td>
+            YMD: 1881-08-31; 1857 mai 10; etc.<br/>
+            DMY: 09.11.1518; 1 noiembrie 1624; etc.<br/>
+            MY: ianuarie 632; etc.
+        </td>
+    </tr>
+    <tr>
+        <td>timespans</td>
+        <td>
+            centuries: s:; sc; se.; sec; sec.; secol; secolele; secolul; sex.<br/>
+            millenniums: mil; mil.; mileniul; mileniului; mileniile
+        </td>
+    </tr>
+    <tr>
+        <td>years</td>
+        <td>77; 78; 1652; [1873]; aproximativ 1834; cca. 1420; etc.</td>
+    </tr>
+</table>
+* The values are mentioned in the reference language – Romanian language
+
+
+
+## Getting started
+To integrate TeNs into spaCy pipelines you need the following:
+
+### Prerequisites
+- Python 3.x
+- JRE 11+
+- spaCy 3.x
+- py4j 0.10.9.9
+- langdetect 1.0.9
+
+1. Install python packages:
+```bash
+    pip install -r requirements.txt
+```
+
+2. Install [JDK 11](https://www.oracle.com/nl/java/technologies/javase/jdk11-archive-downloads.html) or [OpenJDK 11](https://openjdk.org/install/) (or newer versions)
+
+
+### Install
+```bash
+    pip install temporal-spacy
+```
+
+### Supported languages
+- [Romanian](https://universaldependencies.org/tagset-conversion/ro-multext-uposf.html)
+
+
+
+## Usage
+*** 
+
+### Importing Modules & Defining Constants
+
+```python
+import subprocess
+
+import spacy
+
+from temporal_normalization.commons.print_utils import console
+from temporal_normalization.index import create_normalized_component, TemporalNormalization  ## noqa: F401
+
+LANG = "ro"
+MODEL = "ro_core_news_sm"
+TEXT_RO = ("Sec al II-lea a.ch. a fost o perioadă de mari schimbări. "
+           "În secolul XX, tehnologia a avansat semnificativ. "
+           "Sec. 21 este adesea asociat cu globalizarea rapidă.")
+```
+
+### Adding the Component to spaCy Pipeline
+```python
+    # Display a warning if the language of the text is not Romanian.
+console.lang_warning(TEXT_RO, target_lang=LANG)
+
+try:
+    # Load the spaCy model if it has already been downloaded
+    nlp = spacy.load(MODEL)
+except OSError:
+    console.warning(f'Started downloading {MODEL}...')
+    # Download the Romanian model if it wasn't already downloaded
+    subprocess.run(["python", "-m", "spacy", "download", MODEL])
+    # Load the spaCy model
+    nlp = spacy.load(MODEL)
+
+# Add "temporal_normalization" component to the spaCy pipeline
+nlp.add_pipe("temporal_normalization", last=True)
+```
+
+### Processing Text with the Pipeline
+```python
+doc = nlp(TEXT_RO)
+
+# Display NLP-specific linguistic annotations
+console.tokens_table(doc)
+print()
+```
+
+### Accessing the Parsed Temporal Expressions
+```python
+# Display information about the identified and normalized dates in the text.
+for entity in doc.ents:
+    for edge in entity._.normalized.edges:
+        print(edge.serialize())
+        print()
+
+    print("Periods:")
+    for period in entity._.normalized.periods:
+        print(period.serialize("\t"))
+        print()
+```
+
+### Result
+#### First Sentence
+```text
+Start time:
+	Matched value: Sec al II-lea a.ch.
+	Matched Type: century
+	Normalized label: 2nd century BC
+	DBpedia uri: https://dbpedia.org/page/2nd_century_BC
+End time:
+	Matched value: Sec al II-lea a.ch.
+	Matched Type: century
+	Normalized label: 2nd century BC
+	DBpedia uri: https://dbpedia.org/page/2nd_century_BC
+
+Periods:
+	Matched value: Sec al II-lea a.ch.
+	Matched Type: century
+	Normalized label: 1st millennium BC
+	DBpedia uri: https://dbpedia.org/page/1st_millennium_BC
+
+	Matched value: Sec al II-lea a.ch.
+	Matched Type: century
+	Normalized label: 2nd century BC
+	DBpedia uri: https://dbpedia.org/page/2nd_century_BC
+```
+
+#### Second Sentence
+```text
+Start time:
+	Matched value: secolul XX
+	Matched Type: century
+	Normalized label: 20th century
+	DBpedia uri: https://dbpedia.org/page/20th_century
+End time:
+	Matched value: secolul XX
+	Matched Type: century
+	Normalized label: 20th century
+	DBpedia uri: https://dbpedia.org/page/20th_century
+
+Periods:
+	Matched value: secolul XX
+	Matched Type: century
+	Normalized label: 2nd millennium
+	DBpedia uri: https://dbpedia.org/page/2nd_millennium
+
+	Matched value: secolul XX
+	Matched Type: century
+	Normalized label: 20th century
+	DBpedia uri: https://dbpedia.org/page/20th_century
+```
+
+#### Third Sentence
+```text
+Start time:
+	Matched value: Sec. 21
+	Matched Type: century
+	Normalized label: 21st century
+	DBpedia uri: https://dbpedia.org/page/21st_century
+End time:
+	Matched value: Sec. 21
+	Matched Type: century
+	Normalized label: 21st century
+	DBpedia uri: https://dbpedia.org/page/21st_century
+
+Periods:
+	Matched value: Sec. 21
+	Matched Type: century
+	Normalized label: 3rd millennium
+	DBpedia uri: https://dbpedia.org/page/3rd_millennium
+
+	Matched value: Sec. 21
+	Matched Type: century
+	Normalized label: 21st century
+	DBpedia uri: https://dbpedia.org/page/21st_century
+```
+
+
+
+## Publications
+ECAI 2021: [The Power of Regular Expressions in Recognizing Dates and Epochs (2021)](https://ieeexplore.ieee.org/document/9515139)
+```
+@inproceedings{9515139,
+  author={Dorobăț, Ilie Cristian and Posea, Vlad},
+  booktitle={2021 13th International Conference on Electronics, Computers and Artificial Intelligence (ECAI)}, 
+  title={The Power of Regular Expressions in Recognizing Dates and Epochs}, 
+  year={2021},
+  pages={1-3},
+  doi={10.1109/ECAI52376.2021.9515139}}
+```

temporal_normalization_spacy-1.0.0/README.md

@@ -0,0 +1,227 @@
+# Temporal Expressions Normalization spaCy (TeNs)
+
+<b>Temporal Expressions Normalization spaCy (TeNs)</b> is a powerful pipeline component for spaCy that seamlessly
+identifies and parses date entities in text. It leverages the <b>[Temporal Normalization Framework](
+https://github.com/iliedorobat/timespan-normalization)</b> to recognize a wide variety of date formats using an
+extensive set of regular expressions (RegEx), ensuring robust and adaptable date extraction across diverse
+textual sources.
+
+Unlike conventional solutions that primarily focus on well-structured date formats, TeNs excels in handling
+real-world text by <b>identifying</b> not only standard date representations but also <b>abbreviated, informal, or even
+misspelled temporal expressions.</b> This makes it particularly effective for processing noisy or unstructured data,
+such as historical records, user-generated content, and scanned documents with OCR inaccuracies.
+
+Moreover, TeNs is designed to <b>integrate seamlessly into existing NLP pipelines,</b> allowing for enhanced temporal
+information processing in tasks such as event extraction, timeline construction, and knowledge graph population.
+By providing a flexible and accurate approach to temporal data normalization, it significantly improves the
+quality and reliability of date-related information extracted from text.
+
+<b>Table I.</b> Types of temporal expressions which can be processed
+<table>
+    <tr>
+        <th>Type of Temporal Expressions</th>
+        <th>Examples of Temporal Expressions*</th>
+    </tr>
+    <tr>
+        <td>dates</td>
+        <td>
+            YMD: 1881-08-31; 1857 mai 10; etc.<br/>
+            DMY: 09.11.1518; 1 noiembrie 1624; etc.<br/>
+            MY: ianuarie 632; etc.
+        </td>
+    </tr>
+    <tr>
+        <td>timespans</td>
+        <td>
+            centuries: s:; sc; se.; sec; sec.; secol; secolele; secolul; sex.<br/>
+            millenniums: mil; mil.; mileniul; mileniului; mileniile
+        </td>
+    </tr>
+    <tr>
+        <td>years</td>
+        <td>77; 78; 1652; [1873]; aproximativ 1834; cca. 1420; etc.</td>
+    </tr>
+</table>
+* The values are mentioned in the reference language – Romanian language
+
+
+
+## Getting started
+To integrate TeNs into spaCy pipelines you need the following:
+
+### Prerequisites
+- Python 3.x
+- JRE 11+
+- spaCy 3.x
+- py4j 0.10.9.9
+- langdetect 1.0.9
+
+1. Install python packages:
+```bash
+    pip install -r requirements.txt
+```
+
+2. Install [JDK 11](https://www.oracle.com/nl/java/technologies/javase/jdk11-archive-downloads.html) or [OpenJDK 11](https://openjdk.org/install/) (or newer versions)
+
+
+### Install
+```bash
+    pip install temporal-spacy
+```
+
+### Supported languages
+- [Romanian](https://universaldependencies.org/tagset-conversion/ro-multext-uposf.html)
+
+
+
+## Usage
+*** 
+
+### Importing Modules & Defining Constants
+
+```python
+import subprocess
+
+import spacy
+
+from temporal_normalization.commons.print_utils import console
+from temporal_normalization.index import create_normalized_component, TemporalNormalization  ## noqa: F401
+
+LANG = "ro"
+MODEL = "ro_core_news_sm"
+TEXT_RO = ("Sec al II-lea a.ch. a fost o perioadă de mari schimbări. "
+           "În secolul XX, tehnologia a avansat semnificativ. "
+           "Sec. 21 este adesea asociat cu globalizarea rapidă.")
+```
+
+### Adding the Component to spaCy Pipeline
+```python
+    # Display a warning if the language of the text is not Romanian.
+console.lang_warning(TEXT_RO, target_lang=LANG)
+
+try:
+    # Load the spaCy model if it has already been downloaded
+    nlp = spacy.load(MODEL)
+except OSError:
+    console.warning(f'Started downloading {MODEL}...')
+    # Download the Romanian model if it wasn't already downloaded
+    subprocess.run(["python", "-m", "spacy", "download", MODEL])
+    # Load the spaCy model
+    nlp = spacy.load(MODEL)
+
+# Add "temporal_normalization" component to the spaCy pipeline
+nlp.add_pipe("temporal_normalization", last=True)
+```
+
+### Processing Text with the Pipeline
+```python
+doc = nlp(TEXT_RO)
+
+# Display NLP-specific linguistic annotations
+console.tokens_table(doc)
+print()
+```
+
+### Accessing the Parsed Temporal Expressions
+```python
+# Display information about the identified and normalized dates in the text.
+for entity in doc.ents:
+    for edge in entity._.normalized.edges:
+        print(edge.serialize())
+        print()
+
+    print("Periods:")
+    for period in entity._.normalized.periods:
+        print(period.serialize("\t"))
+        print()
+```
+
+### Result
+#### First Sentence
+```text
+Start time:
+	Matched value: Sec al II-lea a.ch.
+	Matched Type: century
+	Normalized label: 2nd century BC
+	DBpedia uri: https://dbpedia.org/page/2nd_century_BC
+End time:
+	Matched value: Sec al II-lea a.ch.
+	Matched Type: century
+	Normalized label: 2nd century BC
+	DBpedia uri: https://dbpedia.org/page/2nd_century_BC
+
+Periods:
+	Matched value: Sec al II-lea a.ch.
+	Matched Type: century
+	Normalized label: 1st millennium BC
+	DBpedia uri: https://dbpedia.org/page/1st_millennium_BC
+
+	Matched value: Sec al II-lea a.ch.
+	Matched Type: century
+	Normalized label: 2nd century BC
+	DBpedia uri: https://dbpedia.org/page/2nd_century_BC
+```
+
+#### Second Sentence
+```text
+Start time:
+	Matched value: secolul XX
+	Matched Type: century
+	Normalized label: 20th century
+	DBpedia uri: https://dbpedia.org/page/20th_century
+End time:
+	Matched value: secolul XX
+	Matched Type: century
+	Normalized label: 20th century
+	DBpedia uri: https://dbpedia.org/page/20th_century
+
+Periods:
+	Matched value: secolul XX
+	Matched Type: century
+	Normalized label: 2nd millennium
+	DBpedia uri: https://dbpedia.org/page/2nd_millennium
+
+	Matched value: secolul XX
+	Matched Type: century
+	Normalized label: 20th century
+	DBpedia uri: https://dbpedia.org/page/20th_century
+```
+
+#### Third Sentence
+```text
+Start time:
+	Matched value: Sec. 21
+	Matched Type: century
+	Normalized label: 21st century
+	DBpedia uri: https://dbpedia.org/page/21st_century
+End time:
+	Matched value: Sec. 21
+	Matched Type: century
+	Normalized label: 21st century
+	DBpedia uri: https://dbpedia.org/page/21st_century
+
+Periods:
+	Matched value: Sec. 21
+	Matched Type: century
+	Normalized label: 3rd millennium
+	DBpedia uri: https://dbpedia.org/page/3rd_millennium
+
+	Matched value: Sec. 21
+	Matched Type: century
+	Normalized label: 21st century
+	DBpedia uri: https://dbpedia.org/page/21st_century
+```
+
+
+
+## Publications
+ECAI 2021: [The Power of Regular Expressions in Recognizing Dates and Epochs (2021)](https://ieeexplore.ieee.org/document/9515139)
+```
+@inproceedings{9515139,
+  author={Dorobăț, Ilie Cristian and Posea, Vlad},
+  booktitle={2021 13th International Conference on Electronics, Computers and Artificial Intelligence (ECAI)}, 
+  title={The Power of Regular Expressions in Recognizing Dates and Epochs}, 
+  year={2021},
+  pages={1-3},
+  doi={10.1109/ECAI52376.2021.9515139}}
+```

temporal_normalization_spacy-1.0.0/setup.cfg

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

temporal_normalization_spacy-1.0.0/setup.py

@@ -0,0 +1,27 @@
+from setuptools import setup, find_packages
+
+setup(
+    name="temporal_normalization_spacy",
+    version="1.0.0",
+    author="Ilie Cristian Dorobat",
+    description="A spaCy plugin for identifying and parsing historical data in Romanian texts",
+    long_description=open("README.md").read(),
+    long_description_content_type="text/markdown",
+    url="https://github.com/iliedorobat/timespan-normalization-spacy",
+    packages=find_packages(),
+    include_package_data=True,
+    package_data={
+        "temporal_normalization.libs": ["temporal-normalization-1.6.jar"],
+    },
+    install_requires=[
+        "spacy>=3.0",
+        "py4j",
+        "langdetect"
+    ],
+    classifiers=[
+        "Programming Language :: Python :: 3",
+        "License :: OSI Approved :: MIT License",
+        "Operating System :: OS Independent",
+    ],
+    python_requires=">=3.6",
+)

temporal_normalization_spacy-1.0.0/temporal_normalization/__init__.py

@@ -0,0 +1,5 @@
+from .commons.print_utils import *
+from .commons.temporal_models import *
+from .commons.temporal_types import *
+from .process.java_process import *
+from .index import TemporalNormalization

temporal_normalization_spacy-1.0.0/temporal_normalization/commons/__init__.py

@@ -0,0 +1,3 @@
+from .print_utils import *
+from .temporal_models import *
+from .temporal_types import *

temporal_normalization_spacy-1.0.0/temporal_normalization/commons/print_utils.py

@@ -0,0 +1,98 @@
+from datetime import datetime
+
+from langdetect import detect
+
+
+# https://godoc.org/github.com/whitedevops/colors
+class COLORS:
+    BLUE = "\033[34m"
+    CYAN = "\033[36m"
+    LIGHT_CYAN = "\033[96m"
+    LIGHT_YELLOW = "\033[93m"
+    LIGHT_RED = "\033[91m"
+    RED = "\033[31m"
+    RESET_ALL = '\033[0m'
+
+
+# https://stackoverflow.com/questions/287871/how-to-print-colored-text-in-python#answer-287944
+class console:
+    @staticmethod
+    def display(message: str, color: str, alert: str, show_time: bool = True):
+        if show_time:
+            print(f'{color}{datetime.now().replace(microsecond=0)} {alert}: {message}{COLORS.RESET_ALL}')
+        else:
+            print(f'{color}{message}{COLORS.RESET_ALL}')
+
+    @staticmethod
+    def debug(message: str, show_time: bool = True):
+        console.display(message, COLORS.CYAN, "DEBUG", show_time)
+
+    @staticmethod
+    def log(message: str, show_time: bool = True):
+        console.display(message, COLORS.BLUE, "LOG", show_time)
+
+    @staticmethod
+    def info(message: str, show_time: bool = True):
+        console.display(message, COLORS.LIGHT_CYAN, "INFO", show_time)
+
+    @staticmethod
+    def warning(message: str, show_time: bool = True):
+        console.display(message, COLORS.LIGHT_YELLOW, "WARNING", show_time)
+
+    @staticmethod
+    def error(message: str, show_time: bool = True):
+        console.display(message, COLORS.RED, "ERROR", show_time)
+
+    @staticmethod
+    def lang_warning(query: str, target_lang: str):
+        if detect(query) != target_lang:
+            console.warning(
+                f'Detected language: "{detect(query)}" but required: "{target_lang}"'
+            )
+    @staticmethod
+    def tokens_table(document):
+        console.info(
+            f'-------------------------------------------------------------------------------------------------------'
+            f'\n{"Token":{15}}|{"Lemma":{15}}|{"POS":{10}}|{"TAG":{10}}|'
+            f'{"DEP":{10}}|{"shape_":{15}}|{"is_alpha":{10}}',
+            show_time=False
+        )
+        console.info(
+            '-------------------------------------------------------------------------------------------------------',
+            show_time=False
+        )
+        for token in document:
+            console.info(
+                f'{token.text:{15}}|{token.lemma_:{15}}|{token.pos_:{10}}|{token.tag_:{10}}|{token.dep_:{10}}|'
+                f'{token.shape_:{15}}|{token.is_alpha:{10}}',
+                show_time=False
+            )
+        console.info(
+            '-------------------------------------------------------------------------------------------------------',
+            show_time=False
+        )
+        console.info(f'sentence: {document}', show_time=False)
+
+    @staticmethod
+    def deps_list(document):
+        separator = ''
+        for i in range(130):
+            separator += '-'
+
+        console.info(
+            f'{separator}\n'
+            f'  '
+            f'{"Token":{15}}|{"Governor":{10}}|{"Root Node":{10}}|'
+            f'{"Lefts":{20}}|{"Rights":{20}}|'
+            f'{"Lemma":{15}}|{"POS":{10}}|{"TAG":{10}}|{"DEP":{10}}'
+        )
+        console.info(separator)
+        for token in document:
+            console.info(
+                f'  '
+                f'{token.text:{15}}|{token.head.text:{10}}|{str(token == token.head):{10}}|'
+                f'{str(list(token.lefts)):{20}}|{str(list(token.rights)):{20}}|'
+                f'{token.lemma_:{15}}|{token.pos_:{10}}|{token.tag_:{10}}|{token.dep_:{10}}'
+            )
+        console.info(separator)
+        console.info(f'sentence: {document}')

temporal_normalization_spacy-1.0.0/temporal_normalization/commons/temporal_models.py

@@ -0,0 +1,105 @@
+import json
+from py4j.java_gateway import JavaObject
+
+from temporal_normalization.commons.temporal_types import TemporalType
+
+
+class TemporalExpression:
+    """
+    A model representing a temporal expression, extracted and processed from a Java object.
+
+    Attributes:
+        is_valid (bool): A flag that specifies whether the text processed through timespan-normalization library is a temporal expression.
+        initial (str or None): The original temporal expression before processing.
+        edges (list[EdgeModel]): A list of temporal intervals represented as edges.
+        periods (list[DBpediaModel]): A list of normalized DBpedia entities extracted from the expression.
+        matches (list[str]): A unique list of matched values found in the normalized entities.
+    """
+
+    def __init__(self, java_object: JavaObject):
+        serialize = java_object.serialize()
+        json_obj = json.loads(serialize)
+
+        self.is_valid = TemporalExpression.is_valid_json(json_obj)
+        self.initial: str | None = json_obj["initial"] if self.is_valid else None
+        self.edges: list[EdgeModel] = [
+            EdgeModel(item) for item in json_obj["edges"]
+        ] if self.is_valid else []
+        self.periods: list[DBpediaModel] = [
+            DBpediaModel(item) for item in json_obj["periods"]
+        ] if self.is_valid else []
+        self.matches: list[str] = list(
+            set(
+                [item.matched_value for item in self.periods]
+            )
+        )
+
+    def __str__(self):
+        if self.initial is None:
+            return "TemporalExpression(None)"
+
+        return f"TemporalExpression({self.initial})"
+
+    def __repr__(self):
+        return self.initial
+
+    @staticmethod
+    def is_valid_json(json_obj) -> bool:
+        return ("initial" in json_obj
+                and "edges" in json_obj
+                and "periods" in json_obj)
+
+
+class DBpediaModel:
+    """
+    A model representing an entity from DBpedia, storing key attributes related to the entity.
+
+    Attributes:
+        uri (str): The unique identifier (URI) of the DBpedia entity.
+        label (str): A human-readable name for the entity.
+        matched_value (str): The original matched value from the input data.
+        matched_type (TemporalType or None): The temporal type of the entity, if applicable.
+    """
+
+    def __init__(self, data: dict):
+        self.uri: str = data["uri"] if "uri" in data else None
+        self.label: str = data["label"] if "label" in data else None
+        self.matched_value: str = data["matchedValue"] if "matchedValue" in data else None
+        try:
+            self.matched_type: TemporalType = TemporalType(data["matchedType"]) if "matchedType" in data else None
+        except ValueError:
+            self.matched_type = None
+
+    def __repr__(self):
+        return f"DBpediaModel(label={self.label}, matched_value={self.matched_value})"
+
+    def serialize(self, indent: str = ""):
+        return (f"{indent}Matched value: {self.matched_value}\n"
+                f"{indent}Matched Type: {self.matched_type.value if self.matched_type else None}\n"
+                f"{indent}Normalized label: {self.label}\n"
+                f"{indent}DBpedia uri: {self.uri}")
+
+
+class EdgeModel:
+    """
+    A model representing time interval represented as DBpedia entities.
+    This edge represents the starting and ending points of a time period.
+
+    Attributes:
+        start (DBpediaModel): The starting entity of the time period.
+        end (DBpediaModel): The ending entity of the time period.
+    """
+
+    def __init__(self, data: dict):
+        self.start: DBpediaModel = DBpediaModel(data["start"]) if "start" in data else None
+        self.end: DBpediaModel = DBpediaModel(data["end"]) if "end" in data else None
+
+    def __repr__(self):
+        return f"EdgeModel(start={self.start}, end={self.end})"
+
+    def serialize(self, indent: str = ""):
+        start = self.start.serialize("\t")
+        end = self.end.serialize("\t")
+
+        return (f"{indent}Start time:\n{start}\n"
+                f"{indent}End time:\n{end}")

temporal_normalization_spacy-1.0.0/temporal_normalization/commons/temporal_types.py

@@ -0,0 +1,10 @@
+from enum import Enum
+
+
+class TemporalType(Enum):
+    CENTURY = "century"
+    DATE = "date"
+    EPOCH = "epoch"
+    MILLENNIUM = "millennium"
+    UNKNOWN = "unknown"
+    YEAR = "year"

temporal_normalization_spacy-1.0.0/temporal_normalization/index.py

@@ -0,0 +1,88 @@
+import os
+import re
+import unicodedata
+
+from spacy import Language
+from spacy.tokens import Doc, Span
+
+from temporal_normalization.commons.temporal_models import TemporalExpression
+from temporal_normalization.process.java_process import start_process
+
+try:
+    @Language.factory("temporal_normalization")
+    def create_normalized_component(nlp, name):
+        return TemporalNormalization(nlp, name)
+except AttributeError:
+    # spaCy 2.x
+    pass
+
+
+class TemporalNormalization:
+    __FIELD = "normalized"
+
+    def __init__(self, nlp: Language, name: str):
+        Span.set_extension("normalized", default=None, force=True)
+        self.nlp = nlp
+
+    def __call__(self, doc: Doc) -> Doc:
+        jar_path = os.path.join(
+            os.path.dirname(__file__),
+            'libs/temporal-normalization-1.6.jar'
+        )
+
+        expressions: list[TemporalExpression] = []
+        start_process(doc, expressions, jar_path)
+        str_matches: list[str] = _prepare_str_patterns(expressions)
+
+        _retokenize(doc, str_matches, expressions)
+
+        return doc
+
+
+def _prepare_str_patterns(expressions: list[TemporalExpression]) -> list[str]:
+    matches: list[str] = []
+
+    for expression in expressions:
+        for match in expression.matches:
+            matches.append(match)
+
+    return matches
+
+
+def _retokenize(doc: Doc, str_matches: list[str], expressions: list[TemporalExpression]) -> None:
+    regex_matches: list[str] = [fr"{item}" for item in str_matches]
+    pattern = f"({'|'.join(regex_matches)})"
+    matches = list(re.finditer(pattern, remove_accents(doc.text), re.IGNORECASE)) if len(regex_matches) > 0 else []
+
+    with doc.retokenize() as retokenizer:
+        for match in matches:
+            start_char, end_char = match.start(), match.end()
+            start_token, end_token = None, None
+
+            for token in doc:
+                if token.idx == start_char:
+                    start_token = token.i
+                if token.idx + len(token.text) == end_char:
+                    end_token = token.i
+
+            if start_token is not None and end_token is not None:
+                entity = Span(doc, start_token, end_token + 1, label="DATETIME")
+                expression = next((item for item in expressions if remove_accents(entity.text) in item.matches), None)
+
+                if expression:
+                    entity._.set("normalized", expression)
+
+                retokenizer.merge(entity)
+            else:
+                print(f"Warning: Could not find tokens for match '{match.group()}' at {start_char}-{end_char}")
+
+
+def remove_accents(input_str):
+    # Normalize the input string to NFD form (decomposed)
+    nfkd_form = unicodedata.normalize('NFD', input_str)
+    # Filter out characters that are combining accents (category 'Mn' stands for Non-spacing Mark)
+    return ''.join([c for c in nfkd_form if unicodedata.category(c) != 'Mn'])
+
+
+if __name__ == "__main__":
+    pass

temporal_normalization_spacy-1.0.0/temporal_normalization/process/__init__.py

@@ -0,0 +1 @@
+from .java_process import *

temporal_normalization_spacy-1.0.0/temporal_normalization/process/java_process.py

@@ -0,0 +1,87 @@
+import re
+import shutil
+import subprocess
+
+from py4j.java_gateway import JavaGateway
+from py4j.protocol import Py4JNetworkError
+from spacy.tokens import Doc
+
+from temporal_normalization.commons.print_utils import console
+from temporal_normalization.commons.temporal_models import TemporalExpression
+
+
+def start_process(doc: Doc, expressions: list[TemporalExpression], jar_path):
+    check_java_version()
+
+    java_process = subprocess.Popen(
+        ["java", "-jar", jar_path],
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        text=True
+    )
+
+    for line in java_process.stdout:
+        if "Gateway Server Started..." in line:
+            print(line.strip())
+            break
+
+    gateway = gateway_conn(doc, expressions)
+
+    try:
+        # Proper way to shut down Py4J
+        gateway.shutdown()
+        print("Python connection closed.")
+    except Py4JNetworkError:
+        print("Java process already shut down.")
+
+    # Terminate Java process
+    java_process.terminate()
+    print("Java server is shutting down...")
+
+
+def gateway_conn(doc: Doc, expressions: list[TemporalExpression]) -> JavaGateway:
+    """Connect to the running Py4J Gateway"""
+
+    gateway = JavaGateway()
+    print("Python connection established.")
+
+    if isinstance(doc, Doc):
+        java_object = gateway.jvm.ro.webdata.normalization.timespan.ro.TimeExpression(doc.text, False, "\n")
+        time_expression = TemporalExpression(java_object)
+
+        if time_expression.is_valid:
+            expressions.append(time_expression)
+
+    return gateway
+
+
+def check_java_version():
+    min_version = 11
+    java_path = shutil.which("java")
+
+    try:
+        if java_path:
+            # Run the command to check the Java version
+            result = subprocess.run([java_path, "-version"], capture_output=True, text=True)
+
+            # Print the version information (Java version is printed to stderr)
+            if result.returncode == 0:
+                version_output = result.stderr
+                match = re.search(r'version "(\d+\.\d+)', version_output)
+
+                if match:
+                    crr_version = float(match.group(1))
+                    if crr_version < min_version:
+                        console.error(f"Java {crr_version} is installed, but version {min_version} is required.")
+                else:
+                    console.error("Could not extract Java version.")
+            else:
+                console.error("Error occurred while checking the version.")
+        else:
+            console.error("Java not found.")
+    except Exception as e:
+        console.error(e.__str__())
+
+
+if __name__ == "__main__":
+    pass

temporal_normalization_spacy-1.0.0/temporal_normalization_spacy.egg-info/PKG-INFO

@@ -0,0 +1,251 @@
+Metadata-Version: 2.2
+Name: temporal_normalization_spacy
+Version: 1.0.0
+Summary: A spaCy plugin for identifying and parsing historical data in Romanian texts
+Home-page: https://github.com/iliedorobat/timespan-normalization-spacy
+Author: Ilie Cristian Dorobat
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.6
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: spacy>=3.0
+Requires-Dist: py4j
+Requires-Dist: langdetect
+Dynamic: author
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# Temporal Expressions Normalization spaCy (TeNs)
+
+<b>Temporal Expressions Normalization spaCy (TeNs)</b> is a powerful pipeline component for spaCy that seamlessly
+identifies and parses date entities in text. It leverages the <b>[Temporal Normalization Framework](
+https://github.com/iliedorobat/timespan-normalization)</b> to recognize a wide variety of date formats using an
+extensive set of regular expressions (RegEx), ensuring robust and adaptable date extraction across diverse
+textual sources.
+
+Unlike conventional solutions that primarily focus on well-structured date formats, TeNs excels in handling
+real-world text by <b>identifying</b> not only standard date representations but also <b>abbreviated, informal, or even
+misspelled temporal expressions.</b> This makes it particularly effective for processing noisy or unstructured data,
+such as historical records, user-generated content, and scanned documents with OCR inaccuracies.
+
+Moreover, TeNs is designed to <b>integrate seamlessly into existing NLP pipelines,</b> allowing for enhanced temporal
+information processing in tasks such as event extraction, timeline construction, and knowledge graph population.
+By providing a flexible and accurate approach to temporal data normalization, it significantly improves the
+quality and reliability of date-related information extracted from text.
+
+<b>Table I.</b> Types of temporal expressions which can be processed
+<table>
+    <tr>
+        <th>Type of Temporal Expressions</th>
+        <th>Examples of Temporal Expressions*</th>
+    </tr>
+    <tr>
+        <td>dates</td>
+        <td>
+            YMD: 1881-08-31; 1857 mai 10; etc.<br/>
+            DMY: 09.11.1518; 1 noiembrie 1624; etc.<br/>
+            MY: ianuarie 632; etc.
+        </td>
+    </tr>
+    <tr>
+        <td>timespans</td>
+        <td>
+            centuries: s:; sc; se.; sec; sec.; secol; secolele; secolul; sex.<br/>
+            millenniums: mil; mil.; mileniul; mileniului; mileniile
+        </td>
+    </tr>
+    <tr>
+        <td>years</td>
+        <td>77; 78; 1652; [1873]; aproximativ 1834; cca. 1420; etc.</td>
+    </tr>
+</table>
+* The values are mentioned in the reference language – Romanian language
+
+
+
+## Getting started
+To integrate TeNs into spaCy pipelines you need the following:
+
+### Prerequisites
+- Python 3.x
+- JRE 11+
+- spaCy 3.x
+- py4j 0.10.9.9
+- langdetect 1.0.9
+
+1. Install python packages:
+```bash
+    pip install -r requirements.txt
+```
+
+2. Install [JDK 11](https://www.oracle.com/nl/java/technologies/javase/jdk11-archive-downloads.html) or [OpenJDK 11](https://openjdk.org/install/) (or newer versions)
+
+
+### Install
+```bash
+    pip install temporal-spacy
+```
+
+### Supported languages
+- [Romanian](https://universaldependencies.org/tagset-conversion/ro-multext-uposf.html)
+
+
+
+## Usage
+*** 
+
+### Importing Modules & Defining Constants
+
+```python
+import subprocess
+
+import spacy
+
+from temporal_normalization.commons.print_utils import console
+from temporal_normalization.index import create_normalized_component, TemporalNormalization  ## noqa: F401
+
+LANG = "ro"
+MODEL = "ro_core_news_sm"
+TEXT_RO = ("Sec al II-lea a.ch. a fost o perioadă de mari schimbări. "
+           "În secolul XX, tehnologia a avansat semnificativ. "
+           "Sec. 21 este adesea asociat cu globalizarea rapidă.")
+```
+
+### Adding the Component to spaCy Pipeline
+```python
+    # Display a warning if the language of the text is not Romanian.
+console.lang_warning(TEXT_RO, target_lang=LANG)
+
+try:
+    # Load the spaCy model if it has already been downloaded
+    nlp = spacy.load(MODEL)
+except OSError:
+    console.warning(f'Started downloading {MODEL}...')
+    # Download the Romanian model if it wasn't already downloaded
+    subprocess.run(["python", "-m", "spacy", "download", MODEL])
+    # Load the spaCy model
+    nlp = spacy.load(MODEL)
+
+# Add "temporal_normalization" component to the spaCy pipeline
+nlp.add_pipe("temporal_normalization", last=True)
+```
+
+### Processing Text with the Pipeline
+```python
+doc = nlp(TEXT_RO)
+
+# Display NLP-specific linguistic annotations
+console.tokens_table(doc)
+print()
+```
+
+### Accessing the Parsed Temporal Expressions
+```python
+# Display information about the identified and normalized dates in the text.
+for entity in doc.ents:
+    for edge in entity._.normalized.edges:
+        print(edge.serialize())
+        print()
+
+    print("Periods:")
+    for period in entity._.normalized.periods:
+        print(period.serialize("\t"))
+        print()
+```
+
+### Result
+#### First Sentence
+```text
+Start time:
+	Matched value: Sec al II-lea a.ch.
+	Matched Type: century
+	Normalized label: 2nd century BC
+	DBpedia uri: https://dbpedia.org/page/2nd_century_BC
+End time:
+	Matched value: Sec al II-lea a.ch.
+	Matched Type: century
+	Normalized label: 2nd century BC
+	DBpedia uri: https://dbpedia.org/page/2nd_century_BC
+
+Periods:
+	Matched value: Sec al II-lea a.ch.
+	Matched Type: century
+	Normalized label: 1st millennium BC
+	DBpedia uri: https://dbpedia.org/page/1st_millennium_BC
+
+	Matched value: Sec al II-lea a.ch.
+	Matched Type: century
+	Normalized label: 2nd century BC
+	DBpedia uri: https://dbpedia.org/page/2nd_century_BC
+```
+
+#### Second Sentence
+```text
+Start time:
+	Matched value: secolul XX
+	Matched Type: century
+	Normalized label: 20th century
+	DBpedia uri: https://dbpedia.org/page/20th_century
+End time:
+	Matched value: secolul XX
+	Matched Type: century
+	Normalized label: 20th century
+	DBpedia uri: https://dbpedia.org/page/20th_century
+
+Periods:
+	Matched value: secolul XX
+	Matched Type: century
+	Normalized label: 2nd millennium
+	DBpedia uri: https://dbpedia.org/page/2nd_millennium
+
+	Matched value: secolul XX
+	Matched Type: century
+	Normalized label: 20th century
+	DBpedia uri: https://dbpedia.org/page/20th_century
+```
+
+#### Third Sentence
+```text
+Start time:
+	Matched value: Sec. 21
+	Matched Type: century
+	Normalized label: 21st century
+	DBpedia uri: https://dbpedia.org/page/21st_century
+End time:
+	Matched value: Sec. 21
+	Matched Type: century
+	Normalized label: 21st century
+	DBpedia uri: https://dbpedia.org/page/21st_century
+
+Periods:
+	Matched value: Sec. 21
+	Matched Type: century
+	Normalized label: 3rd millennium
+	DBpedia uri: https://dbpedia.org/page/3rd_millennium
+
+	Matched value: Sec. 21
+	Matched Type: century
+	Normalized label: 21st century
+	DBpedia uri: https://dbpedia.org/page/21st_century
+```
+
+
+
+## Publications
+ECAI 2021: [The Power of Regular Expressions in Recognizing Dates and Epochs (2021)](https://ieeexplore.ieee.org/document/9515139)
+```
+@inproceedings{9515139,
+  author={Dorobăț, Ilie Cristian and Posea, Vlad},
+  booktitle={2021 13th International Conference on Electronics, Computers and Artificial Intelligence (ECAI)}, 
+  title={The Power of Regular Expressions in Recognizing Dates and Epochs}, 
+  year={2021},
+  pages={1-3},
+  doi={10.1109/ECAI52376.2021.9515139}}
+```

temporal_normalization_spacy-1.0.0/temporal_normalization_spacy.egg-info/SOURCES.txt

@@ -0,0 +1,18 @@
+LICENSE
+MANIFEST.in
+README.md
+setup.py
+temporal_normalization/__init__.py
+temporal_normalization/index.py
+temporal_normalization/commons/__init__.py
+temporal_normalization/commons/print_utils.py
+temporal_normalization/commons/temporal_models.py
+temporal_normalization/commons/temporal_types.py
+temporal_normalization/libs/temporal-normalization-1.6.jar
+temporal_normalization/process/__init__.py
+temporal_normalization/process/java_process.py
+temporal_normalization_spacy.egg-info/PKG-INFO
+temporal_normalization_spacy.egg-info/SOURCES.txt
+temporal_normalization_spacy.egg-info/dependency_links.txt
+temporal_normalization_spacy.egg-info/requires.txt
+temporal_normalization_spacy.egg-info/top_level.txt

temporal_normalization_spacy-1.0.0/temporal_normalization_spacy.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

temporal_normalization_spacy-1.0.0/temporal_normalization_spacy.egg-info/requires.txt

@@ -0,0 +1,3 @@
+spacy>=3.0
+py4j
+langdetect

temporal_normalization_spacy-1.0.0/temporal_normalization_spacy.egg-info/top_level.txt

@@ -0,0 +1 @@
+temporal_normalization