Gráficos y funciones auxiliares de investigación

Cuando Load data into Rust se completa correctamente, las celdas de investigación pueden usar estas funciones auxiliares. Son funciones para cuadernos proporcionadas por AQS, no API adicionales para estrategias de AQE. Después de actualizar AQS, vuelve a cargar los datos para instalar las nuevas funciones auxiliares en una sesión existente.

Datos disponibles para las celdas

data es una colección AqsData cuyas claves son los símbolos cargados. Envuelve un HashMap<String, DataFrame> y sigue admitiendo indexación (data["BTCUSD"]), get, insert y otros métodos de mapa mediante desreferenciación. No es un alias de tipo de HashMap. bars sigue siendo una copia de trabajo del primer símbolo cargado. Las marcas de tiempo históricas son milisegundos Unix UTC en una columna Int64 llamada 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")?;

Usa los símbolos exactos del proveedor (por ejemplo, BTC-USD de Yahoo). Un símbolo ausente produce un error que enumera los símbolos disponibles. Cada llamada a bars devuelve una copia de trabajo independiente de Polars: calcular indicadores en btc no modifica data ni eth. Las funciones libres equivalentes son aqs_symbols(&data) y aqs_bars(&data, "BTCUSD")?.

El selector Loaded symbols del panel de sesión puede añadir una celda preparada de tabla y velas para un símbolo. Inserta código sin ejecutarlo.

Vistas previas de tablas

aqs_table(&bars, 10)?;

aqs_table(frame: &DataFrame, limit: usize) devuelve Result<(), Box<dyn std::error::Error>>. Emite los nombres de columnas y los valores con formato sin modificar el DataFrame.

La función auxiliar incluye como máximo 100 filas. El visor muestra como máximo 50 columnas. Los límites de la vista previa no truncan el DataFrame disponible para el análisis.

Líneas simples y superposiciones

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

aqs_plot(frame: &DataFrame, column: &str) devuelve Result<(), Box<dyn std::error::Error>>. La columna seleccionada debe poder convertirse a Float64; timestamp debe contener milisegundos Int64. Las columnas ausentes o los tipos incompatibles producen un error de celda.

Cada llamada crea un gráfico; aqs_plot_many coloca varias líneas en el mismo eje de precios. Las columnas indicadas ya deben existir. Pueden emitirse tablas y gráficos desde la misma celda, en el orden de las llamadas:

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

Velas, medias móviles y paneles sincronizados

Configuración de un gráfico de investigación y su salida: velas BTCUSD con dos medias móviles superpuestas, un histograma de volumen y una línea ATR en paneles sincronizados. Ver la captura a tamaño completoVer la captura a tamaño completo.

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()?;

Los indicadores de AQE operan sobre DataFrames normales de Polars. Carga suficiente historial para el periodo más largo y su calentamiento. El constructor de gráficos solo representa columnas; no calcula un indicador por el mero hecho de pasar su nombre a line. Una columna sin valores finitos produce un error de celda.

Los constructores del gráfico principal y de paneles admiten .line(column), .area(column), .histogram(column), .candles() y .ohlc(). .label(text) cambia el nombre de la última serie de ese constructor. Las velas y las barras OHLC requieren las columnas open, high, low y close. Todas las series temporales requieren timestamp.

Los gráficos temporales de los cuadernos permiten ampliar y desplazar la vista, compartir el eje temporal, consultar valores al pasar el cursor, asignar colores automáticos a las series y ajustar el tamaño de los paneles mediante sus separadores. Cada panel tiene su propia escala vertical; las superposiciones de un mismo panel comparten esa escala. Coloca las series con unidades diferentes, como precio y volumen, en paneles distintos. .height(pixels) admite valores de 240 a 1200; el valor predeterminado crece con el número de paneles. Se admiten hasta seis paneles y doce series en total.

Muestreo de vista previa e integridad de los datos

El gráfico ordena su vista por marca de tiempo y convierte milisegundos en segundos. Cuando varias filas corresponden al mismo segundo, prevalece la última fila de origen de forma coherente entre superposiciones. Se omiten las marcas de tiempo nulas o fuera de rango. Se omiten los valores nulos o no finitos, incluido el calentamiento de indicadores. Los huecos no se rellenan con nuevas observaciones; la representación de líneas puede conectar visualmente los puntos restantes.

Los gráficos temporales grandes usan grupos comunes de filas para todos los paneles. Una vela usa la primera apertura válida, el máximo más alto, el mínimo más bajo y el último cierre válido de su grupo. Los histogramas suman los valores de su grupo; las líneas y las áreas usan el último valor finito. Cada grupo se sitúa en su última marca de tiempo. Esto es solo agregación para visualización: el DataFrame de origen, los cálculos de investigación y los backtests no cambian. Los límites OHLC no válidos o un desbordamiento producen un error.

.max_points(n) acepta de 2 a 2000 puntos (1000 por defecto) como objetivo por serie. La función auxiliar reduce ese objetivo según sea necesario para mantener la salida total por debajo de 4000 puntos y 240 KiB. El pie del gráfico indica el número de filas de origen y el tamaño del grupo. Usa un intervalo de fechas más reducido al inspeccionar velas individuales.

Diagramas de dispersión y distribuciones

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

aqs_scatter(frame, x_column, y_column) empareja valores de la misma fila de origen. Elimina los pares que contienen valores ausentes o no finitos y toma una muestra de como máximo 2000 pares para mostrarlos.

aqs_histogram(frame, column, bins) cuenta todas las observaciones finitas y las agrupa en un número de intervalos numéricos de 2 a 100. Una columna constante se convierte en un único intervalo. Las observaciones ausentes o no finitas se cuentan como omitidas en el pie del gráfico. Esto es una distribución, a diferencia de .histogram("volume") del constructor de gráficos, que representa valores en función del tiempo.

Estos dos tipos de gráfico usan ejes numéricos y ayudas emergentes SVG, no los controles de ampliación y desplazamiento de los gráficos temporales. No requieren una columna de marca de tiempo.

Comparar símbolos sobre una base común

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

Compara los precios de cierre de BTCUSD, ETHUSD y SOLUSD desde un punto inicial compartido con base 100. Las líneas muestran variaciones relativas de precios, no rentabilidades de estrategia. Ver la captura de comparación a tamaño completoVer la captura de comparación a tamaño completo.

Elige entre 2 y 8 símbolos cargados distintos. Cada línea empieza con base 100 en la primera marca de tiempo exacta compartida por todos los símbolos con valores finitos y positivos. Las marcas de tiempo ausentes posteriores no se rellenan con el último valor; cada serie conserva sus propias observaciones. Si no hay un punto de anclaje común, la función auxiliar devuelve un error. La visualización toma una muestra de unas 400 observaciones de cada serie, conservando la primera y la última.

Esta es una comparación normalizada de precios, no una curva de patrimonio de estrategia, una rentabilidad de cartera ni un cálculo de correlación. No ajusta los instrumentos por costes, operaciones corporativas o monedas. Usa datos de entrada debidamente ajustados para tu estudio.

Salida estructurada personalizada

aqs_emit(value: serde_json::Value) emite una vista previa estructurada. Usa preferentemente las funciones auxiliares anteriores para los gráficos. El visor también conserva la compatibilidad heredada con table y 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}
    ]
}));

Las marcas de tiempo de líneas personalizadas son segundos Unix, a diferencia de los milisegundos del DataFrame. Los nombres de las columnas de las tablas y los valores de las celdas deben ser cadenas de texto. Las nuevas funciones auxiliares emiten especificaciones de versión 1 chart, scatter, distribution y heatmap. Para inspeccionar el contenido de un constructor sin mostrarlo, usa .build()? en lugar de .show()?. El HTML proporcionado por el cuaderno no se renderiza.

Superposiciones de señales y mapas de calor

Usa .signals(&signals)? en aqs_chart para superponer señales generadas o entradas ejecutadas. Las tablas de señales personalizadas necesitan timestamp en milisegundos UTC, side (Buy o Sell) y, opcionalmente, label.

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

Los mapas de calor aceptan hasta 50 etiquetas por eje y 2 500 celdas. Los valores ausentes permanecen en blanco, no en cero. Las coordenadas duplicadas producen un error: agrupa explícitamente los datos antes de representarlos. La escala de colores está centrada en cero. Los marcadores de señales y los mapas de calor se conservan tanto en las instantáneas estáticas de artículos de AQI como en el cuaderno local.

Para lectores de backtests guardados, comparaciones de patrimonio y drawdown, aqs_returns_heatmap, reproducciones de modelos alfa y experimentos aislados con grafos, consulta Reutilización de estrategias y backtests.

Límites de salida y errores

La sección AQI paper del cuaderno abre el editor completo de artículos con un bloque de componente de cuaderno que contiene código y muestras de salidas guardadas que cumplen los requisitos. Usa Add notebook en el editor de artículos para seleccionar celdas concretas o excluir salidas. La inserción es local; revisa el contenido y guárdalo o publícalo explícitamente. Los gráficos temporales de los artículos usan el mismo renderizador TradingView Lightweight Charts que el cuaderno de investigación, incluidas superposiciones, paneles sincronizados, marcadores de señales y valores UTC del cursor en cruz. Los lectores pueden ampliar y desplazar las muestras guardadas; estos gráficos no cargan datos en vivo. Los mapas de calor, diagramas de dispersión y distribuciones usan el renderizador SVG de investigación, y las alternativas estáticas siguen disponibles sin JavaScript. Se excluyen los resultados desactualizados, fallidos o no verificados. La instantánea no incorpora conjuntos de datos sin procesar ni se ejecuta en la máquina del lector. Consulta Compartir investigación para el flujo de revisión y publicación.

El entorno de ejecución limita el texto y las vistas previas enriquecidas individuales a 256 KiB. Las salidas grandes deben reducirse o escribirse en un archivo local del proyecto. El visor permite hasta 20 vistas previas enriquecidas por evaluación.

Los diagnósticos del compilador y de ejecución aparecen debajo de la celda correspondiente; stderr también detiene Run all para su revisión. La salida permanece en el cuaderno guardado y se marca como desactualizada después de modificaciones o de un restablecimiento. Estas vistas previas son independientes del espacio de gráficos en vivo de AQS.