Quantopian APIリファレンス

#この記事について
QuantopianのAPIリファレンスについて、気になる部分をメモ代わりに日本語化しておきます。なお筆者は英語が不自由なので文章はお察し。

#必須のメソッド
アルゴリズムには`initialize`と`handle_data`の2つのメソッドを実装しなければなりません。3番めのメソッドとして`before_trading_start`がありますが、これはオプションです。

##初期化
`initialize(context)`

バックテストの最初に一度だけ呼び出されます。contextオブジェクトはアルゴリズム内のすべての他のメソッドに渡すことができます。

context: 初期化された時点では空の辞書です。プロパティへのアクセスはドット表記法およびブラケット表記法いずれでも可能です。

- context.property
- context[property]

返り値
なし

##マーケットイベントへの対応
```handle_data(context, data)```
マーケットイベント（バーの更新）が起こるたびに呼び出されます。

data: 証券ID(SID)をキーとする辞書で、ユニバース銘柄を含みます。このメソッドが呼ばれた時点の銘柄ユニバースのスナップショットを表します。

context: initializeに登場したものと同じです。ユーザが定義したステータスとportfolioオブジェクトを格納します。

返り値
なし

##トレーディング実行前処理
`before_trading_start(context, data)`
市場が開く前、1日に一度だけ呼び出されます。主な用途は個々の企業の財務データを調査するためQuantopianの基礎データベースを照会することです。企業の基本的なデータを使用して、600以上の測定可能な基準に基づいて、アルゴリズムで使用する銘柄ユニバースを設定することができます。

context: initializeに登場したものと同じです。ユーザが定義したステータスとportfolioオブジェクトを格納します。

返り値
なし


#その他のメソッド
アルゴリズム中では、何種類かの注文用のメソッドを使うことができます。order_target等のファンクションを使って目標のポジションを構築する際には、成立済みの注文は考慮されますが、オープン注文は考慮しません。

##注文メソッド
アルゴリズムで使用できる注文メソッドは表のとおりです。通常注文はamountまたはpercentで指定した株数、金額、割合で注文を作成します。ターゲット注文は既存のポジションを加味して注文後のポジションがamountまたはpercentで指定した株数、金額、割合になるような注文を作成します。
ターゲット注文で目標のポジションを構築する際には、成立済みの注文は考慮されますが、オープン注文は考慮されません。

| 注文種類 | 通常注文     　 | ターゲット注文        |
|:--------|:---------------|:---------------------|
| 株数指定 |order()         |order_target()        |
| 金額指定 |order_value()   |order_target_value()  |
| ウェイト指定 |order_percent() |order_target_percent()|

すべての注文種類において注文タイプstyle=OrderTypeを指定することができます。
デフォルトはMarketOrder（成行）で、StopOrder（逆指値）、LimitOrder（指値）、StopLimitOrder（指値+逆指値）が使用可能です。

- style=MarketOrder(exchange)
- style=StopOrder(stop_price, exchange)
- style=LimitOrder(limit_price, exchange)
- style=StopLimitOrder(limit_price=price1, stop_price=price2, exchange)


###株数指定
`order(security, amount, style=OrderType)`
`order_target(security, amount, style=OrderType)`

orderは指定した銘柄、数量の注文を作成します。
order_targetは注文後の株数が目標株数となるように注文を作成します。もし既存のポジションが無ければ、amountで指定した全量の注文が作成されます。既存のポジションがあった場合、目標株数と現在保有株数の差が注文数量となります。
例えば、現在のポートフォリオでAAPLを5株保有しているとき、order_target(symbol('AAPL'), 20)を実行すると、差分の15株分の注文が作成されます。

security: 証券オブジェクト
amount: 整数で株数を指定します。正の数値は購入、負の数値は売却です。
style: 注文タイプを指定します。

返り値
注文ID


###金額指定
`order_value(security, amount, style=OrderType)`
`order_target_value(security, amount, style=OrderType)`

order_valueは指定した金額で注文を作成します。例えばAAPLを\$1000購入したい場合、order_value(symbol('AAPL'), 1000)と指定しAAPLの価格が\$105だった場合、9株が購入されます。端数は切り捨てられます。
order_target_valueは注文後の金額が目標金額となるように注文を作成します。もし既存のポジションが無ければ、amountで指定した全額の注文が作成されます。既存のポジションがあった場合、目標金額と現在保有金額の差が注文金額となります。
例えば、現在のポートフォリオでAAPLを\$500保有しているとき、order_target_value(symbol('AAPL'), 2000)を実行すると、差分の\$1500の注文が作成されます。

security: 証券オブジェクト
amount: floatで金額を指定します。正の数値は購入、負の数値は売却です。
style: 注文タイプを指定します。

返り値
注文ID


###ウェイト指定
`order_percent(security, amount, style=OrderType)`
`order_target_percent(security, percent, style=OrderType)`

order_percentはポートフォリオの価値に対して、指定したウェイトとなる注文を作成します。ポートフォリオの価値とはポジションの価値とキャッシュの総額をいいます。割合は小数で指定しなければなりません。（0.5なら50%を表す）例えばorder_percent(symbol('AAPL'), .5)を実行すると、現在のポートフォリオの価値の50%のAAPLの買い注文を作成します。
order_target_percentは注文後のウェイトが目標となるように注文を作成します。もし既存のポジションが無ければ、percentで指定した全量の注文が作成されます。既存のポジションがあった場合、目標ウェイトと現在保有ウェイトの差が注文数量となります。
例えば、現在のポートフォリオでAAPLのウェイトが5%だったとき、order_target_percent(symbol('AAPL'), 0.1)を実行すると、差分の5%の注文が作成されます。

security: 証券オブジェクト
amount: ウェイトを指定します。正の数値は購入、負の数値は売却です。
percent: ウェイトを指定します。正の数値は購入、負の数値は売却です。 
style: 注文タイプを指定します。

返り値
注文ID


###注文キャンセル
`cancel_order(order)`
指定した注文を取り消します。

order: 注文ID

返り値
なし


###注文情報の取得
`get_open_orders(sid=sid)`
証券IDが指定されないまたはNoneの場合は、証券IDをキーとする辞書が返されます。辞書は証券IDごとの注文情報のリストを古いものから順に格納しています。
証券IDが指定された場合は、証券IDに関する発注済みの注文を古いものから順に格納したリストを返します。

sid: (オプション)証券ID

返り値
辞書またはリスト


###注文情報の取得

get_order(order)
指定した注文情報を返します。

order: 注文ID

返り値
読み書き可能な注文オブジェクトを返しますが、handle_dataの最後で破棄されます。


##Interactive Brokers証券での注文実行
###Relative Order
`order(security, amount, style=RelativeOrder(offset, pct_offset, limit_price, exchange))`
RelativeOrderとは、NBBO(National Best Bid & Offer)[^1]より積極的な価格で約定することを許容する注文形態です。NBBOより積極的なBidとOfferを提示することで、注文が約定する可能性を高めることができます。
固定オフセット（例えばBid/Offerの2セント上下）と、パーセンテージオフセットがあり、それらを組み合わせて使用することもできます。クオートは相場の動きに合わせて自動的に調整されます。

[^1]: ...国内のすべての取引所およびマーケットメーカーから提示されるプライスのうち、投資家に最も有利なBidとOfferをとったもの。

この注文形態を使用するためには、IB's market data for Relative Ordersを購読します。そうでない場合、IBは15分遅れの相場情報を配信します。

買い注文の場合、NBB(National Best Bid)が上昇した場合は自動的に注文価格も上方に修正されます。NBBが下落した場合には注文価格は調整されません。これは、NBBが下落したことで既にある注文はより積極的になったと考えられるためです。

売り注文の場合、NBO(National Best Offer)が下落した場合は自動的に注文価格も下方に修正されます。NBOが上昇した場合には注文価格は調整されません。これは、NBOが上昇したことで既にある注文はより積極的になったと考えられるためです。

もし固定オフセットとパーセンテージオフセットの両方を指定した場合、IBは2つの価格のうちで可能かつより積極的な方を採用します。（買いの場合はより高い方、売りの場合はより低い方）

この注文形態では、買いの場合では指定した価格以上、売りの場合では指定した価格以下で約定しないように制限を指定することもできます。

この注文形態でバックテストを行った場合、注文は単純な成行注文となります。本当にRelativeOrderとして動作するのは、IBリアルマネー口座で実行した場合のみです。

将来的に、バックテスターがこの注文形態をサポートしたときには、カスタムのスリッページモデルを設定することになるでしょう。

この注文形態を使用するためには、brokers.ibライブラリからRelativeOrderをimportする必要があります。

security: 証券オブジェクト
amount: 注文株数。
offset: 現在のNBBまたはNBOからの固定オフセット値。ドル単位。
pct_offset: 現在のNBBまたはNBOからのパーセンテージオフセット値。0から100の間で指定します。
limit_price: 買いの場合の最高価格または売りの場合の最低価格を指定します。
exchange: 使用しません。この注文形態の場合、IB Live TradingではSMART[^2]で発注されます。Live Tradingでない場合は無視されます。IEX取引所へのルーティングは許可されません。

[^2]: SMART...Smart order routing(SOR)、国内取引所や私設取引所(PTS)など複数の市場から最良価格がある市場を自動的に選び、売買を執行する注文のこと。

###VWAPBestEffort
```py:
order(security, amount, style=VWAPBestEffort(limit_price=price1, start_date=date1,
                                             end_date=date2, max_pct_vol=percent,
                                             avoid_liquidity=False, exchange=Exchange))
```
VWAPBestEffortとは、注文を小さく分割し、それらを指定した期間にわたって執行することで、出来高加重平均価格(VWAP)に近づけようとするものです。
この注文形態はIBのlive tradingでのみ使用可能です。IBは成行注文と指値注文についてベストエフォートVWAPをサポートしています。逆指値注文と、指値+逆指値注文には対応していません。
この注文形態はorder, order_target, order_value, order_target_percentを含む注文形態と互換性があります。一度成行または指値注文がIBに発注されると、ブローカーはその注文を約定させるためベストエフォートアルゴリズムを使うでしょう。

このメソッドを使用すると、注文は期間内に部分的に約定され、終了日までに全部約定されます。注文ロジックを動作させるため、アルゴリズムでオープン注文をチェックすることを強く推奨します。

VWAP注文を行うためにはbrokers.ibからVWAPBestEffortクラスをインポートする必要があります。

security: 証券オブジェクト
amount: 注文株数。
limit_price: (optional) 小数値で注文の制限価格を指定します。Noneを指定すると成行注文になります。
start_date: (optional) VWAPの開始期間を指定します。デフォルトではアルゴリズム時間の1分後です。BestEffort注文はIBの次の分足から執行されます。
end_date: (optional) VWAPの終了期間を指定します。デフォルトでは取引終了時刻です。
max_pct_volume: (optional) 1日の出来高のうち何パーセントまでの取引を許容するかをパーセンテージで指定します。可能な範囲は0.01 – 0.5です。デフォルトでは0.25です。
avoid_liquidity: (optional) 注文がbid/offerを叩かないようにします。これは流動性取得手数料[^3]を回避する助けとなり、流動性提供リベートを得られるでしょう。しかしながら、ベンチマークとの乖離が大きくなるかもしれません。このパラメータは真偽値でデフォルトはFalseです。
exchange: (optional) 注文のルーティングを指定します。IB Live TradingでのデフォルトはSMARTです。Live Tradingでない場合は無視されます。IEX取引所へのルーティングは許可されません。

返り値
注文ID


#パイプライン
// 別途まとめる予定

#その他のメソッド
##ヒストリカルデータ取得
`history(bar_count, frequency, field, ffill=True)`
日毎に可変のヒストリカルデータを取得します。

bar_count: 整数でバーの数を指定します。数には現在のバーを含みます。
frequency: データを取得する頻度を指定します。'1d'と'1m'が使用可能です。
field: ヒストリカルデータから取得する値を指定します。
'open_price', 'close_price', 'price', 'high', 'low', 'volume'のいずれかを指定できます。
ffill: ヒストリカルデータに欠落がある場合に、前のデータを利用して欠落を埋めるかどうかを指定します。デフォルトはTrueです。もしFalseにした場合、プライスデータならばnp.nan、出来高ならば0が返されます。

返り値
pandas.DataFrame形式で、row数はbar_count、値はfieldで指定した値、columnは現在のユニバースのSecurity IDとなります。


##チャートへの記録
`record(series1_name=value1, series2_name=value2, ...)`
`record('series1_name', value1, 'series2_name', value2, ...)`
引数で与えられた値を記録します。記録されたすべての内容について、チャートを出力します。
values: 最大5つまでのキーワードおよび値を設定できます。

返り値
なし

##定期実行処理
`schedule_function(func=myfunc, date_rule=date_rule, time_rule=time_rule, half_days=True)`
事前に定義したスケジュールで自動的にファンクションを実行します。initializeの中からのみ呼び出すことができます。

func: ファンクション名を定義します。ファンクションはcontextとdataをパラメータにしなければなりません。
date_rule: スケジュールにおける日付部分を指定します。日付は毎日、毎週、毎月のそれぞれ初めまたは終わりから、オフセットで指定することが出来ます。デフォルトは毎日でオフセットは0です。言い換えると、日付のルールを指定しない場合はファンクションは毎日実行されます。
適用できるルールは以下のとおり。

- `date_rules.every_day()`
- `date_rules.week_start(days_offset=0)`
- `date_rules.week_end(days_offset=0)`
- `date_rules.month_start(days_offset=0)`
- `date_rules.month_end(days_offset=0)`

time_rule: スケジュールにおける時刻部分を指定します。時刻は取引開始または取引終了のそれぞれ初めまたは終わりから、オフセットで指定することができます。デフォルトは取引開始時および取引終了1分前です。
適用できるルールは以下のとおり。

- `time_rules.market_open(hours=0, minutes=1)`
- `time_rules.market_close(hours=0, minutes=1)`

half_days: ブール値で半日立会の日の動作を指定します。Falseにすると、半日立会の日はファンクションは呼び出されません。デフォルトはTrueです。

返り値
なし

##ティッカーシンボルの取得
`set_symbol_lookup_date('YYYY-MM-DD')`
日付を指定して、その時点で有効なティッカーシンボルをユニバースとします。symbolまたはsymbolsファンクションを呼び出す前に、initializeの中で実行する必要があります。

date: YYYY-MM-DD 形式の文字列

返り値
なし


###証券オブジェクトの取得
`sid(int)`
証券IDを指定して証券オブジェクトを取得します。

int: 証券ID

返り値
証券オブジェクト


`symbol('symbol1')`
ティッカーシンボルを指定して証券オブジェクトを取得します。

'symbol1': ティッカーシンボル

返り値
証券オブジェクト


`symbols('symbol1', 'symbol2', ...)`
カンマ区切りでティッカーシンボルを指定して証券オブジェクトのリストを取得します。

'symbol1', 'symbol2', ...: ティッカーシンボル

返り値
証券オブジェクトのリスト


###ユニバース更新
`update_universe(sids)`
銘柄ユニバースを更新します。before_trading_startの中で呼び出されます。

sids: 証券IDのリスト

返り値
なし