الرسوم البيانية والدوال المساعدة للبحث

بعد نجاح Load data into Rust، تستطيع خلايا البحث استخدام هذه الدوال المساعدة. هي دوال خاصة بالدفاتر يوفّرها AQS، وليست واجهات API إضافية لاستراتيجيات AQE. بعد ترقية AQS، حمّل البيانات مرة أخرى لتثبيت الدوال الجديدة في جلسة موجودة.

البيانات المتاحة للخلايا

تمثّل data مجموعة AqsData مفهرسة بالرموز المحمّلة. وتغلّف HashMap<String, DataFrame>، مع دعم الفهرسة (data["BTCUSD"]) وget وinsert وغيرها من دوال الخريطة عبر فك المرجع. وليست اسمًا مستعارًا لنوع HashMap. وتظل bars نسخة عمل من بيانات أول رمز محمّل. تُخزَّن الطوابع الزمنية التاريخية كعدد الميلي ثانية منذ بداية توقيت Unix بتوقيت UTC، في عمود Int64 اسمه timestamp.

data.symbols()                  // Sorted symbol names

data.summary()?;                // Table of symbols, row counts and columns
let mut btc = data.bars("BTCUSD")?;
let mut eth = data.bars("ETHUSD")?;

استخدم رموز المزوّد الدقيقة، مثل BTC-USD في Yahoo. ينتج عن الرمز المفقود خطأ يسرد الرموز المتاحة. يعيد كل استدعاء bars نسخة عمل مستقلة من Polars: حساب المؤشرات على btc لا يغيّر data أو eth. والدالتان المستقلتان المكافئتان هما aqs_symbols(&data) وaqs_bars(&data, "BTCUSD")?.

يمكن لمنتقي Loaded symbols في لوحة الجلسة إضافة خلية جدول وشموع جاهزة لرمز واحد. وهو يدرج الشيفرة دون تنفيذها.

معاينات الجداول

aqs_table(&bars, 10)?;

تعيد aqs_table(frame: &DataFrame, limit: usize) قيمة Result<(), Box<dyn std::error::Error>>. وتصدر أسماء الأعمدة والقيم المنسّقة دون تعديل إطار البيانات.

تُخرج الدالة ما يصل إلى 100 صف، ويعرض العارض ما يصل إلى 50 عمودًا. ولا تؤدي حدود المعاينة إلى اقتطاع إطار البيانات المتاح للتحليل.

الخطوط البسيطة والطبقات المتراكبة

aqs_plot(&bars, "close")?;
aqs_plot_many(&bars, &["close", "EMA_20", "EMA_50"])?;

تعيد aqs_plot(frame: &DataFrame, column: &str) قيمة Result<(), Box<dyn std::error::Error>>. يجب أن يكون العمود المحدد قابلًا للتحويل إلى Float64؛ وأن يكون timestamp من نوع Int64 بالميلي ثانية. تؤدي الأعمدة المفقودة أو الأنواع غير المتوافقة إلى خطأ في الخلية.

ينشئ كل استدعاء مخططًا واحدًا؛ وتضع aqs_plot_many عدة خطوط على محور السعر نفسه. يجب أن تكون الأعمدة المسماة موجودة بالفعل. ويمكن إصدار الجداول والمخططات من الخلية نفسها، بترتيب الاستدعاءات:

aqs_table(&bars, 5)?;
aqs_plot(&bars, "close")?;

الشموع والمتوسطات المتحركة واللوحات المتزامنة

إعداد مخطط البحث ومخرجاته: شموع BTCUSD مع طبقتين لمتوسطين متحركين ومدرج تكراري لحجم التداول وخط ATR في لوحات متزامنة. عرض لقطة الشاشة بالحجم الكاملعرض لقطة الشاشة بالحجم الكامل.

use aq_engine::core::indicators::{
    Indicator, atr::AverageTrueRange, ema::ExponentialMovingAverage,
};
let mut btc = data.bars("BTCUSD")?;
let mut atr = AverageTrueRange::new(14);
atr.run(&mut btc)?;
let mut ema20 = ExponentialMovingAverage::new(20, "close");
ema20.run(&mut btc)?;
let mut ema50 = ExponentialMovingAverage::new(50, "close");
ema50.run(&mut btc)?;

aqs_chart(&btc)
    .title("BTCUSD · trend and volatility")
    .candles()
    .line("EMA_20").label("EMA 20")
    .line("EMA_50").label("EMA 50")
    .pane("Volume", |p| p.histogram("volume"))
    .pane("ATR", |p| p.line("ATRr_14"))
    .height(650)
    .max_points(1000)
    .show()?;

تعمل مؤشرات AQE على إطارات بيانات Polars المعتادة. حمّل بيانات تاريخية تكفي لأطول فترة ولتهيئتها. يرسم منشئ المخططات الأعمدة فقط، ولا يحسب مؤشرًا لمجرد تمرير اسمه إلى line. إذا لم يحتوِ العمود على أي قيمة عددية منتهية، يظهر خطأ في الخلية.

يدعم منشئا المخطط الرئيسي واللوحات .line(column) و.area(column) و.histogram(column) و.candles() و.ohlc(). تعيد .label(text) تسمية آخر سلسلة في ذلك المنشئ. تتطلب الشموع وأعمدة OHLC الأعمدة open وhigh وlow وclose. وتتطلب جميع السلاسل الزمنية timestamp.

تدعم الرسوم الزمنية في الدفاتر التكبير والتحريك، ومحورًا زمنيًا مشتركًا، وقراءات عند تمرير المؤشر، وألوانًا تلقائية للسلاسل، وفواصل تتيح تغيير أحجام اللوحات. لكل لوحة مقياس رأسي خاص بها، وتشترك السلاسل المتراكبة داخل اللوحة في هذا المقياس. ضع السلاسل ذات الوحدات المختلفة، مثل السعر وحجم التداول، في لوحات مختلفة. تقبل .height(pixels) قيمًا من 240–1200، ويزداد الارتفاع الافتراضي مع عدد اللوحات. تُدعَم ست لوحات واثنتا عشرة سلسلة إجمالًا كحد أقصى.

أخذ عينات المعاينة وسلامة البيانات

يرتّب المخطط البيانات المعروضة بحسب الطابع الزمني ويحوّل الميلي ثانية إلى ثوانٍ. عندما تقع عدة صفوف في الثانية نفسها، يُعتمَد آخر صف من المصدر بصورة متسقة عبر السلاسل المتراكبة. تُستبعَد الطوابع الزمنية الفارغة أو الخارجة عن النطاق. وتُستبعَد أيضًا القيم الفارغة أو غير الصالحة كأعداد منتهية، بما فيها قيم فترة تهيئة المؤشرات. لا تُضاف مشاهدات جديدة لملء الفجوات، لكن الخط المرسوم قد يصل بصريًا بين النقاط المتبقية.

تستخدم الرسوم الزمنية الكبيرة مجموعات صفوف مشتركة عبر جميع اللوحات. تستخدم الشمعة أول سعر افتتاح صالح، وأعلى سعر، وأدنى سعر، وآخر سعر إغلاق صالح ضمن مجموعتها. تجمع أعمدة المدرج قيم المجموعة، وتستخدم الخطوط والمساحات آخر قيمة عددية منتهية. توضع كل مجموعة عند طابعها الزمني الأخير. هذا تجميع للعرض فقط: لا يتغير إطار البيانات المصدر ولا حسابات البحث ولا الاختبارات التاريخية. تؤدي حدود OHLC غير الصالحة أو التجاوز العددي إلى خطأ.

تقبل .max_points(n) القيم 2–2000، بافتراضي 1000، كهدف لكل سلسلة. تقلل الدالة المساعدة ذلك الهدف عند الحاجة لإبقاء المخرجات الكلية دون 4000 نقطة و240 KiB. يبيّن التعليق عدد صفوف المصدر وحجم المجموعة. استخدم نطاق تواريخ أضيق عند فحص شموع فردية.

مخططات التشتت والتوزيعات

aqs_scatter(&btc, "volume", "ATRr_14")?;
aqs_histogram(&btc, "ATRr_14", 30)?;

تقرن aqs_scatter(frame, x_column, y_column) القيم من صف المصدر نفسه. وتزيل الأزواج التي تتضمن قيمًا مفقودة أو غير صالحة كأعداد منتهية، وتأخذ عينة لا تتجاوز 2000 زوج للعرض.

توزّع aqs_histogram(frame, column, bins) جميع المشاهدات ذات القيم العددية المنتهية على 2–100 فئة عددية. يتحول العمود ذو القيمة الثابتة إلى فئة واحدة. ويذكر التعليق عدد المشاهدات المستبعَدة بسبب قيم مفقودة أو غير صالحة كأعداد منتهية. هذا رسم للتوزيع، بخلاف .histogram("volume") في منشئ المخططات، التي ترسم القيم مقابل الوقت.

يستخدم هذان النوعان من المخططات محاور عددية وتلميحات SVG، لا أدوات التكبير والتحريك الخاصة بمخططات الوقت. ولا يحتاجان إلى عمود طابع زمني.

مقارنة الرموز على أساس مشترك

aqs_compare(&data, &["BTCUSD", "ETHUSD", "SOLUSD"], "close")?;

قارن أسعار إغلاق BTCUSD وETHUSD وSOLUSD من نقطة بداية مشتركة بمؤشر 100. تعرض الخطوط تغيرات الأسعار النسبية، لا عوائد الاستراتيجية. عرض لقطة شاشة المقارنة بالحجم الكاملعرض لقطة شاشة المقارنة بالحجم الكامل.

اختر 2–8 رموز محمّلة مختلفة. يبدأ كل خط من قيمة أساس 100 عند أول طابع زمني مطابق لدى جميع الرموز، تكون فيه قيمها أعدادًا منتهية وموجبة. لا تُعوَّض الطوابع الزمنية المفقودة لاحقًا بالقيم السابقة، وتحتفظ كل سلسلة بمشاهداتها الخاصة. إذا لم توجد نقطة بداية مشتركة، تعيد الدالة خطأً. يأخذ العرض عينات من كل سلسلة لتصبح نحو 400 نقطة، مع الاحتفاظ بأول مشاهدة وآخرها.

هذه مقارنة أسعار موحّدة الأساس، وليست منحنى لحقوق ملكية استراتيجية أو عائد محفظة أو حساب ارتباط. وهي لا تعدّل بيانات الأدوات المالية لمراعاة التكاليف أو إجراءات الشركات أو اختلاف العملات. استخدم بيانات مدخلات معدّلة بما يناسب دراستك.

مخرجات منظمة مخصصة

تصدر aqs_emit(value: serde_json::Value) معاينة منظمة واحدة. فضّل الدوال السابقة للمخططات. ويحتفظ العارض أيضًا بالدعم القديم لـtable وline:

aqs_emit(serde_json::json!({
    "kind": "table",
    "columns": ["Metric", "Value"],
    "rows": [["Observations", bars.height().to_string().as_str()]],
    "totalRows": 1
}));

aqs_emit(serde_json::json!({
    "kind": "line",
    "label": "Example series",
    "points": [
        {"time": 1791241200, "value": 1.0},
        {"time": 1791241260, "value": 1.2}
    ]
}));

الطوابع الزمنية للخطوط المخصصة هي ثواني Unix، بخلاف الميلي ثانية في إطار البيانات. ينبغي أن تكون أعمدة الجداول وقيم الخلايا سلاسل نصية. تصدر الدوال الجديدة مواصفات الإصدار 1 لكل من chart وscatter وdistribution وheatmap. لفحص حمولة بيانات منشئ دون عرضها، استخدم .build()? بدلًا من .show()?. لا يُعرَض HTML المقدَّم من الدفتر كصفحة.

طبقات الإشارات التداولية والخرائط الحرارية

استخدم .signals(&signals)? على aqs_chart لإضافة علامات الإشارات التداولية المولّدة أو أوامر الدخول المنفّذة. تحتاج إطارات بيانات الإشارات التداولية المخصصة إلى timestamp بالميلي ثانية بتوقيت UTC، وside بقيمة Buy أو Sell، واختياريًا label.

aqs_chart(&btc).candles().signals(&signals)?.show()?;
aqs_heatmap(&monthly, "month", "year", "return_pct")?;

تقبل الخرائط الحرارية ما يصل إلى 50 تسمية لكل محور و2,500 خلية. تبقى القيم المفقودة فارغة، لا صفرًا. تؤدي الإحداثيات المكررة إلى خطأ: اجمع البيانات صراحةً قبل الرسم. تتمركز الألوان حول الصفر. تُحفَظ علامات الإشارات التداولية والخرائط الحرارية في لقطات أوراق AQI الثابتة وكذلك في الدفتر المحلي.

لقراءة الاختبارات التاريخية المحفوظة ومقارنات حقوق الملكية والتراجع وaqs_returns_heatmap وإعادة تشغيل ألفا وتجارب الرسوم البيانية المعزولة، راجع إعادة استخدام الاستراتيجيات والاختبارات التاريخية.

حدود المخرجات والأخطاء

يفتح قسم AQI paper في الدفتر محرر الورقة الكامل بكتلة مكوّن دفتر تتضمن الشيفرة وعينات المخرجات المحفوظة المؤهلة. استخدم Add notebook في محرر الورقة لتحديد خلايا بعينها أو استبعاد المخرجات. الإدراج محلي؛ راجع ثم احفظ أو انشر صراحةً. تستخدم مخططات السلاسل الزمنية في الورقة عارض TradingView Lightweight Charts نفسه المستخدم في دفتر البحث، بما فيه الطبقات واللوحات المتزامنة وعلامات الإشارات التداولية وقيم مؤشر التقاطع بتوقيت UTC. يستطيع القراء تكبير العينات المحفوظة وتحريكها؛ ولا تحمّل هذه المخططات بيانات مباشرة. تستخدم الخرائط الحرارية ومخططات التشتت والتوزيعات عارض SVG الخاص بالبحث، وتظل البدائل الثابتة متاحة دون JavaScript. تُستبعَد النتائج المتقادمة أو الفاشلة أو غير المتحقق منها. لا تضمّن اللقطة مجموعات البيانات الخام ولا تُنفَّذ على جهاز القارئ. راجع مشاركة البحث لسير عمل المراجعة والنشر.

تضع بيئة التشغيل حدًا قدره 256 KiB للنص ولكل معاينة غنية على حدة. ينبغي تقليل المخرجات الكبيرة أو كتابتها إلى ملف داخل مجلد المشروع. يسمح العارض بما يصل إلى 20 معاينة غنية لكل تقييم.

تظهر تشخيصات المترجم والتشغيل أسفل الخلية المعنية؛ وتوقف stderr أيضًا Run all للمراجعة. تبقى المخرجات في الدفتر المحفوظ وتُوسَم بأنها متقادمة بعد التعديلات أو إعادة الضبط. وهذه المعاينات منفصلة عن مساحة عمل مخططات AQS المباشرة.