README.md

---

language: ar
datasets:
- Marefa-NER
---


# Tebyan تبيـان
## Marefa Arabic Named Entity Recognition Model
## نموذج المعرفة لتصنيف أجزاء النص
---------
**Version**: 1.2

**Last Update:** 22-05-2021

## Model description

**Marefa-NER** is a Large Arabic Named Entity Recognition (NER) model built on a completely new dataset and targets to extract up to 9 different types of entities
```

Person, Location, Organization, Nationality, Job, Product, Event, Time, Art-Work

```

نموذج المعرفة لتصنيف أجزاء النص. نموذج جديد كليا من حيث البيانات المستخدمة في تدريب النموذج. 
كذلك يستهدف النموذج تصنيف حتى 9 أنواع مختلفة من أجزاء النص
```

شخص - مكان - منظمة - جنسية - وظيفة - منتج - حدث - توقيت - عمل إبداعي

```

## How to use كيف تستخدم النموذج

*You can test the model quickly by checking this [Colab notebook](https://colab.research.google.com/drive/1OGp9Wgm-oBM5BBhTLx6Qow4dNRSJZ-F5?usp=sharing)*

-----

Install the following Python packages

`$ pip3 install transformers==4.8.0 nltk==3.5 protobuf==3.15.3 torch==1.9.0 `

> If you are using `Google Colab`, please restart your runtime after installing the packages.

[**OPTIONAL**] 
Using of an Arabic segmentation tool approved better results in many scenarios. If you want to use `FarasaPy`to segment the texts, please ensure that you have `openjdk-11`installed in your machine, then install the package via:
```bash

# install openjdk-11-jdk

$ apt-get install -y build-essential 

$ apt-get install -y openjdk-11-jdk



# instll FarasaPy

$ pip3 install farasapy==0.0.13

```

*Do not forget to set `USE_FARASAPY` to `True` in the following code*
 
 Also, you can set `USE_SENTENCE_TOKENIZER` to `True` for getting better results for  long texts.

-----------

```python



# ==== Set configurations

# do you want to use FarasaPy Segmentation tool ?

USE_FARASAPY = False # set to True to use it



# do you want to split text into sentences [better for long texts] ?

USE_SENTENCE_TOKENIZER = False # set to True to use it



# ==== Import required modules

import logging

import re



import nltk

nltk.download('punkt')

from nltk.tokenize import word_tokenize, sent_tokenize



from transformers import AutoTokenizer, AutoModelForTokenClassification, pipeline



# disable INFO Logs

transformers_logger = logging.getLogger("transformers")

transformers_logger.setLevel(logging.WARNING)



def _extract_ner(sent: str, ner: pipeline) -> str:

    grouped_ents = []

    current_ent = {}



    results = ner(sent)

    for ent in results:

        if len(current_ent) == 0:

            current_ent = ent

            continue



        if current_ent["end"] == ent["start"] and current_ent["entity_group"] == ent["entity_group"]:

            current_ent["word"] = current_ent["word"]+ent["word"]

        else:

            grouped_ents.append(current_ent)

            current_ent = ent

            

    if len(grouped_ents) > 0 and grouped_ents[-1] != ent:

        grouped_ents.append(current_ent)

    elif len(grouped_ents) == 0 and len(current_ent) > 0:

        grouped_ents.append(current_ent)

    

    return [ g for g in grouped_ents if len(g["word"].strip()) ]



if USE_FARASAPY:

	from farasa.segmenter import FarasaSegmenter

	segmenter = FarasaSegmenter()

	

	def _segment_text(text: str, segmenter: FarasaSegmenter) -> str:

	    segmented = segmenter.segment(text)

	    f_segments = { w.replace("+",""): w.replace("و+","و ").replace("+","") for w in segmented.split(" ") if w.strip() != "" and w.startswith("و+") }

	    for s,t in f_segments.items():

	        text = text.replace(s, t)

	    return text

	

	_ = _segment_text("نص تجريبي للتأكد من عمل الأداة", segmenter)



custom_labels = ["O", "B-job", "I-job", "B-nationality", "B-person", "I-person", "B-location",

                 "B-time", "I-time", "B-event", "I-event", "B-organization", "I-organization",

                 "I-location", "I-nationality", "B-product", "I-product", "B-artwork", "I-artwork"]



# ==== Import/Download the NER Model

m_name = "marefa-nlp/marefa-ner"

tokenizer = AutoTokenizer.from_pretrained(m_name)

model = AutoModelForTokenClassification.from_pretrained(m_name)



ar_ner = pipeline("ner", model=model, tokenizer=tokenizer, grouped_entities=True, aggregation_strategy="simple")



# ==== Model Inference

samples = [

    "تلقى تعليمه في الكتاب ثم انضم الى الأزهر عام 1873م. تعلم على يد السيد جمال الدين الأفغاني والشيخ محمد عبده",

    "بعد عودته إلى القاهرة، التحق نجيب الريحاني فرقة جورج أبيض، الذي كان قد ضمَّ - قُبيل ذلك - فرقته إلى فرقة سلامة حجازي . و منها ذاع صيته",

    "امبارح اتفرجت على مباراة مانشستر يونايتد مع ريال مدريد في غياب الدون كرستيانو رونالدو",

    "Government extends flight ban from India and Pakistan until June 21"

]



# [optional]

samples = [ " ".join(word_tokenize(sample.strip())) for sample in samples if sample.strip() != "" ]



for sample in samples:

    ents = []

    

    if USE_FARASAPY:

        sample = _segment_text(sample, segmenter)



    if USE_SENTENCE_TOKENIZER:

        for sent in sent_tokenize(sample):

            ents += _extract_ner(sent, ar_ner)

    else:

        ents = _extract_ner(sample, ar_ner)

       

    # print the results

    print("(", sample, ")")

    for ent in ents:

        print("\t", ent["word"], "=>", ent["entity_group"])

    print("=========\n")



```

Output

```

( تلقى تعليمه في الكتاب ثم انضم الى الأزهر عام 1873م . تعلم على يد السيد جمال الدين الأفغاني والشيخ محمد عبده )

	 الأزهر => organization

	 عام 1873م => time

	 جمال الدين الأفغاني => person

	 محمد عبده => person

=========



( بعد عودته إلى القاهرة، التحق نجيب الريحاني فرقة جورج أبيض، الذي كان قد ضمَّ - قُبيل ذلك - فرقته إلى فرقة سلامة حجازي . و منها ذاع صيته )

	 القاهرة => location

	 نجيب الريحاني => person

	 فرقة جورج أبيض => organization

	 فرقة سلامة حجازي => organization

=========



( امبارح اتفرجت على مباراة مانشستر يونايتد مع ريال مدريد في غياب الدون كرستيانو رونالدو )

	 مانشستر يونايتد => organization

	 ريال مدريد => organization

	 كرستيانو رونالدو => person

=========



( Government extends flight ban from India and Pakistan until June 21 )

	 India => location

	 Pakistan => location

	 June 21 => time

=========

```

## Fine-Tuning

Check this [notebook](https://colab.research.google.com/drive/1WUYrnmDFFEItqGMvbyjqZEJJqwU7xQR-?usp=sharing) to fine-tune the NER model

## Acknowledgment شكر و تقدير

قام بإعداد البيانات التي تم تدريب النموذج عليها, مجموعة من المتطوعين الذين قضوا ساعات يقومون بتنقيح البيانات و مراجعتها

- على سيد عبد الحفيظ - إشراف
- نرمين محمد عطيه 
- صلاح خيرالله
- احمد علي عبدربه
- عمر بن عبد العزيز سليمان
- محمد ابراهيم الجمال
- عبدالرحمن سلامه خلف
- إبراهيم كمال محمد سليمان
- حسن مصطفى حسن 
- أحمد فتحي سيد
- عثمان مندو
- عارف الشريف
- أميرة محمد محمود
- حسن سعيد حسن
- عبد العزيز علي البغدادي
- واثق عبدالملك الشويطر
- عمرو رمضان عقل الحفناوي
- حسام الدين أحمد على
- أسامه أحمد محمد محمد
- حاتم محمد المفتي
- عبد الله دردير
- أدهم البغدادي
- أحمد صبري
- عبدالوهاب محمد محمد
- أحمد محمد عوض