Computational Research¶
QuranKit provides tools for reproducible computational and statistical analysis of Qur'anic text.
Frequency Analysis¶
Letter Frequency¶
from qurankit import Quran
from qurankit.analysis import frequency
quran = Quran.load()
# Letter frequency (with/without diacritics)
letter_freq = frequency.letter_frequency(quran, include_diacritics=False)
for letter, count in sorted(letter_freq.items(), key=lambda x: -x[1]):
print(f"{letter}: {count}")
# Diacritic frequency
diacritic_freq = frequency.diacritic_frequency(quran)
for mark, count in sorted(diacritic_freq.items(), key=lambda x: -x[1]):
print(f"{mark}: {count}")
Word Frequency¶
# Word frequency (by surface form)
word_freq = frequency.word_frequency(quran, normalized=False)
for word, count in word_freq.most_common(50):
print(f"{word}: {count}")
# Normalized word frequency
word_freq_norm = frequency.word_frequency(quran, normalized=True, mode="broad")
Root & Lemma Frequency¶
# Requires QAC vocabulary
vocab = quran.vocabulary
# Root frequency
root_freq = vocab.get_root_frequency_list(limit=100)
for item in root_freq:
print(f"{item.root}: {item.count}")
# Lemma frequency
lemma_freq = vocab.get_lemma_frequency_list(limit=100)
for item in lemma_freq:
print(f"{item.lemma}: {item.count}")
Distribution Analysis¶
from qurankit.analysis import distribution
# Root distribution across surahs
root_dist = distribution.root_distribution(quran, "ر ح م")
for surah_num, count in root_dist.items():
surah = quran.surah(surah_num)
print(f"Surah {surah_num} ({surah.name_arabic}): {count}")
# Lemma distribution
lemma_dist = distribution.lemma_distribution(quran, "كِتَاب")
# Word distribution
word_dist = distribution.word_distribution(quran, "كتاب", mode="broad")
Co-occurrence Analysis¶
from qurankit.analysis import cooccurrence
# Word co-occurrence within window
cooccur = cooccurrence.word_cooccurrence(
quran,
target="رحمن",
window=5, # 5 words before/after
mode="broad"
)
for word, count in cooccur.most_common(20):
print(f"{word}: {count}")
# Root co-occurrence
root_cooccur = cooccurrence.root_cooccurrence(
quran,
target_root="ر ح م",
window=10
)
# Surah-level co-occurrence
surah_cooccur = cooccurrence.surah_cooccurrence(quran, "رحمن", "رحيم")
Collocation Analysis¶
from qurankit.analysis import collocation
# Find significant collocations (PMI, log-likelihood, etc.)
collocations = collocation.find_collocations(
quran,
target="كتاب",
measure="pmi", # or "log_likelihood", "dice", "t_score"
min_freq=5,
window=5
)
for colloc in collocations:
print(f"{colloc.word}: {colloc.score:.4f} "
f"(freq: {colloc.freq}, joint: {colloc.joint_freq})")
N-gram Analysis¶
from qurankit.analysis import ngrams
# Character n-grams
char_ngrams = ngrams.character_ngrams(quran, n=3, top=50)
for gram, count in char_ngrams:
print(f"{gram}: {count}")
# Word n-grams
word_ngrams = ngrams.word_ngrams(quran, n=2, top=50, mode="broad")
for gram, count in word_ngrams:
print(f"{gram}: {count}")
# Root n-grams (requires vocabulary)
root_ngrams = ngrams.root_ngrams(quran, n=2, top=50)
Statistical Testing¶
from qurankit.analysis import statistics
# Chi-square test for root distribution uniformity
chi2, p = statistics.root_distribution_uniformity(quran, "ر ح م")
print(f"Chi-square: {chi2:.4f}, p-value: {p:.6f}")
# Compare root frequencies between Makki/Madani surahs
makki_freq, madani_freq = statistics.root_frequency_by_revelation(quran, "ر ح م")
u_stat, p = statistics.mannwhitneyu(makki_freq, madani_freq)
print(f"Mann-Whitney U: {u_stat:.4f}, p-value: {p:.6f}")
# Correlation between root frequencies
corr, p = statistics.root_frequency_correlation(quran, "ر ح م", "ع ل م")
print(f"Correlation: {corr:.4f}, p-value: {p:.6f}")
Reproducible Research Runs¶
from qurankit.analysis import ResearchRun, ResearchResult
# Create a documented research run
run = ResearchRun(
name="Root frequency analysis - ر ح م",
description="Analyze distribution and frequency of root ر ح م across the Qur'an",
researcher="Your Name",
tags=["root-analysis", "frequency", "rahma"]
)
# Add inputs
run.add_input(
dataset="tanzil",
edition="simple",
version="1.0.0"
)
run.add_input(
dataset="qac",
version="2.0"
)
# Record parameters
run.set_parameter("normalization", "broad")
run.set_parameter("min_frequency", 1)
run.set_parameter("surah_range", [1, 114])
# Execute analysis
vocab = quran.vocabulary
stats = vocab.get_vocabulary_stats("ر ح م")
freq_list = vocab.get_root_frequency_list(limit=50)
# Record results
result = ResearchResult(
run_id=run.id,
name="Root statistics - ر ح م",
category="deterministic_result",
data={
"total_occurrences": stats.total_occurrences,
"unique_lemmas": stats.unique_lemmas,
"surahs_covered": stats.surahs_covered,
"first_occurrence": str(stats.first_occurrence),
"last_occurrence": str(stats.last_occurrence)
},
method="vocabulary_lookup",
parameters=run.parameters,
software_version="qurankit-0.2.0"
)
run.add_result(result)
# Save run
run.save("research_runs/rahma_analysis.json")
# Load and verify
loaded_run = ResearchRun.load("research_runs/rahma_analysis.json")
print(loaded_run.reproduce())
Export Formats¶
from qurankit.analysis.reports import ComparisonReport, CorpusStatistics
# Generate report
report = ComparisonReport.generate(quran, reference=(2, 255))
# Export formats
report.to_json("report.json")
report.to_csv("report.csv")
report.to_excel("report.xlsx")
report.to_markdown("report.md")
report.to_latex("report.tex")
# Corpus statistics
stats = CorpusStatistics.compute(quran)
stats.to_json("corpus_stats.json")
stats.to_csv("corpus_stats.csv")
Data Frames (Pandas Integration)¶
import pandas as pd
from qurankit.analysis import to_dataframe
# Root frequency as DataFrame
df_roots = to_dataframe(quran.vocabulary.get_root_frequency_list())
print(df_roots.head())
print(df_roots.describe())
# Co-occurrence matrix
df_cooccur = to_dataframe(cooccurrence.root_cooccurrence_matrix(quran))
print(df_cooccur.shape)
# Surah statistics
df_surahs = to_dataframe(CorpusStatistics.compute(quran).surah_statistics)
print(df_surahs[['number', 'name_arabic', 'ayah_count', 'word_count']].head())
Visualization Examples¶
import matplotlib.pyplot as plt
import seaborn as sns
from qurankit.analysis import frequency, to_dataframe
# Root frequency distribution
df = to_dataframe(quran.vocabulary.get_root_frequency_list(limit=100))
plt.figure(figsize=(10, 6))
sns.barplot(data=df.head(20), x='root', y='count')
plt.xticks(rotation=45)
plt.title("Top 20 Roots by Frequency")
plt.tight_layout()
plt.savefig("root_frequency.png")
# Root distribution heatmap
df_dist = to_dataframe(distribution.root_distribution_matrix(quran))
plt.figure(figsize=(12, 10))
sns.heatmap(df_dist.iloc[:50, :50], cmap="YlOrRd")
plt.title("Root Distribution Across Surahs (Top 50)")
plt.savefig("root_distribution_heatmap.png")
Jupyter Notebook Integration¶
# In a Jupyter notebook
from qurankit import Quran
from qurankit.analysis.reports import ComparisonReport
quran = Quran.load()
# Rich display
quran.surah(1) # Shows formatted surah info
quran.ayah(2, 255) # Shows formatted ayah
# Vocabulary display
vocab = quran.vocabulary
vocab.get_vocabulary_stats("ر ح م") # Rich HTML display
# Mutashabihat display
engine = quran.mutashabihat
engine.find_exact_phrases(min_length=3) # Interactive table
# Reports
report = ComparisonReport.generate(quran, reference=(2, 255))
report.display() # Rich HTML in notebook
Best Practices for Research¶
- Document everything — Use
ResearchRunto track datasets, parameters, versions - Version control — Save research runs as JSON, commit to git
- Report limitations — Note dataset coverage, annotation quality, method constraints
- Separate categories — Distinguish deterministic results from suggestions
- Reproducible seeds — Set random seeds for any stochastic methods
- Share data — Export results in open formats (CSV, JSON, Parquet)