Metadata-Version: 2.4
Name: qardlar
Version: 0.2.0
Summary: QARDL, ARDL, NARDL and CS-ARDL estimation with an Arabic-first API — a faithful Python port of the GAUSS QARDL library
Author-email: Merwan Roudane <merwanroudane920@gmail.com>
Maintainer-email: Merwan Roudane <merwanroudane920@gmail.com>
License: MIT License
        
        Copyright (c) 2026 Merwan Roudane
        
        This package (`qardlar`) is a Python port of the GAUSS QARDL library
        version 3.1.1, which is distributed under the MIT License:
        
            Copyright (c) 2026 Aptech Systems, Inc.
        
        The original copyright notice and permission notice for the GAUSS QARDL
        library are reproduced in the NOTICE file, which is distributed with this
        software as required by the terms of that licence.
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/merwanroudane/qardlar
Project-URL: Repository, https://github.com/merwanroudane/qardlar
Project-URL: Issues, https://github.com/merwanroudane/qardlar/issues
Keywords: econometrics,QARDL,ARDL,NARDL,CS-ARDL,quantile regression,cointegration,time series,panel data,Arabic,الاقتصاد القياسي
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: Arabic
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: numpy>=1.23
Requires-Dist: scipy>=1.9
Requires-Dist: pandas>=1.5
Provides-Extra: plots
Requires-Dist: matplotlib>=3.6; extra == "plots"
Provides-Extra: excel
Requires-Dist: openpyxl>=3.1; extra == "excel"
Provides-Extra: dev
Requires-Dist: pytest>=7.4; extra == "dev"
Requires-Dist: pytest-cov>=4.1; extra == "dev"
Requires-Dist: matplotlib>=3.6; extra == "dev"
Requires-Dist: openpyxl>=3.1; extra == "dev"
Requires-Dist: jupyter; extra == "dev"
Requires-Dist: nbclient; extra == "dev"
Provides-Extra: all
Requires-Dist: matplotlib>=3.6; extra == "all"
Requires-Dist: openpyxl>=3.1; extra == "all"
Dynamic: license-file

<div dir="rtl">

# qardlar — نماذج الانحدار الذاتي الموزّع الكمي بواجهة عربية

[![الترخيص: MIT](https://img.shields.io/badge/الترخيص-MIT-blue.svg)](LICENSE)
[![Python 3.10+](https://img.shields.io/badge/Python-3.10%2B-blue.svg)](https://www.python.org)

مكتبة بايثون علمية لتقدير نماذج **QARDL** (الانحدار الذاتي الموزّع الكمي)
والاستدلال عنها، بواجهة عربية كاملة، منقولة عن مكتبة **GAUSS QARDL 3.1.1**
مع الحفاظ على المنهجية والخوارزميات وترتيب المعاملات وبنية المخرجات.

**المؤلف:** الدكتور مروان رودان — Dr. Merwan Roudane
**المستودع:** <https://github.com/merwanroudane/qardlar>

---

## المحتويات

1. [ما هي qardlar؟](#ما-هي-qardlar)
2. [التثبيت](#التثبيت)
3. [أول برنامج](#أول-برنامج)
4. [النموذج الرياضي](#النموذج-الرياضي)
5. [كيف تكتب كود qardlar؟](#كيف-تكتب-كود-qardlar)
6. [مثال اقتصادي كامل](#مثال-اقتصادي-كامل)
7. [مرجع سريع للدوال](#مرجع-سريع-للدوال)
8. [العلاقة بمكتبة GAUSS](#العلاقة-بمكتبة-gauss)
9. [الاستشهاد](#الاستشهاد)

---

## ما هي qardlar؟

### المشكلة التي تحلّها

نماذج ARDL التقليدية تقدّر أثرًا **واحدًا** لكل متغير مستقل: أثرًا على
*متوسط* المتغير التابع. لكن كثيرًا من الأسئلة الاقتصادية المهمة تتعلق بأجزاء
أخرى من التوزيع:

- هل يؤثر ارتفاع سعر النفط في النمو الاقتصادي بالقدر نفسه في سنوات الركود
  (الكمّيات الدنيا) وسنوات الرواج (الكمّيات العليا)؟
- هل تعديل سعر الصرف نحو التوازن طويل الأجل أسرع حين يكون التضخم مرتفعًا؟
- هل علاقة استهلاك الطاقة بالناتج المحلي ثابتة عبر التوزيع أم تتغيّر؟

يجيب **QARDL** عن هذه الأسئلة: يقدّر معالم النموذج عند **كل كمّية** من توزيع
المتغير التابع، فتحصل على `β(τ)` بدل `β` واحدة، وعلى سرعة تعديل `ρ(τ)` بدل
`ρ` واحدة.

### ما تقدّمه هذه المكتبة

| | |
|---|---|
| **واجهة عربية كاملة** | أسماء الدوال والمعاملات وحقول النتائج ورسائل الأخطاء بالعربية، مع مرادفات إنجليزية تطابق GAUSS |
| **مطابقة عددية موثّقة** | 19 اختبار مطابقة ضد نتائج GAUSS المرجعية، بأرقام مقيسة لا مزعومة |
| **جداول صالحة للنشر** | تصدير إلى LaTeX و HTML و Markdown و Excel، بأربع سمات أكاديمية |
| **رسوم بجودة النشر** | لوحات ألوان مناسبة للطباعة، بما فيها خيار رمادي خالص |
| **حلّال دقيق** | حل مسألة البرمجة الخطية مباشرةً مع صقل الحل، بدل التقريب التكراري |

### ما لا تقدّمه

عائلتا **NARDL** (اللاخطي) و **CS-ARDL** (البانل) **خارج نطاق** هذه المكتبة.
هذا قرار نطاق صريح: `qardlar` مكرّسة لعائلة QARDL وما تحتاجه فعليًا.

---

## التثبيت

### الطريقة المعتادة

</div>

```bash
pip install qardlar
```

<div dir="rtl">

### مع دعم الرسوم وتصدير Excel

</div>

```bash
pip install "qardlar[all]"
```

<div dir="rtl">

### من المستودع مباشرةً

</div>

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

<div dir="rtl">

### المتطلبات

| الحزمة | الغرض | إلزامية؟ |
|---|---|---|
| `numpy` ≥ 1.23 | العمليات المصفوفية | ✅ |
| `scipy` ≥ 1.9 | حلّال البرمجة الخطية والتوزيعات | ✅ |
| `pandas` ≥ 1.5 | إطارات البيانات والصيغ | ✅ |
| `matplotlib` ≥ 3.6 | الرسوم | اختيارية |
| `openpyxl` ≥ 3.1 | تصدير Excel | اختيارية |

### التحقق من التثبيت

</div>

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

<div dir="rtl">

---

## أول برنامج

هذا أصغر برنامج مفيد، مشروحًا سطرًا سطرًا.

</div>

```python
# ١) استيراد المكتبة. الاسم المختصر 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("سرعة التعديل عند كل كمّية:", نتيجة.رو)
```

<div dir="rtl">

---

## النموذج الرياضي

نموذج QARDL(p, q) عند الكمّية `τ` هو:

</div>

$$
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}
$$

<div dir="rtl">

وتُشتق منه الكميتان الأهم في التفسير الاقتصادي:

</div>

$$
\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{(سرعة التعديل)}
$$

<div dir="rtl">

### كيف تقرأ هذه المعالم؟

| المعلمة | المعنى | كيف تقرأها |
|---|---|---|
| `β(τ)` | الأثر طويل الأجل | تغيّر `y` عند الكمّية `τ` استجابةً لتغيّر دائم بوحدة واحدة في `x` |
| `ρ(τ)` | سرعة التعديل | نسبة الانحراف عن التوازن التي تُصحَّح في فترة واحدة. **يجب أن تكون سالبة** |
| `γ(τ)` | الأثر قصير الأجل | الاستجابة الفورية لتغيّر `x` |
| `φ(τ)` | الإبطاء الذاتي | استمرارية `y` عبر الزمن |

**قراءة مسار `β(τ)`:** إذا كان مسطّحًا عبر الكمّيات فالأثر متجانس، ولا يضيف
QARDL على ARDL. أما إن كان مائلًا أو متعرّجًا فالأثر يختلف باختلاف موضع
التوزيع، وهذا هو مبرر استخدام QARDL.

### الافتراضات الأساسية

1. **`p ≥ 1` مطلوبة**؛ الحالة `p = 0` غير مدعومة. أما `q = 0` فمدعومة.
2. **يفترض تفسير `β` وجود تكامل مشترك** بين `y` و `x`. افحص ذلك باختبار
   الحدود قبل تفسير المعاملات طويلة الأجل.
3. البيانات مرتّبة زمنيًا وخالية من القيم المفقودة.

---

## كيف تكتب كود qardlar؟

دليل عملي خطوة بخطوة. يفترض أنك تعرف الاقتصاد القياسي لكنك جديد على بايثون.

### ١. كيف أستورد المكتبة؟

</div>

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

<div dir="rtl">

### ٢. كيف أقرأ ملف بياناتي؟

</div>

```python
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()                         # حذف الصفوف الناقصة
```

<div dir="rtl">

### ٣. كيف أحدّد المتغير التابع والمستقلة؟

طريقتان:

**الأولى — بالصيغة (الأوضح):** تكتب الصيغة فتتولى المكتبة ترتيب الأعمدة.
أسماء الأعمدة العربية مدعومة بلا قيود.

</div>

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

<div dir="rtl">

**الثانية — بترتيب الأعمدة:** تُرتِّب البيانات بنفسك بحيث يكون المتغير التابع
في العمود الأول.

</div>

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

<div dir="rtl">

### ٤. كيف أحدّد الإبطاءات؟

**يدويًا:**

</div>

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

<div dir="rtl">

**آليًا بمعيار معلومات:**

</div>

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

<div dir="rtl">

**برتبة مختلفة لكل متغير:**

</div>

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

<div dir="rtl">

### ٥. كيف أحدّد الكمّيات؟

</div>

```python
نتيجة = 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, شبكة)
```

<div dir="rtl">

> **نصيحة:** الكمّيات القصوى (أقل من 0.05 أو أكثر من 0.95) تحتاج عينات كبيرة
> لأن عدد المشاهدات في ذيل التوزيع قليل.

### ٦. كيف أطبع جدول النتائج؟

</div>

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

<div dir="rtl">

السمات المتاحة: `academic` (الافتراضية) و `journal` و `compact` و
`presentation`.

### ٧. كيف أحفظ الجدول؟

</div>

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

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

<div dir="rtl">

### ٨. كيف أرسم النتائج؟

</div>

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

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

<div dir="rtl">

### ٩. كيف أجري اختبار الحدود؟

خطوة **ضرورية** قبل تفسير المعاملات طويلة الأجل.

</div>

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

<div dir="rtl">

### ١٠. كيف أجري الاختبارات التشخيصية؟

</div>

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

<div dir="rtl">

يشمل: Ljung-Box و Breusch-Godfrey للارتباط الذاتي، Breusch-Pagan و ARCH
لعدم تجانس التباين، Jarque-Bera للاعتدالية، Ramsey RESET للشكل الدالي،
CUSUM و CUSUMSQ للاستقرار.

### ١١. كيف أختبر تغيّر المعالم عبر الكمّيات؟

هذا هو الاختبار الذي يبرّر استخدام QARDL أصلًا:

</div>

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

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

<div dir="rtl">

### ١٢. كيف أجري التنبؤ والتوقع؟

</div>

```python
مقدَّر = 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=مسار)
```

<div dir="rtl">

### ١٣. كيف أتعامل مع الأخطاء؟

رسائل الأخطاء بالعربية وتشرح المشكلة تحديدًا:

</div>

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

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

<div dir="rtl">

| نوع الخطأ | متى يقع |
|---|---|
| `QardlarLagError` | رتبة إبطاء غير صالحة |
| `QardlarQuantileError` | كمّية خارج `(0, 1)` أو مكرّرة |
| `QardlarDataError` | قيم مفقودة أو شكل بيانات خاطئ |
| `QardlarSampleError` | مشاهدات غير كافية للرتب المطلوبة |
| `QardlarLinAlgError` | مصفوفة تصميم ناقصة الرتبة |
| `QardlarOptionError` | قيمة خيار غير مدعومة |

### ١٤. كيف أغيّر مقدّر التباين؟

</div>

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

<div dir="rtl">

> ⚠️ **تنبيه مهم:** يخزّن المسار `iid` تباين `β` بمقياس `(n−1)²` وتباين `φ`
> و `γ` بمقياس `(n−1)`، وهو اصطلاح موروث من المكتبة الأصلية. **لا تقارن
> `تباين_بيتا` الخام بين مسارين مختلفين**؛ استخدم دائمًا
> `نتيجة.أخطاء_معيارية()` التي تزيل المقياس.

### ١٥. كيف أفحص استقرار المعالم عبر الزمن؟

</div>

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

<div dir="rtl">

---

## مثال اقتصادي كامل

**السؤال البحثي:** هل يختلف أثر استهلاك الطاقة في النمو الاقتصادي باختلاف
وتيرة النمو نفسها؟ الفرضية أن الأثر أقوى في سنوات النمو الضعيف، حيث تكون
الطاقة قيدًا فعّالًا، وأضعف في سنوات النمو القوي.

</div>

```python
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}")
```

<div dir="rtl">

### كيف تفسّر هذه المخرجات في ورقتك

1. **اختبار الحدود أولًا.** إن لم تُرفض فرضية العدم فلا تفسّر `β` إطلاقًا.
2. **مسار `β(τ)`.** ميل المسار هو النتيجة البحثية: انحداره يعني أن الأثر
   أقوى في الكمّيات الدنيا.
3. **اختبار الثبات.** رفضه هو ما يبرّر منهجيًا استخدام QARDL بدل ARDL.
4. **`ρ(τ)` سالبة ومعنوية** تدل على التعديل نحو التوازن. اختلاف مقدارها عبر
   الكمّيات يعني أن سرعة العودة إلى التوازن تتوقف على حالة الاقتصاد.
5. **التشخيص.** لا تنشر نتائج نموذج فشل في اختبارات الارتباط الذاتي أو
   الاستقرار.

> ⚠️ **تحذير سببي.** نماذج ARDL/QARDL تصف علاقات ديناميكية وارتباطات شرطية،
> ولا تُثبت سببية بذاتها. لا تصف النتائج بلغة سببية ما لم يوفّر تصميمك
> البحثي مبرّرًا لذلك (تجربة طبيعية، متغيرات مساعدة، أو ما شابه).

---

## مرجع سريع للدوال

| ما تريد فعله | الأمر |
|---|---|
| تقدير QARDL | `qa.qardl(بيانات, p, q, tau)` |
| تقدير بتباين حصين | `qa.qardlRobust(بيانات, p, q, tau)` |
| تقدير بتباين HAC | `qa.qardlHAC(بيانات, p, q, tau)` |
| رتبة إبطاء لكل متغير | `qa.qardlX(بيانات, p, [q1, q2], tau)` |
| نموذج تصحيح الخطأ | `qa.qardlECM(بيانات, p, q, tau)` |
| **سير العمل المتكامل** | `qa.qardlFull(بيانات, 8, 8, tau)` |
| اختيار الإبطاءات | `qa.pqorder(بيانات, 8, 8, "bic")` |
| اختبار الحدود | `qa.ardlbounds(بيانات, p, q)` |
| اختبار الحدود بحالة | `qa.ardlboundsCase(بيانات, p, q, 3)` |
| القيم الاحتمالية | `qa.qardl_pval(نتيجة)` |
| اختبار ثبات المعالم | `qa.qardlWald(نتيجة, بيانات, test="constancy")` |
| اختبار التماثل | `qa.qardlWald(نتيجة, بيانات, test="symmetry")` |
| تشخيص البواقي | `qa.ardlResidualDiagnostics(نتيجة)` |
| استجابة نبضية | `qa.qirf(نتيجة, p, q, H)` |
| استجابة بنطاقات ثقة | `qa.blockBootstrapQIRF(بيانات, p, q, H)` |
| فترات bootstrap | `qa.blockBootstrapQARDL(بيانات, p, q, tau)` |
| تقدير متدحرج | `qa.rollingQardl(بيانات, 8, 8, tau)` |
| تنبؤ داخل العينة | `qa.predictQARDL(نتيجة, بيانات)` |
| توقع خارج العينة | `qa.forecastQARDL(نتيجة, بيانات, h)` |
| طباعة جدول | `print(نتيجة.ملخص())` |
| حفظ جدول | `نتيجة.ملخص().حفظ("ملف.tex")` |
| رسم المعالم | `qa.plots.رسم_QARDL(نتيجة)` |

انظر [`docs/CHEATSHEET_AR.md`](docs/CHEATSHEET_AR.md) للمرجع الكامل.

---

## العلاقة بمكتبة GAUSS

`qardlar` **نقل** لمكتبة GAUSS QARDL 3.1.1، لا إعادة تصميم. حُوفظ على:

- أسماء الإجراءات وترتيب معاملاتها وقيمها الافتراضية
- أسماء حقول المخرجات (كمرادفات إنجليزية)
- الخوارزميات ومسارات التباين الثلاثة
- الاصطلاحات العددية، بما فيها ما قد يبدو غريبًا (انظر §4.5 من ملف التوافق)

### مستوى المطابقة العددية

| المكوّن | أقصى فرق | الحالة |
|---|---:|---|
| معاملات ARDL طويلة الأجل | `1.0e-10` | ✅ |
| اختبار الحدود | `2.8e-10` | ✅ |
| جدول القيم الحرجة PSS | `0` | ✅ مطابقة تامة |
| QARDL عند `τ = 0.25` و `0.75` | `8.8e-11` | ✅ |
| QARDL عند `τ = 0.50` | `5.1e-08` | ⚠️ موثّق |
| كل ما يعتمد على العشوائية | — | ⛔ مكافئ إحصائيًا لا رقميًا |

الفرق عند الوسيط يقع **دون الدقة التي تنشر بها GAUSS معاملاتها نفسها**،
ويتسق مع عدم وحدانية حل انحدار الوسيط. التفاصيل الكاملة والأدلة في
[`docs/GAUSS_PYTHON_COMPATIBILITY.md`](docs/GAUSS_PYTHON_COMPATIBILITY.md).

### للقادمين من GAUSS

انظر [`docs/GAUSS_TO_QARDLAR.md`](docs/GAUSS_TO_QARDLAR.md) لدليل التحويل
سطرًا بسطر.

---

## الوثائق

| الملف | المحتوى |
|---|---|
| [`docs/ARABIC_SYNTAX_GUIDE.md`](docs/ARABIC_SYNTAX_GUIDE.md) | دليل كتابة الكود خطوة بخطوة |
| [`docs/GAUSS_TO_QARDLAR.md`](docs/GAUSS_TO_QARDLAR.md) | دليل الانتقال من GAUSS |
| [`docs/GAUSS_PYTHON_COMPATIBILITY.md`](docs/GAUSS_PYTHON_COMPATIBILITY.md) | مصفوفة التوافق العددي |
| [`docs/ARABIC_TERMINOLOGY.md`](docs/ARABIC_TERMINOLOGY.md) | قاموس المصطلحات المعتمد |
| [`docs/CHEATSHEET_AR.md`](docs/CHEATSHEET_AR.md) | مرجع سريع |
| [`examples/`](examples/) | أمثلة ودفاتر تعليمية |

---

## الاستشهاد

إن استخدمت هذه المكتبة في عمل أكاديمي، فاستشهد بالمكتبة **وبالمنهجية**:

</div>

```bibtex
@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}
}
```

<div dir="rtl">

انظر [`CITATION.md`](CITATION.md) للتفاصيل، ولا تنسَ الاستشهاد بمكتبة GAUSS
الأصلية إن قارنت بها.

---

## الترخيص

MIT. هذه المكتبة نقل لمكتبة GAUSS QARDL 3.1.1 المرخّصة كذلك بـ MIT
(© 2026 Aptech Systems, Inc.). انظر [`LICENSE`](LICENSE) و
[`NOTICE`](NOTICE).

لا تتبنّى Aptech Systems ولا مؤلفو المنهجية هذا النقل ولا يتحملون مسؤوليته.

</div>
