pip install qardlar

pip install "qardlar[all]"

git clone https://github.com/merwanroudane/qardlar.git
cd qardlar
pip install -e ".[dev]"

import qardlar as qa
print(qa.__version__)
نتيجة = qa.qardl(qa.بيانات_تجريبية(500), 2, 1)
print(نتيجة.ملخص())

# ١) استيراد المكتبة. الاسم المختصر qa اصطلاح شائع.
import qardlar as qa

# ٢) تحميل بيانات. هنا نستخدم المجموعة المرفقة مع المكتبة.
#    البيانات مصفوفة أعمدتها [y, x1, x2]: العمود الأول هو المتغير التابع.
بيانات = qa.بيانات_تجريبية()

# ٣) تحديد الكمّيات التي نريد التقدير عندها.
#    0.25 = الربيع الأدنى، 0.50 = الوسيط، 0.75 = الربيع الأعلى.
الكمّيات = [0.25, 0.50, 0.75]

# ٤) التقدير: p=2 يعني إبطاءين للمتغير التابع،
#              q=1 يعني إبطاءًا واحدًا لفروق المتغيرات المستقلة.
نتيجة = qa.qardl(بيانات, 2, 1, الكمّيات)

# ٥) عرض جدول النتائج.
print(نتيجة.ملخص())

# ٦) الوصول إلى الأرقام مباشرةً.
print("المعاملات طويلة الأجل:")
print(نتيجة.إعادة_تشكيل("بيتا"))   # مصفوفة صفوفها الكمّيات وأعمدتها المتغيرات

print("سرعة التعديل عند كل كمّية:", نتيجة.رو)

$$ Q_{y_t}(\tau \mid \mathcal{F}_{t-1}) = \alpha(\tau)

• \sum_{i=1}^{k}\sum_{j=0}^{q-1} \gamma_{ij}(\tau),\Delta x_{i,t-j}
• \sum_{i=1}^{k} \theta_i(\tau), x_{it}
• \sum_{j=1}^{p} \phi_j(\tau), y_{t-j} $$

$$ \beta(\tau) = \frac{\theta(\tau)}{1 - \sum_{j=1}^{p}\phi_j(\tau)} \qquad\text{(المعامل طويل الأجل)} $$

$$ \rho(\tau) = -\Bigl(1 - \sum_{j=1}^{p}\phi_j(\tau)\Bigr) \qquad\text{(سرعة التعديل)} $$

import qardlar as qa                    # الطريقة الموصى بها
# أو استيراد ما تحتاجه فقط:
from qardlar import qardl, qardlFull, بيانات_تجريبية

import pandas as pd

df = pd.read_csv("بياناتي.csv")          # من ملف CSV
df = pd.read_excel("بياناتي.xlsx")       # من ملف Excel
print(df.head())                         # عرض أول خمسة صفوف
print(df.isna().sum())                   # فحص القيم المفقودة
df = df.dropna()                         # حذف الصفوف الناقصة

نتيجة = qa.qardlFull(df, 4, 4, formula="التضخم ~ سعر_الفائدة + سعر_الصرف")

بيانات = df[["التضخم", "سعر_الفائدة", "سعر_الصرف"]].to_numpy()
نتيجة = qa.qardl(بيانات, 2, 1)

نتيجة = qa.qardl(بيانات, 2, 1)     # p = 2، q = 1

p, q = qa.pqorder(بيانات, 8, 8, "bic")    # أو "aic" أو "hqc" أو "gets"
print(f"الرتب المختارة: p = {p}، q = {q}")
نتيجة = qa.qardl(بيانات, p, q)

نتيجة = qa.qardlX(بيانات, 2, [1, 3])   # q=1 للمتغير الأول، q=3 للثاني

نتيجة = qa.qardl(بيانات, 2, 1, [0.25, 0.50, 0.75])            # ثلاث كمّيات
نتيجة = qa.qardl(بيانات, 2, 1, [0.1, 0.25, 0.5, 0.75, 0.9])   # خمس كمّيات

import numpy as np
شبكة = np.arange(0.05, 1.0, 0.05)          # شبكة كثيفة لرسم مسار سلس
نتيجة = qa.qardl(بيانات, 2, 1, شبكة)

print(نتيجة.ملخص())                          # السمة الافتراضية
print(نتيجة.ملخص(السمة="journal"))           # أكثر إحكامًا
print(نتيجة.ملخص(فترات=False))               # بلا فترات ثقة
print(نتيجة.ملخص(مستوى_الثقة=0.99))          # فترات 99%

جدول = نتيجة.ملخص()
جدول.حفظ("النتائج.tex")      # LaTeX جاهز للورقة البحثية
جدول.حفظ("النتائج.html")     # HTML بدعم الاتجاه من اليمين لليسار
جدول.حفظ("النتائج.md")       # Markdown
جدول.حفظ("النتائج.xlsx")     # Excel
جدول.حفظ("النتائج.csv")      # CSV

df_نتائج = جدول.إلى_إطار()   # إطار بيانات للتحليل اللاحق

from qardlar.plots import رسم_QARDL, رسم_QIRF, رسم_البواقي, حفظ_الشكل

شكل = رسم_QARDL(نتيجة)                        # مسار المعالم عبر الكمّيات
شكل = رسم_QARDL(نتيجة, اللوحة="رمادية")       # للطباعة بالأبيض والأسود
حفظ_الشكل(شكل, "الشكل_1.pdf")                 # PDF متجهي للنشر
حفظ_الشكل(شكل, "الشكل_1.png", dpi=600)

حدود = qa.ardlbounds(بيانات, 2, 1)
print(حدود.ملخص())
print(حدود.القرار)     # نص عربي واضح بنتيجة الاختبار

تشخيص = qa.ardlResidualDiagnostics(نتيجة)
print(تشخيص.ملخص())

w = qa.qardlWald(نتيجة, بيانات, test="constancy")
print(w.ملخص())
# رفض فرضية العدم ⇒ المعالم تتغيّر فعلًا عبر الكمّيات ⇒ QARDL يضيف معلومة

# قيود مخصصة بصياغة نصية مقروءة:
w2 = qa.qardlWald(نتيجة, بيانات, test="custom", family="beta",
                  restrictions=["beta[1,0.25] = beta[1,0.75]"])

مقدَّر = qa.predictQARDL(نتيجة, بيانات)          # داخل العينة
توقع = qa.forecastQARDL(نتيجة, بيانات, h=12)     # خارج العينة

# مع مسار مفترض للمتغيرات المستقلة (تحليل سيناريو):
import numpy as np
مسار = بيانات[-1, 1:] + np.arange(1, 13)[:, None] * [0.1, -0.05]
توقع = qa.forecastQARDL(نتيجة, بيانات, h=12, future_x=مسار)

try:
    نتيجة = qa.qardl(بيانات, 0, 1)
except qa.QardlarLagError as خطأ:
    print(خطأ)     # qardl: p يجب أن يكون عددًا صحيحًا موجبًا

qa.set_language("en")     # للتبديل إلى الإنجليزية

نتيجة = qa.qardl(بيانات, 2, 1, الكمّيات, "iid")       # الافتراضي
نتيجة = qa.qardl(بيانات, 2, 1, الكمّيات, "robust")    # حصين لعدم التجانس
نتيجة = qa.qardl(بيانات, 2, 1, الكمّيات, "hac")       # HAC مع اقتطاع تلقائي
نتيجة = qa.qardl(بيانات, 2, 1, الكمّيات, "hac", 8)    # اقتطاع محدَّد

متدحرج = qa.rollingQardl(بيانات, 4, 4, [0.25, 0.5, 0.75], حجم_النافذة=250)
from qardlar.plots import رسم_المتدحرج
شكل = رسم_المتدحرج(متدحرج, معلمة="بيتا")

import qardlar as qa
import numpy as np
from qardlar.plots import رسم_QARDL, حفظ_الشكل

# ═══ ١. البيانات ═══════════════════════════════════════════════
# نستخدم هنا المجموعة المرفقة لأغراض العرض. في بحث حقيقي استبدلها
# ببياناتك: pd.read_csv("طاقة_ونمو.csv")
بيانات = qa.بيانات_تجريبية()

# ═══ ٢. سير العمل المتكامل ════════════════════════════════════
# ينفّذ الخطوات الأربع بترتيبها الصحيح:
#   اختيار الرتب ← اختبار الحدود ← تقدير المستويات ← تقدير ECM
نتيجة = qa.qardlFull(
    بيانات,
    pend=4, qend=4,                       # حدود البحث عن الرتب
    tau=[0.1, 0.25, 0.5, 0.75, 0.9],      # خمس كمّيات
    criterion="bic",
    cov_type="hac",                       # تباين حصين للارتباط الذاتي
)

# ═══ ٣. هل توجد علاقة توازنية طويلة الأجل؟ ═══════════════════
print(نتيجة.الحدود.ملخص())
print("القرار:", نتيجة.الحدود.القرار)
# ⚠️ إن كانت النتيجة "عدم رفض" فالمعاملات طويلة الأجل بلا معنى — توقّف هنا.

# ═══ ٤. النتائج ═══════════════════════════════════════════════
print(نتيجة.المستويات.ملخص())
print(نتيجة.ECM.ملخص())

# ═══ ٥. هل يضيف QARDL على ARDL فعلًا؟ ════════════════════════
w = qa.qardlWald(نتيجة.المستويات, بيانات, test="constancy")
print(w.ملخص())

# ═══ ٦. فحص افتراضات النموذج ═════════════════════════════════
print(نتيجة.تشخيص_المستويات.ملخص())

# ═══ ٧. الرسوم ════════════════════════════════════════════════
شكل = رسم_QARDL(نتيجة.المستويات)
حفظ_الشكل(شكل, "الشكل_1_مسار_المعالم.pdf")

# ═══ ٨. تصدير الجداول للورقة البحثية ═════════════════════════
نتيجة.المستويات.ملخص(السمة="journal").حفظ("الجدول_1.tex")
نتيجة.ECM.ملخص(السمة="journal").حفظ("الجدول_2.tex")

# ═══ ٩. القراءة الاقتصادية ═══════════════════════════════════
بيتا = نتيجة.المستويات.إعادة_تشكيل("بيتا")
for i, τ in enumerate(نتيجة.تاو):
    print(f"τ = {τ:.2f}:  β₁ = {بيتا[i, 0]:8.4f}   "
          f"ρ = {float(نتيجة.ECM.رو[i]):8.4f}")

@software{roudane_qardlar,
  author  = {Roudane, Merwan},
  title   = {{qardlar: Quantile Autoregressive Distributed Lag Models
             with an Arabic-first API}},
  year    = {2026},
  url     = {https://github.com/merwanroudane/qardlar}
}

@article{cho_kim_shin_2015,
  author  = {Cho, Jin Seo and Kim, Tae-Hwan and Shin, Yongcheol},
  title   = {Quantile cointegration in the autoregressive
             distributed-lag modeling framework},
  journal = {Journal of Econometrics},
  year    = {2015}, volume = {188}, number = {1}, pages = {281--300},
  doi     = {10.1016/j.jeconom.2015.05.003}
}