Quy ước dữ liệu và lỗi

Trang này gom những điều đúng với mọi nhóm hàm của vnstock_quant: dữ liệu đầu vào trông như thế nào, lỗi được báo ra sao và các quy ước tính toán mà kết quả tuân theo. Từng trang nhóm hàm chỉ nói phần riêng của nhóm đó.

Dữ liệu đầu vào

Thư viện nhận dữ liệu dạng pandas và trả kết quả căn theo chỉ mục bạn đưa vào. Lớp Python chỉ đổi cột sang mảng số rồi dựng lại bảng có nhãn; mọi phép tính và kiểm tra đầu vào nằm trong lõi Rust, nên thiếu cột hay lệch độ dài được báo bằng InputDataError kèm tên cột thiếu.

Hai hồ sơ cột của vnstock 6

vnstock 6 trả bảng theo hồ sơ v5 (tên cột và đơn vị như thế hệ 5, mặc định) hoặc v6 (tên cột mới, giá theo nghìn đồng ở nhiều bảng). Các hàm tải của vnstock_quant luôn đọc hồ sơ v5. Bảng bạn tự tải và đưa vào thì ở hồ sơ nào cũng được: thư viện đọc attrs["profile"] của bảng để đổi đơn vị khi cần.

Kết quả là DataFrame hoặc Series cùng chỉ mục với đầu vào. Siêu dữ liệu đi kèm nằm trong attrs (ví dụ bảng hệ số của prices.adjust ở attrs["factors"]). Thư viện không tự đổi đơn vị giá trừ khi hàm có tham số unit hoặc price_unit; hãy dùng một đơn vị nhất quán trong cả phiên làm việc.

Hệ thống phân cấp ngoại lệ

Các lỗi của thư viện kế thừa từ VnstockQuantError. Mã lỗi giúp bạn phân biệt sai tham số, dữ liệu đầu vào, quyền sử dụng và những trường hợp khác:

VnstockQuantError (Lớp cơ sở)
├── InvalidParameterError      # Tham số sai tên, sai kiểu hoặc ngoài khoảng (mã: QUANT_INVALID_PARAMETER)
├── UnknownIndicatorError      # Không có chỉ báo, tính năng hay hàm mang tên đó (mã: QUANT_UNKNOWN_INDICATOR,
│                              #   QUANT_UNKNOWN_FEATURE, QUANT_UNKNOWN_FUNCTION)
├── UnknownRatioError          # Mã chỉ số tài chính không tồn tại (mã: QUANT_UNKNOWN_RATIO)
├── InputDataError             # Dữ liệu đầu vào thiếu cột hoặc các cột lệch độ dài (mã: QUANT_INPUT_DATA)
│   └── CausalityViolationError  # Tín hiệu hoặc chỉ báo trong backtest đọc dữ liệu tương lai (mã: QUANT_CAUSALITY_VIOLATION)
├── DependencyError            # Thiếu vnstock, hoặc vnstock đang cài không thuộc thế hệ 6 (mã: QUANT_DEPENDENCY_MISSING)
├── EntitlementError           # Cấp quyền hiện tại không mở tính năng này
│   ├── TierRequiredError      # Cần gói quyền sử dụng cao hơn (mã: QUANT_TIER_REQUIRED, QUANT_SCOPE_LIMIT)
│   └── QuotaExceededError     # Hết lượt dùng thử trong ngày, hoặc một lần chạy thử quá lớn cho cấp (mã: QUANT_TRIAL_EXHAUSTED, QUANT_QUOTA_LIMIT)
├── AuthError                  # Lỗi API key, thiết bị hoặc kết nối máy chủ cấp quyền
├── UnsupportedError           # Bản phát hành đã bị tắt, cần nâng cấp (mã: VNSTOCK_RELEASE_DISABLED)
│   └── ReleaseExpiredError    # Bản phát hành đã hết hạn hiệu lực (mã: VNSTOCK_RELEASE_EXPIRED)
└── InternalError              # Lỗi ngoài dự kiến bên trong thư viện

Lỗi do vnstock 6 ném khi tải dữ liệu (chưa chọn nguồn, nguồn không đọc được loại dữ liệu, thiếu khoá, nguồn từ chối) được giữ nguyên, không bọc lại; mã của chúng bắt đầu bằng VNSTOCK_:

Trong fa.Dataset.load(), sáu mã đầu khi tải giá hoặc thuyết minh không làm dừng cả lần tải: thư viện báo một cảnh báo, chỉ số liên quan trả MISSING_MARKET hoặc MISSING_INPUT. Lỗi mạng và lỗi tần suất vẫn được ném ra.

Mọi lỗi đều có các thuộc tính code (mã lỗi), kind (nhóm lỗi), message (nội dung tiếng Việt), retryable (có nên thử lại không) và action (việc nên làm tiếp, có thể là None). str(e) có dạng [code] message (action).

Ví dụ bắt lỗi theo nghiệp vụ

import vnstock_quant as vq

try:
    # Ví dụ gọi hàm tính toán cần quyền hạn
    result = vq.portfolio.twr(values, flows)
except vq.TierRequiredError as e:
    print(f"Lỗi quyền hạn: {e.message}")
    print(f"Việc nên làm: {e.action}")
except vq.QuotaExceededError as e:
    print(f"Đã hết lượt dùng thử hôm nay [{e.code}]. Lượt sẽ được làm mới lúc 00:00 giờ Việt Nam.")
except vq.AuthError as e:
    print(f"Không kiểm tra được quyền sử dụng: {e}")
except vq.InvalidParameterError as e:
    print(f"Tham số không hợp lệ: {e}")
except vq.VnstockQuantError as e:
    print(f"Lỗi chung của vnstock_quant: {e}")

Tắt cảnh báo hệ thống

Các lưu ý không làm dừng chương trình được phát qua lớp cảnh báo VnstockQuantWarning. Ở bản 1.0, một số tính năng chưa đủ chắc chắn được tắt hoặc chạy kèm cảnh báo nêu rõ điều kiện, thay vì trả một con số trông như thật:

Bạn có thể tắt cảnh báo nếu muốn, nhưng nên đọc chúng ít nhất một lần:

import warnings
from vnstock_quant import VnstockQuantWarning

# Bỏ qua các cảnh báo không trọng yếu của vnstock_quant
warnings.filterwarnings("ignore", category=VnstockQuantWarning)

Các quy ước phương pháp luận chung

Trước khi so sánh kết quả giữa các hàm, hãy chú ý các quy ước sau:

Đọc tiếp

• Quyền dùng và hạn mức — Khi nào gặp TierRequiredError và QuotaExceededError.
• Giá điều chỉnh — Vì sao chuỗi lợi suất cần giá đã điều chỉnh.
• Đối chiếu kết quả và tốc độ — Các mốc chuẩn mà kết quả được so với.