Skip to content

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

  1. Document everything — Use ResearchRun to track datasets, parameters, versions
  2. Version control — Save research runs as JSON, commit to git
  3. Report limitations — Note dataset coverage, annotation quality, method constraints
  4. Separate categories — Distinguish deterministic results from suggestions
  5. Reproducible seeds — Set random seeds for any stochastic methods
  6. Share data — Export results in open formats (CSV, JSON, Parquet)

Next Steps