리서치 차트 및 헬퍼

Load data into Rust가 성공하면 리서치 셀에서 이 헬퍼를 사용할 수 있습니다. 이는 AQS가 제공하는 노트북 헬퍼이며 추가 AQE 전략 API가 아닙니다. AQS를 업그레이드한 후에는 데이터를 다시 불러와 기존 세션에 새 헬퍼를 설치하세요.

셀에서 사용할 수 있는 데이터

data는 불러온 심볼을 키로 사용하는 AqsData 컬렉션입니다. HashMap<String, DataFrame>을 감싸며 역참조를 통해 인덱싱(data["BTCUSD"]), get, insert 및 기타 맵 메서드를 계속 지원합니다. HashMap의 타입 별칭은 아닙니다. bars는 첫 번째로 불러온 심볼의 작업용 복사본으로 유지됩니다. 과거 타임스탬프는 timestamp라는 Int64 열의 UTC Unix 밀리초입니다.

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

공급자의 정확한 심볼을 사용하세요(예: Yahoo의 BTC-USD). 심볼이 없으면 사용 가능한 심볼 목록을 포함한 오류가 발생합니다. 각 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>>를 반환합니다. DataFrame을 수정하지 않고 열 이름과 형식화된 값을 출력합니다.

헬퍼에는 최대 100행이 포함됩니다. 뷰어는 최대 50열을 표시합니다. 미리보기 한도는 분석에 사용할 수 있는 DataFrame을 잘라내지 않습니다.

기본 선 차트와 오버레이

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 DataFrame에서 동작합니다. 가장 긴 기간과 워밍업에 충분한 이력을 불러오세요. 차트 빌더는 열을 그릴 뿐이며, line에 지표 이름을 전달했다고 지표를 계산하지는 않습니다. 유한한 값이 없는 열은 셀 오류를 발생시킵니다.

주 차트와 창 빌더는 .line(column), .area(column), .histogram(column), .candles(), .ohlc()를 지원합니다. .label(text)는 해당 빌더의 마지막 시리즈 이름을 바꿉니다. 캔들과 OHLC 봉에는 open, high, low, close 열이 필요합니다. 모든 시계열에는 timestamp가 필요합니다.

노트북 시계열 차트는 확대 및 이동, 공통 시간축, 마우스를 올렸을 때 값 표시, 시리즈별 자동 색상 지정, 크기 조절이 가능한 창 구분선을 지원합니다. 각 창에는 자체 세로 축척이 있으며, 같은 창의 오버레이는 해당 축척을 공유합니다. 가격과 거래량처럼 단위가 다르면 별도 창에 배치하세요. .height(pixels)는 240–1200으로 제한되며 기본 높이는 창 수에 따라 커집니다. 최대 여섯 개 창과 총 열두 개 시리즈를 지원합니다.

미리보기 샘플링과 데이터 무결성

차트는 표시용 데이터를 타임스탬프순으로 정렬하고 밀리초를 초로 변환합니다. 여러 행이 같은 초에 매핑되면 모든 오버레이에서 일관되게 마지막 소스 행을 사용합니다. null이거나 범위 밖인 타임스탬프는 제외됩니다. 지표 워밍업을 포함한 null 또는 유한하지 않은 값도 제외됩니다. 빈 구간을 새로운 관측값으로 채우지는 않지만 선 렌더링이 남은 점들을 시각적으로 연결할 수 있습니다.

데이터가 많은 시계열 차트는 모든 창에서 행을 동일한 버킷으로 묶어 표시합니다. 캔들은 버킷의 첫 유효 시가, 최고 고가, 최저 저가, 마지막 유효 종가를 사용합니다. 히스토그램은 버킷 값을 합산하며 선과 영역은 마지막 유한 값을 사용합니다. 각 버킷은 마지막 타임스탬프에 배치됩니다. 이는 화면 표시만을 위한 집계이며 원본 DataFrame, 리서치 계산, 백테스트는 바뀌지 않습니다. 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")?;

공통 기준값 100에서 시작하는 BTCUSD, ETHUSD, SOLUSD 종가를 비교하세요. 선은 전략 수익률이 아니라 상대적인 가격 변화를 보여줍니다. 원본 크기 비교 스크린샷 보기원본 크기 비교 스크린샷 보기

불러온 서로 다른 심볼 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}
    ]
}));

사용자 지정 선 타임스탬프는 DataFrame의 밀리초와 달리 Unix 초입니다. 테이블 열과 셀 값은 문자열이어야 합니다. 새 헬퍼는 버전 1 chart, scatter, distribution, heatmap 명세를 출력합니다. 빌더 페이로드를 표시하지 않고 검사하려면 .show()? 대신 .build()?를 사용하세요. 노트북에서 제공한 HTML은 렌더링되지 않습니다.

신호 오버레이와 히트맵

aqs_chart에서 .signals(&signals)?를 사용해 생성 신호나 진입 체결을 겹쳐 표시하세요. 사용자 지정 신호 프레임에는 UTC 밀리초 timestamp, side(Buy 또는 Sell), 선택적으로 label이 필요합니다.

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

히트맵은 축당 최대 50개 레이블과 2,500개 셀을 허용합니다. 누락된 값은 0이 아니라 빈칸으로 유지됩니다. 좌표가 중복되면 오류가 발생하므로 그리기 전에 명시적으로 집계하세요. 색상은 0을 중심으로 배치됩니다. 신호 마커와 히트맵은 로컬 노트북뿐 아니라 정적 AQI 논문 스냅샷에도 보존됩니다.

저장된 백테스트 조회, 계좌 평가액 및 낙폭 비교, aqs_returns_heatmap, 알파 재생, 격리된 그래프 실험은 전략 재사용 및 백테스트를 참조하세요.

출력 한도와 오류

노트북의 AQI paper 섹션에서는 코드와 공유 조건에 맞는 저장된 출력 샘플을 노트북 컴포넌트 블록에 넣어 전체 논문 편집기를 열 수 있습니다. 특정 셀만 선택하거나 출력을 제외하려면 논문 편집기의 Add notebook을 사용하세요. 삽입은 로컬에서만 이루어지므로 검토 후 명시적으로 저장하거나 게시해야 합니다. 논문의 시계열 차트는 리서치 노트북과 동일한 TradingView Lightweight Charts 렌더러를 사용하며 오버레이, 동기화된 창, 신호 마커, UTC 기준 십자선 값 표시를 지원합니다. 독자는 저장된 샘플을 확대하거나 이동할 수 있지만, 차트가 실시간 데이터를 불러오지는 않습니다. 히트맵, 산점도, 분포는 리서치 SVG 렌더러를 사용하며 JavaScript 없이도 정적 대체 화면을 볼 수 있습니다. Stale 상태이거나 실패했거나 검증되지 않은 결과는 제외됩니다. 스냅샷에는 원시 데이터셋이 포함되지 않으며 독자의 컴퓨터에서 코드가 실행되지도 않습니다. 검토 및 게시 워크플로는 리서치 공유를 참조하세요.

런타임은 텍스트와 개별 리치 미리보기를 256 KiB로 제한합니다. 큰 출력은 줄이거나 프로젝트 로컬 파일에 기록해야 합니다. 뷰어는 평가당 최대 20개의 리치 미리보기를 허용합니다.

컴파일러 및 런타임 진단은 해당 셀 아래에 표시됩니다. stderr 메시지가 발생해도 검토할 수 있도록 Run all이 중단됩니다. 출력은 저장된 노트북에 남으며, 편집하거나 초기화하면 Stale로 표시됩니다. 이 미리보기는 실시간 AQS 차트 워크스페이스와 별개입니다.