Mutashabihat Analysis Notebook¶
Detailed examples of mutashabihat (repeated phrase) detection and analysis using QuranKit.
In [ ]:
Copied!
from qurankit import Quran
from qurankit.analysis import MutashabihatEngine, MatchMethod, ReportGenerator
from qurankit.search import SearchMode
quran = Quran.load()
engine = MutashabihatEngine()
reporter = ReportGenerator()
from qurankit import Quran
from qurankit.analysis import MutashabihatEngine, MatchMethod, ReportGenerator
from qurankit.search import SearchMode
quran = Quran.load()
engine = MutashabihatEngine()
reporter = ReportGenerator()
1. Exact Phrase Matching¶
Find exact textual matches for a given ayah.
In [ ]:
Copied!
# Ayat al-Kursi (2:255) - one of the most repeated passages
result = engine.find_exact_phrase("2:255", min_length=2)
print(f"Exact phrase matches for 2:255: {len(result.matches)}")
for match in result.matches:
print(f" {match.reference}: {match.matched_text}")
print(f" Method: {match.match_method.value}")
print(f" Category: {match.match_category.value}")
print()
# Ayat al-Kursi (2:255) - one of the most repeated passages
result = engine.find_exact_phrase("2:255", min_length=2)
print(f"Exact phrase matches for 2:255: {len(result.matches)}")
for match in result.matches:
print(f" {match.reference}: {match.matched_text}")
print(f" Method: {match.match_method.value}")
print(f" Category: {match.match_category.value}")
print()
In [ ]:
Copied!
# Surah Al-Ikhlas (112) - short surah with repeated phrases
result = engine.find_exact_phrase("112:1", min_length=2)
print(f"Exact phrase matches for 112:1: {len(result.matches)}")
for match in result.matches:
print(f" {match.reference}: {match.matched_text}")
# Surah Al-Ikhlas (112) - short surah with repeated phrases
result = engine.find_exact_phrase("112:1", min_length=2)
print(f"Exact phrase matches for 112:1: {len(result.matches)}")
for match in result.matches:
print(f" {match.reference}: {match.matched_text}")
2. Normalized Matching¶
Match phrases ignoring diacritics but preserving Quranic marks.
In [ ]:
Copied!
# Diacritics-insensitive matching
result = engine.find_normalized_matches(
"2:255",
normalization_profile="diacritics-insensitive-v1",
min_words=2
)
print(f"Normalized matches for 2:255: {len(result.matches)}")
for match in result.matches[:10]:
print(f" {match.reference}: {match.matched_text} [{match.match_type.value}]")
# Diacritics-insensitive matching
result = engine.find_normalized_matches(
"2:255",
normalization_profile="diacritics-insensitive-v1",
min_words=2
)
print(f"Normalized matches for 2:255: {len(result.matches)}")
for match in result.matches[:10]:
print(f" {match.reference}: {match.matched_text} [{match.match_type.value}]")
In [ ]:
Copied!
# Broad search matching (alif/hamza/ya normalization)
result = engine.find_normalized_matches(
"2:255",
normalization_profile="search-broad-v1",
min_words=2
)
print(f"Broad search matches for 2:255: {len(result.matches)}")
for match in result.matches[:10]:
print(f" {match.reference}: {match.matched_text} [{match.match_type.value}]")
# Broad search matching (alif/hamza/ya normalization)
result = engine.find_normalized_matches(
"2:255",
normalization_profile="search-broad-v1",
min_words=2
)
print(f"Broad search matches for 2:255: {len(result.matches)}")
for match in result.matches[:10]:
print(f" {match.reference}: {match.matched_text} [{match.match_type.value}]")
3. Near-Duplicate Detection¶
Find similar phrases using fuzzy matching (computational suggestion).
In [ ]:
Copied!
# Near-duplicate detection with 70% similarity threshold
result = engine.find_near_duplicates(
"2:255",
threshold=0.7,
normalization_profile="search-broad-v1"
)
print(f"Near duplicates for 2:255 (threshold 0.7): {len(result.matches)}")
for match in result.matches[:10]:
print(f" {match.reference}: {match.matched_text}")
print(f" Similarity: {match.similarity_score:.3f}")
print(f" Category: {match.match_category.value}")
print()
# Near-duplicate detection with 70% similarity threshold
result = engine.find_near_duplicates(
"2:255",
threshold=0.7,
normalization_profile="search-broad-v1"
)
print(f"Near duplicates for 2:255 (threshold 0.7): {len(result.matches)}")
for match in result.matches[:10]:
print(f" {match.reference}: {match.matched_text}")
print(f" Similarity: {match.similarity_score:.3f}")
print(f" Category: {match.match_category.value}")
print()
In [ ]:
Copied!
# Try with different thresholds
for threshold in [0.5, 0.6, 0.7, 0.8, 0.9]:
result = engine.find_near_duplicates(
"2:255",
threshold=threshold,
normalization_profile="search-broad-v1"
)
print(f"Threshold {threshold}: {len(result.matches)} matches")
# Try with different thresholds
for threshold in [0.5, 0.6, 0.7, 0.8, 0.9]:
result = engine.find_near_duplicates(
"2:255",
threshold=threshold,
normalization_profile="search-broad-v1"
)
print(f"Threshold {threshold}: {len(result.matches)} matches")
4. Recurring N-grams¶
Find n-grams (sequences of n words) that appear multiple times.
In [ ]:
Copied!
# 2-grams appearing at least 3 times
ngrams = engine.find_exact_ngrams(n=2, min_occurrences=3)
print(f"Recurring 2-grams (min 3 occurrences): {len(ngrams)}")
for ng in ngrams[:15]:
print(f" {ng.text} — {ng.count} occurrences")
for ref in ng.references[:3]:
print(f" {ref}")
if len(ng.references) > 3:
print(f" ... and {len(ng.references) - 3} more")
print()
# 2-grams appearing at least 3 times
ngrams = engine.find_exact_ngrams(n=2, min_occurrences=3)
print(f"Recurring 2-grams (min 3 occurrences): {len(ngrams)}")
for ng in ngrams[:15]:
print(f" {ng.text} — {ng.count} occurrences")
for ref in ng.references[:3]:
print(f" {ref}")
if len(ng.references) > 3:
print(f" ... and {len(ng.references) - 3} more")
print()
In [ ]:
Copied!
# 3-grams appearing at least 2 times
ngrams = engine.find_exact_ngrams(n=3, min_occurrences=2)
print(f"Recurring 3-grams (min 2 occurrences): {len(ngrams)}")
for ng in ngrams[:15]:
print(f" {ng.text} — {ng.count} occurrences")
for ref in ng.references[:2]:
print(f" {ref}")
if len(ng.references) > 2:
print(f" ... and {len(ng.references) - 2} more")
print()
# 3-grams appearing at least 2 times
ngrams = engine.find_exact_ngrams(n=3, min_occurrences=2)
print(f"Recurring 3-grams (min 2 occurrences): {len(ngrams)}")
for ng in ngrams[:15]:
print(f" {ng.text} — {ng.count} occurrences")
for ref in ng.references[:2]:
print(f" {ref}")
if len(ng.references) > 2:
print(f" ... and {len(ng.references) - 2} more")
print()
In [ ]:
Copied!
# 4-grams
ngrams = engine.find_exact_ngrams(n=4, min_occurrences=2)
print(f"Recurring 4-grams (min 2 occurrences): {len(ngrams)}")
for ng in ngrams[:10]:
print(f" {ng.text} — {ng.count} occurrences")
# 4-grams
ngrams = engine.find_exact_ngrams(n=4, min_occurrences=2)
print(f"Recurring 4-grams (min 2 occurrences): {len(ngrams)}")
for ng in ngrams[:10]:
print(f" {ng.text} — {ng.count} occurrences")
5. Similar Openings and Endings¶
Find ayahs with similar beginnings or endings.
In [ ]:
Copied!
# Similar openings (first 3 words)
openings = engine.find_similar_openings(prefix_length=3, min_occurrences=2)
print(f"Similar openings (3 words, min 2 occurrences): {len(openings)}")
for opening in openings[:15]:
print(f" {opening.text} — {opening.count} occurrences")
for ref in opening.references[:3]:
print(f" {ref}")
if len(opening.references) > 3:
print(f" ... and {len(opening.references) - 3} more")
print()
# Similar openings (first 3 words)
openings = engine.find_similar_openings(prefix_length=3, min_occurrences=2)
print(f"Similar openings (3 words, min 2 occurrences): {len(openings)}")
for opening in openings[:15]:
print(f" {opening.text} — {opening.count} occurrences")
for ref in opening.references[:3]:
print(f" {ref}")
if len(opening.references) > 3:
print(f" ... and {len(opening.references) - 3} more")
print()
In [ ]:
Copied!
# Similar endings (last 3 words)
endings = engine.find_similar_endings(suffix_length=3, min_occurrences=2)
print(f"Similar endings (3 words, min 2 occurrences): {len(endings)}")
for ending in endings[:15]:
print(f" {ending.text} — {ending.count} occurrences")
for ref in ending.references[:3]:
print(f" {ref}")
if len(ending.references) > 3:
print(f" ... and {len(ending.references) - 3} more")
print()
# Similar endings (last 3 words)
endings = engine.find_similar_endings(suffix_length=3, min_occurrences=2)
print(f"Similar endings (3 words, min 2 occurrences): {len(endings)}")
for ending in endings[:15]:
print(f" {ending.text} — {ending.count} occurrences")
for ref in ending.references[:3]:
print(f" {ref}")
if len(ending.references) > 3:
print(f" ... and {len(ending.references) - 3} more")
print()
6. Recurring Expressions¶
Find recurring multi-word expressions across the corpus.
In [ ]:
Copied!
# Recurring expressions (3+ words, 3+ occurrences)
expressions = engine.find_recurring_expressions(min_length=3, min_occurrences=3)
print(f"Recurring expressions (3+ words, 3+ occurrences): {len(expressions)}")
for expr in expressions[:20]:
print(f" {expr.text} — {expr.count} occurrences")
for ref in expr.references[:3]:
print(f" {ref}")
if len(expr.references) > 3:
print(f" ... and {len(expr.references) - 3} more")
print()
# Recurring expressions (3+ words, 3+ occurrences)
expressions = engine.find_recurring_expressions(min_length=3, min_occurrences=3)
print(f"Recurring expressions (3+ words, 3+ occurrences): {len(expressions)}")
for expr in expressions[:20]:
print(f" {expr.text} — {expr.count} occurrences")
for ref in expr.references[:3]:
print(f" {ref}")
if len(expr.references) > 3:
print(f" ... and {len(expr.references) - 3} more")
print()
7. Generate Reports¶
Create structured analysis reports.
In [ ]:
Copied!
# Single ayah report
result = engine.find_normalized_matches(
"2:255",
normalization_profile="diacritics-insensitive-v1",
min_words=2
)
report = reporter.generate_report(result, "tanzil-uthmani-v1", "2:255")
print(reporter.format_report_text(report))
# Single ayah report
result = engine.find_normalized_matches(
"2:255",
normalization_profile="diacritics-insensitive-v1",
min_words=2
)
report = reporter.generate_report(result, "tanzil-uthmani-v1", "2:255")
print(reporter.format_report_text(report))
In [ ]:
Copied!
# Multi-ayah report for key verses
key_verses = ["1:1", "2:255", "3:2", "112:1", "113:1", "114:1"]
reports = reporter.generate_multi_report(key_verses)
print(f"Generated {len(reports)} reports")
for ref, report in zip(key_verses, reports):
print(f"\n=== {ref} ===")
print(f" Exact matches: {report.exact_match_count}")
print(f" Normalized matches: {report.normalized_match_count}")
print(f" Near duplicates: {report.near_duplicate_count}")
print(f" Total unique references: {report.total_unique_references}")
# Multi-ayah report for key verses
key_verses = ["1:1", "2:255", "3:2", "112:1", "113:1", "114:1"]
reports = reporter.generate_multi_report(key_verses)
print(f"Generated {len(reports)} reports")
for ref, report in zip(key_verses, reports):
print(f"\n=== {ref} ===")
print(f" Exact matches: {report.exact_match_count}")
print(f" Normalized matches: {report.normalized_match_count}")
print(f" Near duplicates: {report.near_duplicate_count}")
print(f" Total unique references: {report.total_unique_references}")
In [ ]:
Copied!
# Corpus-wide statistics
stats = reporter.generate_corpus_statistics()
print("Corpus Statistics:")
for key, value in stats.items():
print(f" {key}: {value}")
# Corpus-wide statistics
stats = reporter.generate_corpus_statistics()
print("Corpus Statistics:")
for key, value in stats.items():
print(f" {key}: {value}")
8. Comparative Analysis¶
Compare mutashabihat patterns across different surahs.
In [ ]:
Copied!
# Compare first verses of each surah
first_verses = [f"{i}:1" for i in range(1, 115)]
print("Mutashabihat analysis for first verses of each surah:")
surah_stats = []
for ref in first_verses:
result = engine.find_normalized_matches(
ref,
normalization_profile="diacritics-insensitive-v1",
min_words=2
)
if result.matches:
surah_stats.append((ref, len(result.matches)))
# Sort by match count
surah_stats.sort(key=lambda x: x[1], reverse=True)
print("\nTop 20 surahs by first verse mutashabihat:")
for ref, count in surah_stats[:20]:
print(f" {ref}: {count} matches")
# Compare first verses of each surah
first_verses = [f"{i}:1" for i in range(1, 115)]
print("Mutashabihat analysis for first verses of each surah:")
surah_stats = []
for ref in first_verses:
result = engine.find_normalized_matches(
ref,
normalization_profile="diacritics-insensitive-v1",
min_words=2
)
if result.matches:
surah_stats.append((ref, len(result.matches)))
# Sort by match count
surah_stats.sort(key=lambda x: x[1], reverse=True)
print("\nTop 20 surahs by first verse mutashabihat:")
for ref, count in surah_stats[:20]:
print(f" {ref}: {count} matches")
In [ ]:
Copied!
# Analyze specific surah groups
groups = {
"Mu'awwidhatayn": ["113:1", "113:2", "113:3", "113:4", "113:5",
"114:1", "114:2", "114:3", "114:4", "114:5", "114:6"],
"Al-Fatiha": ["1:1", "1:2", "1:3", "1:4", "1:5", "1:6", "1:7"],
"Ayat al-Kursi context": ["2:254", "2:255", "2:256", "2:257"]
}
for group_name, verses in groups.items():
print(f"\n=== {group_name} ===")
for ref in verses:
result = engine.find_normalized_matches(
ref,
normalization_profile="diacritics-insensitive-v1",
min_words=2
)
print(f" {ref}: {len(result.matches)} matches")
# Analyze specific surah groups
groups = {
"Mu'awwidhatayn": ["113:1", "113:2", "113:3", "113:4", "113:5",
"114:1", "114:2", "114:3", "114:4", "114:5", "114:6"],
"Al-Fatiha": ["1:1", "1:2", "1:3", "1:4", "1:5", "1:6", "1:7"],
"Ayat al-Kursi context": ["2:254", "2:255", "2:256", "2:257"]
}
for group_name, verses in groups.items():
print(f"\n=== {group_name} ===")
for ref in verses:
result = engine.find_normalized_matches(
ref,
normalization_profile="diacritics-insensitive-v1",
min_words=2
)
print(f" {ref}: {len(result.matches)} matches")