الصفحاتعوامل فاما-فرينش · 12 / 29

عوامل فاما-فرينش

يستطيع QuantCraft تحميل مجموعات بيانات عالمية لعوائد عوامل فاما-فرينش إلى جانب أعمدة الأسعار OHLCV أثناء اختبار رجعي أو تشغيل أمامي. وهي عوائد عوامل شهرية (FF3 وFF5) تُجلب مرة واحدة لكل تشغيل — لا لكل رمز. أما القوائم المالية لكل رمز فميزة منفصلة؛ راجع البيانات الأساسية.

تغطي هذه الصفحة:

كيف تختلف بيانات فاما-فرينش عن البيانات الأساسية وعن واجهة Factor Exposure في رسم Trade
المتطلبات وكيفية تفعيل الميزة في نوافذ التشغيل
كيف تقرأ صفوف العوامل في شيفرة استراتيجيتك

فاما-فرينش مقابل البيانات الأساسية

	البيانات الأساسية	عوامل فاما-فرينش
البيانات	ملفات لكل رمز (الميزانية والأرباح …)	مجموعة بيانات عوامل شهرية عالمية واحدة
الوصول من الخوارزمية	وسيط الاستدعاء `fundamentals` (`fundamentals.current(...)`)	كائن الوحدة الوحيد `fama_french.qc`
وسيط الاستدعاء المسمّى	نعم — `on_bar(..., fundamentals=...)`	لا — اقرأ `fama_french.qc` داخل أي دالة استدعاء

رموز OHLCV وحزم البيانات الأساسية وعوامل فاما-فرينش مستقلة — يمكنك تفعيل أي تركيبة في نافذة التشغيل.

ليست علامة تبويب Factor Exposure في رسم Trade

تُجري علامة التبويب Fundamentals → Factor Exposure في رسم Trade انحدار FF3/FF5 من جهة العميل مقابل OHLC الرسم. وهذه الواجهة خارج نطاق الخوارزميات. تتلقى الاستراتيجيات فقط صفوف عوائد العوامل الشهرية الخام (ff3_monthly وff5_monthly).

المتطلبات

اشتراك Premium في QuantCraft، أو الوصول إلى البيانات المجانية عند تفعيل ذلك الاستثناء (البوابة نفسها للبيانات الأساسية).
تسجيل الدخول — يُرسل رمز جلسة QuantCraft صالح عند تفعيل خانة الاختيار.
الواجهة: Include Fama-French factors (global) مفعّلة افتراضيًا عندما تسمح بوابة البيانات بذلك — في Run backtest (Symbol & data) والتشغيل الأمامي الجماعي وChart forward test. ألغِ التحديد لحذف بيانات العوامل في ذلك التشغيل.

اضبط من Test (تشغيل الشيفرة) للاختبارات الرجعية، أو من Algo Trading Parameters في عمليات التشغيل الأمامية على الرسم البياني.

بداية سريعة

بعد أن يحمّل المحرك بيانات العوامل، اقرأ الكائن الوحيد داخل دالة استدعاء:

from quantcraft import fama_french

_ff3 = None  # oldest-first rows, built once

def factor_row_before(bar_t):
    """Latest FF3 month that ended before this bar's month (no look-ahead)."""
    global _ff3
    if _ff3 is None:
        _ff3 = fama_french.qc.rows_chronological("ff3_monthly")
    t = str(bar_t)
    bar_yyyymm = t[:4] + t[5:7]          # works for "2024-01-02" and ISO timestamps
    rows = [r for r in _ff3 if r["yyyymm"] < bar_yyyymm]
    return rows[-1] if rows else None

def on_bar(bar_index, bar, fundamentals=None, symbol=None):
    if fama_french.qc is None:
        return  # checkbox off or load failed
    row = factor_row_before(bar["t"])
    if row:
        mkt_rf = float(row.get("Mkt-RF", 0))
        smb = float(row.get("SMB", 0))
        hml = float(row.get("HML", 0))

الاختبارات الرجعية: لا تستخدم latest_row داخل دوال الاستدعاء. تُحمَّل بيانات العوامل مرة واحدة، حتى تاريخ اليوم، ولا تُصفّى بحسب العمود قيد المحاكاة. يُرجع latest_row("ff3_monthly") دائمًا أحدث شهر في مجموعة البيانات كلها — وفي عمود من 2015 يكون ذلك شهرًا حاضرًا، وهذا انحياز استشرافي. اختر الشهر من تاريخ العمود نفسه (كما أعلاه) أو بـ qc.row("ff3_monthly", "YYYYMM"). ولا بأس بـ latest_row في تشغيل أمامي، حيث يكون "الأحدث" هو الحاضر فعلًا.

النمط المفضّل: from quantcraft import fama_french ثم اقرأ fama_french.qc داخل دوال الاستدعاء (on_init وon_bar وon_tick …). لا تستخدم from quantcraft.fama_french import qc على مستوى الوحدة العلوي — فهذا يلتقط None عند الاستيراد قبل أن يحمّل المحرك البيانات.

البدائل: المتغير العام في النص qc_fama_french (يُحقن في ملف خوارزميتك الجذري)، أو import quantcraft.process.runtime as rt ثم rt.qc_fama_french في دوال الاستدعاء — وكلها الكائن نفسه عند ضبطه؛ فضّل fama_french.qc في الشيفرة الجديدة.

لا يزال المسار الأقدم from ide.factors_module import … يعمل للاستراتيجيات الحالية؛ اكتب الشيفرة الجديدة على quantcraft.fama_french. وquantcraft.fama_french اسم بديل للوحدة، لذا يقرأ fama_french.qc القيمة الحيّة للجلسة — راجع مقابض الوحدات مقابل الأسماء المستوردة.

قراءة صفوف العوامل

تعيش البيانات الشهرية في مجموعات بيانات مفهرسة بسلاسل YYYYMM (مثل "192607")، لا بفهارس قوائم.

الدالة	الغرض
`qc.row("ff3_monthly", "202604")`	شهر محدد واحد، أو `None`
`qc.rows_chronological("ff5_monthly")`	قائمة الأقدم أولًا؛ كل عنصر يتضمن `yyyymm`. قائمة فارغة لمفتاح غير معروف.
`qc.latest_row("ff3_monthly")`	أحدث شهر في مجموعة البيانات كلها بصيغة `{ yyyymm, Mkt-RF, SMB, HML, RF, … }`، أو `None`. لا يراعي العمود — للتشغيل الأمامي فقط (راجع التحذير أعلاه).
`qc.dataset(key)`	قاموس مجموعة البيانات الخام لذلك المفتاح (`columns` و`rows` …)، أو `None` عند غياب المفتاح
`qc.raw` / `qc.datasets` / `qc.updated_at`	الحمولة الكاملة و`raw["datasets"]` ووقت التحديث بتوقيت UTC بعد تحليله (أو `None`)

سطح الاستيراد الكامل (quantcraft.fama_french): QcFamaFrench(token, *, base_url=None) — يبني ويجلب فورًا (لا تنشئه عادةً؛ فالتشغيل يفعل ذلك)؛ وload_qc_fama_french_from_config(cfg)؛ والمساعدان البسيطان factor_rows_chronological(dataset) / latest_factor_row(dataset) اللذان يعملان على قاموس مجموعة بيانات خام.

معرّفات مجموعات البيانات:

المفتاح	المحتوى
`ff3_monthly`	عوائد فاما-فرينش الشهرية بثلاثة عوامل
`ff5_monthly`	عوائد فاما-فرينش الشهرية بخمسة عوامل

مفاتيح FF3 المعتادة: Mkt-RF وSMB وHML وRF. ويضيف FF5 كلًّا من RMW وCMA. القيم سلاسل عشرية (النسبة المئوية ÷ 100) — استخدم float(...) في العمليات الحسابية.

# Helpers (recommended)
history = fama_french.qc.rows_chronological("ff5_monthly")   # oldest-first
jan_2024 = fama_french.qc.row("ff5_monthly", "202401")

# Raw dict access (keys are YYYYMM strings — not rows[0] / rows[-1])
ff3_rows = fama_french.qc.datasets["ff3_monthly"]["rows"]
july_1926 = ff3_rows["192607"]

التفعيل في بيئة التطوير

Run backtest

في Test → Run backtest → Symbol & data حدّد Include Fama-French factors (global) (مفعّلة افتراضيًا عندما تسمح بوابة البيانات بذلك). يتطلب تسجيل الدخول. يحمّل المحرك البيانات قبل تشغيل on_init() لديك.

لا يوجد وسيط استدعاء factors= في on_tick / on_bar. استورد quantcraft.fama_french واستخدم fama_french.qc.

Chart forward test

في Trade → Algo Trading Parameters استخدم خانة الاختيار Include Fama-French factors (global) نفسها (مفعّلة افتراضيًا لـ Premium).

التشغيل الأمامي الجماعي / QuantCloud

في نافذة New Run للتشغيل الأمامي الجماعي (التداول الآلي (AutoTrading) أو QuantCloud) استخدم Include Fama-French factors (global) في علامة التبويب Schedule & data (مفعّلة افتراضيًا). راجع QuantCloud وإعدادات التشغيل المسبقة (.qcs).

إعدادات التشغيل المسبقة (.qcs)

يمكن أن تتضمن إعدادات التشغيل المحفوظة:

{ "includeFactors": true }

يتطلب تحميل إعداد مسبق فيه includeFactors: true اشتراك Premium؛ وتمسح الفئة المجانية هذه العلامة عند التحميل. راجع إعدادات التشغيل المسبقة (.qcs).

أخطاء شائعة

rows[0] / rows[-1] — غير صالح. dataset["rows"] قاموس مفهرس بـ "YYYYMM" لا قائمة. استخدم row أو rows_chronological (أو latest_row في عمليات التشغيل الأمامية).
from quantcraft.fama_french import qc في أعلى الملف — يلتقط None قبل أن يحمّل المحرك البيانات.
توقّع دالة استدعاء factors= — استخدم fama_french.qc داخل on_init / on_bar / on_tick بدلًا من ذلك.
latest_row في اختبار رجعي — يُرجع أحدث شهر اليوم في كل عمود تاريخي (استشراف). اختر الشهر من تاريخ العمود.

السلوك عند الفشل

إذا كانت خانة الاختيار مفعّلة لكن الجلب فشل، يستمر التشغيل ويطبع رسالة — factors load failed: … (الاختبار الرجعي / Debug Test) أو forward factors load failed: … أو bulk factors load failed: … — ويترك fama_french.qc = None. راجع لوحة المخرجات. تحقّق دائمًا قبل الاستخدام.