ファンダメンタルデータ

開発中：ファンダメンタルデータはまだ完全には機能していません。IDE やバックテストでこの機能を使うと、一貫性のないファンダメンタルデータ（欠落したフィールド、一致しないレポート日、不安定なバー整列スナップショット）が返ることがあります。将来のリリースでファンダメンタルデータが安定版とされるまで、結果は実験的なものとして扱ってください。

QuantCraft のストラテジーは、OHLCV の価格バーと並べて企業の財務データ（貸借対照表、キャッシュフロー計算書、損益計算書、決算履歴／予想）を使えます。データは QuantCraft のファンダメンタルデータサービスからシンボルごとに一度だけ読み込まれ、日付をキーとするテーブルとして整理され、バックテスト中はバーに整列したスナップショットとしてストラテジーに提供されます。コールバックのタイミングはストラテジーのライフサイクルに従います。シンボルと日付は Test（コードの実行）で設定します。

3 つの財務諸表に加えて、レシオ（91 種類）、1 株あたりの値、バリュエーションのマルチプルと利回り、品質スコア（Piotroski F、Altman Z-prime、Beneish M）も得られます — すべてポイントインタイムで、すべて任意です。これらはシンボルごとに順次展開されるため、すべてのアクセスをガードしてください。raw["metricsInputs"] is None は、バンドルがそれらより前のものであることを意味します。

このページで扱う内容：

• どのような財務諸表データが利用できるか
• 日付をキーとするテーブルがどう整理されているか
• バックテスト中にバー整列ペイロードがコールバックにどう届くか

**関連：**グローバルな Fama-French ファクターリターンのデータセット（ティッカーごとではない）は別の機能です — Fama-French ファクター（fama_french.qc、コールバック引数なし）を参照してください。ファクターの rows は、リストのインデックスではなく YYYYMM 文字列をキーとします。

---

得られるもの

各ファンダメンタルデータのバンドルは、1 つのティッカーに対する単一の JSON オブジェクトで、次を含みます。

• 貸借対照表 — quarterly と yearly のレポート。
• キャッシュフロー — quarterly と yearly のレポート。
• 損益計算書 — quarterly と yearly のレポート。
• 決算（Earnings）：
  • History — レポート日ごとの発表 EPS と予想、サプライズ。
  • Trend — 先行予想、EPS トレンド、アナリストの修正。
  • Annual — 会計年度ごとの epsActual。
• レシオ — quarterly と yearly の財務レシオ（マージン、リターン、流動性、レバレッジ）。
• Financials extended — 基本の損益計算書、貸借対照表、キャッシュフロー計算書にはない quarterly と yearly の拡張指標。
• 1 株あたり — quarterly と yearly の 1 株あたりの値（提出時のまま。その期間の株式分割ベースでの株数）。
• バリュエーション — quarterly と yearly の時価総額、企業価値、マルチプル、利回りと、日付のない latest オブジェクト。
• スコア — quarterly と yearly の Piotroski F、Altman Z-prime、Beneish M と、notApplicableReason。
• TTM — 直近 12 か月の単一オブジェクト（期間ごとには分割されない）。
• 指標の出所 — フラットな metricsInputs / metricsHealth オブジェクト。metricsInputs は、指標の拡張前のバンドルでは None です。
• 提出履歴 — quarterly と yearly の提出メタデータ（書式の種類、提出日、期末をキーとする）。バンドルに含まれていれば、バー整列の current(...) スナップショットにも含まれます。生のテーブルは f.tables["filingHistory.quarterly"] で引き続き利用できます。
• 企業情報 — フラットなエンティティのメタデータ（名称、CIK、SIC、住所、取引所、ティッカー）。日付をキーとせず、バー整列スナップショットにも含まれません。f.raw["companyInfo"] でアクセスします。

各レポートは、たとえば totalAssets、cash、freeCashFlow、totalRevenue、netIncome、epsActual、epsEstimate、surprisePercent のような camelCase の指標からなる行です。数値は、基になる JSON では文字列で届くことがあり、欠けているフィールドは None で返ります。

特定のティッカーがすべてのセクションを公開しているとは限りません。ティッカーで利用できるフィールドは、ファンダメンタルデータ対応状況エクスプローラーで確認してください。

---

日付をキーとするテーブル

上記の各セクションについて、ファンダメンタルデータは日付をキーとするテーブルとして整理されます。行はレポート日（YYYY-MM-DD）をキーとし、指標は価格履歴のようにインデックスできる並列リストとして公開されます。

標準のテーブルパス：

テーブルではないもの。valuation.latest、scores.notApplicableReason、ttm、metricsInputs、metricsHealth、companyInfo は日付をキーとしないため、tables、lists、バー時点のすべてのスナップショットには含まれません — これは意図的です。

これらはすべて期間ごとではなくアップロード時点の値なので、tables に含めないことで、バー時点のすべてのスナップショットからも除外されます。そのため、バックテストが 2019 年のバーで今日の価格を誤って読むことはありません。代わりに f.raw を通じてアクセスしてください。空のブロック（{"quarterly": {}, "yearly": {}}。金融セクターの提出者の scores がこの形です）は、テーブルをまったく登録しません。

インデックスの規約：新しい順

これらのテーブルのどれでも、インデックス 0 が最新の対象期間、インデックス 1 がその前の期間、というようになります。これは QuantCraft の他の部分での価格系列の扱いと一致します。

バンドルを直接読み込みたい場合（たとえばバックテストの外で）、基本の形は次のとおりです。

読み込んだバンドルから読み取れるもの：

DateKeyedTable は periods（YYYY-MM-DD のキー、新しい順）と columns（フィールド → 値）を公開し、table["fieldName"] によるインデックスをサポートします。

実行時のフィールド探索は簡単です。sorted(f.lists.keys()) はすべてのフラットな系列を、sorted(t.columns.keys()) は 1 つのテーブルの列を表示します — サーバーがフィールドを追加・削除したときに便利です。

---

バックテストにおけるバー整列ペイロード

バックテストでは、ファンダメンタルデータを生のテーブルとして読むのではなく、エンジンが現在のバーに適したレポートを選択し、スナップショットとしてコールバックに渡します。これをバー整列ペイロードと呼びます。

バックテストのファンダメンタルデータの設定

Run backtest の Symbol & data タブで：

1. Uses fundamentals (select if your strategy requires fundamental data) をオンにします（サインインが必要 — B2 のファンダメンタルデータファイルを読み込むために、QuantCraft がセッショントークンを送信します）。バルクフォワードとチャートフォワードでは Use fundamentals (optional) と表示されます。ビルドでファンダメンタルデータ機能が利用可能な場合にチェックボックスが表示されますが、Premium であるか無料データアクセスが有効でない限り無効（Premium のヒント付き）です。
2. 複数選択から1 つ以上のファンダメンタルデータバンドルを選びます（fundamentals/AAPL.json.gz のようなパス）。

**Screener のシンボルソース（バックテスト）または Screener のターゲット（AutoTrading / QuantCloud のバルク実行）**では、何も選ぶ必要はありません。ファンダメンタルデータをオンにすれば、スクリーンが選んだすべてのシンボルがそれぞれ独自のバンドルを持つため、fundamentals.current(bar["t"], symbol=symbol) がそれぞれで機能します。バンドルは Screener 自身のダウンロードから取得され（二重に取得されることはありません）、Screener がまだダウンロードしていないシンボルは一度だけ取得されて保持されます。ライブ実行では、バンドルは再スクリーニングのたびに追従します。手動での選択も追加分として引き続き受け付けられます（たとえばベンチマークのティッカー）。データを読み込めなかったシンボルは、実行を失敗させる代わりに None を返します — Output パネルに読み込めた件数が表示されます。

**OHLCV のシンボルとファンダメンタルデータのシンボルは独立しています。**ブローカーフィードで RNMBY をバックテストしながら、RHM.XETRA のファンダメンタルデータを読み込めます — コードでは、正しいティッカーを fundamentals.current(..., symbol="RHM.XETRA")（またはそれに相当するもの）に渡してください。

複数のバンドルが選択されている場合、特定のバンドルが必要なときは、fundamentals.current / get_data_with_offset に明示的な symbol= を使ってください。バー整列スナップショットに使われるプライマリバンドルは、エンジンが別のルールを適用しない限り、シンボルリストの最初の OHLCV シンボルがデフォルトです。

コールバックの外で低レベルのテーブルアクセスをするには、None でない場合に quantcraft.process.runtime の qc_fundamentals を使います（例：qc_fundamentals.raw["companyInfo"]）。これはプライマリバンドルだけを保持します。他のティッカーには、コールバックの fundamentals ハンドルを symbol= とともに使ってください。

ファンダメンタルデータが設定されていない場合、エンジンは単に fundamentals=None をコールバックに渡すので、ガードで対処します。

ポイントインタイム（バックテスト）：バックテストエンジンと Debug Test はどちらも BacktestFundamentals(..., backtest_mode=True) を構築するため、current / get_data_with_offset は提出日によるゲーティング（use_filing_date=True）を使います — 期間の filing_date がバーの時刻より後の場合、その期間は除外されます。期間に使える filing_date がない場合は、期間が終了した日にレポートを見えるようにするのではなく、想定される提出期限が代わりに使われます — 期末から四半期テーブルで 45 日、年次で 90 日（default_filing_lag_days）です。フォワード実行は期末による対象判定（backtest_mode=False）を使います。IDE のバックテストでは、コールバックの fundamentals ハンドルを推奨します。use_filing_date=True なしで生の qc_fundamentals.get_data_with_offset(...) を呼ぶと、提出日に対して先読みになる可能性があります。

フォワード実行：ライブ実行は、ファンダメンタルデータを約1 時間ごとに、また Screener のデータが更新されてから約 5 分以内に再読み込みします。再読み込みに失敗した場合は、以前のデータが維持されます。フォワード実行の「今」は本当に今日なので、アップロード時点のブロック（raw["ttm"]、raw["valuation"]["latest"] など）はそこでは先読みではなく最新のデータです。

**旧来のコールバック：**古いストラテジーは、BacktestFundamentals の代わりに別の qc_fundamentals 引数や生の dict を使っていることがあります。現在のシグネチャでは、fundamentals を on_bar / on_tick の 3 番目の引数として渡します。モジュールレベルのエイリアス fundamentals_as_of_bar は、同じバー整列ペイロードの形に対応します。

fundamentals コールバックパラメータ

ファンダメンタルデータが読み込まれていると、エンジンは BacktestFundamentals ハンドルを fundamentals 引数として on_bar、on_tick、そして（フォワード実行で使う場合は）on_timer に渡します。

スナップショットの形

バー整列スナップショットは、このバーの時点で有効な期間だけを含むネストした dict です（IDE のバックテストでは提出日でゲート）。null でない各セクションには、periodEnd とレポートの指標が含まれます。

バーの時刻以前に該当する期間がない場合、Trend は null になることがあります。上記の earningsYield: -5.0 の隣の priceToEarningsRatio: null は、データの欠損ではなく赤字企業です — バリュエーションを参照してください。

スナップショットには決して含まれないもの：ttm、valuation.latest、scores.notApplicableReason、metricsInputs、metricsHealth、companyInfo。これらは期間ごとではなくアップロード時点の値で、バーに添付するとバックテストに将来の情報が漏れてしまいます。qc_fundamentals.raw[...] から読み取ってください。

同じバーごとの dict は、構造化されたバックテスト結果の各行の fundamentals フィールドにも現れるため、ストラテジー内で見えるものが結果データに表示されるものと一致します。

古い期間の参照（get_data_with_offset）

バーの時点での最新レポートではなく、前のレポート — 前の四半期、前の会計年度、前の決算行 — が欲しいことがあります。

動作：

• 各サブテーブルは独立してインデックスされます。offset=1 では、balanceSheet.quarterly セクションは 1 四半期戻り、balanceSheet.yearly は 1 会計年度戻ります。
• サブテーブルに現在のバーより前の履歴が十分にない場合、返される dict ではそのセクションは null になります（1 行のメモが出力されることがあります）。
• 形は current(...) と同じで、トップレベルに "offset": <int> が加わります。
• 生の QcFundamentals API では、推奨されるシグネチャは f.get_data_with_offset(bar_time, offset, *, print_on_shortfall=True, use_filing_date=False) です。モジュールレベルの関数 get_data_with_offset(qc, bar_time, offset, *, print_on_shortfall=True) には use_filing_date パラメータがなく、常に期末による対象判定を使います。ポイントインタイムのデータには、メソッドを use_filing_date=True で呼ぶか（またはコールバックのハンドルを使うか）してください。デフォルトの use_filing_date=False は期末による対象判定のみを意味します（提出日に対して先読みになる可能性があります）。use_filing_date=True では、filing_date が欠けている期間は、期末から 45 日（四半期）／90 日（年次）という想定期限にフォールバックします。IDE のバックテストでは、提出日によるゲーティングを自動的に使うコールバックの fundamentals ハンドルを推奨します。

複数シンボルのファンダメンタルデータ

（クロスセクショナルまたは比較ストラテジーのために）複数のバンドルを読み込む場合、symbol="TICKER" でどれから読むかを選べます。

• symbol を省略するとプライマリバンドルが使われます。読み込まれているのが 1 つだけならそれ、そうでなければ設定されていれば fundamentals.primary、なければ取引中のシンボル、なければアルファベット順で最初の読み込み済みティッカーです。複数シンボルや Screener の実行では、このフォールバックが黙って間違った企業になることがあるため、そこでは必ず symbol=symbol を渡してください。
• fundamentals.symbols は、現在読み込まれているすべての大文字のティッカーキーを一覧します。
• fundamentals.primary_symbol() はプライマリキーを返します。
• バックテストで取引するシンボルは、読み込むファンダメンタルデータのシンボルと異なっていてもかまいません — たとえば、AAPL と MSFT のファンダメンタルデータを読みながら SPY を取引できます。

使用できるバーの時刻

current(...) と get_data_with_offset(...) はどちらも複数の時刻形式を受け付けるので、bar["t"]、bar.t[0]、または独自の値を渡せます。

• datetime（ナイーブなものは UTC として扱う）、
• date、
• ISO 文字列（末尾の Z を含む）、
• UNIX エポック秒（int / float）。

---

実用的なパターン

よくある形をいくつか示します。

---

ファンダメンタルデータのフィールドリファレンス

フィールドの有無はシンボルによって異なります — すべての発行体がすべての行を報告するわけではありません。特定のバンドルが実際に何を公開しているかは、実行時に sorted(f.lists.keys()) または sorted(t.columns.keys()) で確認してください。数値は文字列で届くことがあるため、計算には float(...) で変換してください。

貸借対照表

テーブル：balanceSheet.quarterly、balanceSheet.yearly

キャッシュフロー

テーブル：cashFlow.quarterly、cashFlow.yearly

損益計算書

テーブル：incomeStatement.quarterly、incomeStatement.yearly

決算 — History

テーブル：earnings.History（レポート日ごとの発表 EPS と予想）

決算 — Trend

テーブル：earnings.Trend（先行予想と修正）

決算 — Annual

テーブル：earnings.Annual（年次の発表 EPS）

レシオ

テーブル：ratios.quarterly、ratios.yearly

指標の拡張以降、91 個の指標があります（date、currency_symbol、filing_date を数えると 94 キー）。最初に元のセットを示し、運転資本以降はすべて新規です。展開の途中にあるシンボルは元のセットしか持たないことがあるため、実際のリストは sorted(f.table("ratios.quarterly").columns.keys()) で確認してください。

元のセット

このグループのマージンとリターンのフィールド（grossMargin、operatingMargin など）は小数の割合です — パーセントにするには 100 を掛けてください。debtToEquity は debtToEquityRatio に名前が変わりました。

運転資本

レバレッジとカバレッジ

すべて単純な小数（小数 4 桁）。

リターン

マージンと資本集約度

配当・還元

すべてパーセント（小数 2 桁）：dividendPayoutRatio、freeCashFlowPayoutRatio、shareholderPayoutToFreeCashFlow、retentionRatio、sustainableGrowthRate。

前年比の成長

すべてパーセント（小数 2 桁）。売上／純利益／EPS の成長はここには重複して含まれません — earnings.Trend にあります。

CAGR — yearly のみ

すべてパーセント（小数 2 桁）で、すべての quarterly 期間では null です — 四半期の期間でこれらを要求するフィルターやルールは、すべてのシンボルを不合格にします。

revenueCagr3y / revenueCagr5y、netIncomeCagr3y / netIncomeCagr5y、epsCagr3y / epsCagr5y、freeCashFlowCagr3y / freeCashFlowCagr5y、dividendCagr3y / dividendCagr5y。

Financials extended

テーブル：financialsExtended.quarterly、financialsExtended.yearly

フィールドはシンボルによって異なるため、ここでは列挙しません。読み込んだバンドルが何を公開しているかは、実行時に確認してください。

一般的なフィールドには、拡張された EBITDA 指標、運転資本の構成要素、基本の損益計算書にはない 1 株あたりのデータがあります。

廃止されたフィールド：ebitda、ebitdaMargin、enterpriseValue、priceToEarnings、priceToBook、priceToSales、evToEbitda、evToRevenue は、直近 12 か月ベースで計算されるバリュエーションとレシオのバージョンに置き換える形で、Financials extended から撤回されつつあります（そのため値が異なります）。

1 株あたり

テーブル：perShare.quarterly、perShare.yearly

提出時のままの記録です。sharesOutstanding はその期間について報告された株式分割ベースなので、分割をまたいで比較することはできません。比較が必要なものにはバリュエーションを使ってください。特に記載がなければ、値は小数 4 桁の文字列です。

バリュエーション

テーブル：valuation.quarterly、valuation.yearly（テーブルではない valuation.latest を加えたもの）

3 つのルール：

1. マルチプルは marketCap / 集計値 であり、price / perShare ではありません。perShare から再計算しないでください — 再表示された比較値のせいで、古い期間では両者が食い違います。
2. **符号付きの利回りの隣にある None のマルチプルは、バグではなく正しい状態です。**以下の分母が正でない場合は null と記されたマルチプルは、分母が正でないときに None になり、利回りと bookToMarketRatio は符号を保ちます。赤字企業は priceToEarningsRatio: None と earningsYield: -5.0 を示します。
3. マルチプルは直近 12 か月ベースで、四半期の期間でも同じです — 四半期の PER は、1 四半期を年換算したものではなく、本物の直近 12 か月 PER です。

メタデータ

規模：marketCap、enterpriseValue — 小数 2 桁の金額文字列。

マルチプル（小数 4 桁の数値）

利回り — 小数 2 桁のパーセント、符号付き：earningsYield、ebitToEnterpriseValueYield、freeCashFlowYield、operatingCashFlowYield、dividendYield、buybackYield、shareholderYield。

valuation.latest — 期間ではありません。上記のすべてのフィールドに加えて、priceAsOf、priceAgeDays、priceSource、fundamentalsAsOf、ttmBasis を持つ単一のオブジェクトです。日付キーの隣にあるため、テーブルのエントリーではなく、バー時点のスナップショットにも決して現れません — バックテストで読むと先読みになります。qc_fundamentals.raw["valuation"]["latest"] でアクセスしてください。価格が得られない場合は None です。

スコア

テーブル：scores.quarterly、scores.yearly

予想される 2 つの欠落（どちらもエラーではありません）：

• 提出者の最も古い期間にはスコアがありません — 比較する前年が必要だからです。
• SIC 6000〜6799（銀行、証券会社、保険会社、REIT）では、両方のバケットが空で、scores.notApplicableReason は "financial-sector-sic" です。これは「データなし」ではなく「該当なし」として扱ってください。qc_fundamentals.raw["scores"]["notApplicableReason"] から読み取ります。

TTM

ttm はテーブルではなく単一のオブジェクトで、どのバーの時点でもなくアップロード時点での直近 12 か月の集計値です。スナップショットには決して現れません。qc_fundamentals.raw["ttm"] でアクセスしてください（フォワード実行では安全、バックテストでは先読み）。

• メタデータ：basis（"quarterly" / "annual"）、asOf、periodsUsed（list[str]）、complete（bool）、synthetic（bool — 会計上の第 4 四半期が再構成された。通常は正常で、たいてい true）、coverageDays（約 365）。
• フロー — 4 四半期分を合計。epsBasic / epsDiluted（小数 4 桁）を除き、小数 2 桁の文字列：totalRevenue、grossProfit、operatingIncome、ebit、ebitda、netIncome、epsBasic、epsDiluted、depreciationAndAmortization、interestExpense、incomeBeforeTax、incomeTaxExpense、costOfRevenue、sellingGeneralAdministrative、researchDevelopment、taxProvision、totalCashFromOperatingActivities、totalCashflowsFromInvestingActivities、capitalExpenditures、freeCashFlow、dividendsPaid、stockBasedCompensation、paymentsForRepurchaseOfCommonStock、proceedsFromIssuanceOfCommonStock、repaymentsOfLongTermDebt。
• 時点残高 — 最新の期間で、合計されません。小数 2 桁の文字列：totalAssets、totalLiab、totalStockholderEquity、totalCurrentAssets、totalCurrentLiabilities、totalDebt、netDebt、cashAndShortTermInvestments、goodWill、intangibleAssets、netWorkingCapital、retainedEarnings、netReceivables、inventory、accountsPayable、propertyPlantAndEquipmentNet、preferredStockTotalEquity、commonStockSharesOutstanding、minorityInterest。

指標の出所（metricsInputs / metricsHealth）

指標がどこから来たかを説明するフラットなオブジェクト：

価格ベースのフィールドに頼る前に、metricsHealth["prices"] != "absent" を確認してください。"stale" は引き続き使えます — priceAsOf と照らし合わせます。**metricsInputs is None は、指標の拡張前のバンドルを意味します。**フィールドはシンボルが再アップロードされるにつれて現れるため、しばらくはカバレッジにばらつきがあります。上記のすべてのブロックを任意のものとして扱ってください。

指標ブロックの型の規約

**すべての指標は個別に null になりえます。**期間オブジェクトは、メタデータ以外のキーがすべて null の場合は丸ごと省略されます。ブロックは空のとき {"quarterly": {}, "yearly": {}} になり、null になることも省略されることもありません。NaN / Infinity は現れません。

企業情報

companyInfo はフラットなオブジェクトです — 日付をキーとせず、current(...) / get_data_with_offset(...) のスナップショットには現れません。直接アクセスしてください。

---

注意点と落とし穴

• **常に None をガードしてください。**ファンダメンタルデータが設定されていなければ、fundamentals は None です。スナップショットの中でも、個々のセクション（例：earnings.Trend、scores）は一部のバーで null になることがあり、指標の拡張ブロックは古いバンドルでは完全に欠けていることがあります。
• 複数シンボルおよび Screener の実行では、常に symbol= を渡してください — プライマリバンドルへのフォールバックが、いま扱っているティッカーとは限りません。
• **数値は文字列のことがあります。**基になる JSON は数値指標を文字列で送ってくることが多いので、計算するときは float(...) で変換してください。
• 新しい順のインデックスは、日付をキーとするテーブルとオフセット参照の両方に適用されます — インデックス 0 はバーの時点で最も新しい対象期間、1 はその前、というようになります。
• どのレポートが「現在」かは、バーのタイムスタンプが基準です — bar["t"]（または bar.t[0]）をそのまま渡してください。自分で解析する必要はありません。