finlab.data

get(dataset, save_to_storage, force_download, lazy, progress, progress_callback, start, end, as_of, version) -> pd.DataFrame

參數

dataset str

The name of dataset. tw_tick:SYMBOL and tw_minute:SYMBOL return after-market long-form pandas frames and require both dates (at most 31 calendar days). See the intraday data guide.

save_to_storage bool 預設 True

Whether to cache intraday data or retained versions (as_of/version). False raises ValueError for ordinary reads; use data.set_storage(data.CacheStorage()) instead.

force_download bool 預設 False

Whether to force download the dataset from cloud.

lazy bool 預設 False

Return a lazy computation wrapper after fetching the dataset.

progress ProgressMode 預設 'silent'

'display', 'event', or 'silent'.

progress_callback Callable[[ProgressEvent], None] | None

Receives structured events in event mode.

start DateBound

Optional inclusive lower bound on the date column. Accepts any date-like value (string or Timestamp). Pushed down to the Arrow read so only in-range rows are materialised. Requires the dataset to have a date column/index, otherwise raises ValueError.

end DateBound

Optional inclusive upper bound on the date column. Same rules as start; a string covers the whole period it names, as df.loc[:end] does ('2024-03' includes March 31). When both start and end are None the result is byte-identical to a plain read.

as_of DateBound

Return the dataset exactly as it was published at this time (naive values are Asia/Taipei, for every market; a bare date means 00:00 that day, before that day's publications). Only versions the server still retains are available; list them with data.versions(dataset). Requires a paid data plan and counts toward the download quota; a version already downloaded is read from local storage. financial_statement keeps permanent vintages instead (financial_statement_versions).

version str | int | None

Return exactly this generation from data.versions(dataset). Mutually exclusive with as_of.

回傳

pd.DataFrame

financial data as a DataFrame. With pandas 2 (for example on Colab or

pd.DataFrame

Python 3.10) it shares its values with the cache: editing it in place,

pd.DataFrame

such as df.loc[...] = 0 or df.fillna(0, inplace=True), also

pd.DataFrame

changes later data.get results in the same session, including the

pd.DataFrame

prices sim() backtests with. Edit a copy instead

pd.DataFrame

(df = data.get(...).copy()). pandas 3 returns an independent frame.

search(keyword, market, details) -> pd.Series | pd.DataFrame

參數

keyword str | None

market str | None

details bool 預設 False

describe(dataset, market) -> dict[str, Any]

參數

dataset str

market str | None

universe(exchange, sector, exclude_sector, industry, asset_type, security_type, index, whitelist, market, category, exclude_category)

參數

exchange str | list[str] 預設 'ALL'

TW: 'TWSE'/'TPEx' (or legacy 'TSE'/'OTC'). International: 'NASDAQ'/'NYSE'/'AMEX'/'HKEX'/'TSE'/etc. TW uses each stock's current exchange for every date: a stock that moved from TPEx to TWSE counts as TWSE before its move. For date-by-date listing eligibility, use universe.membership().

sector str | list[str] 預設 'ALL'

Sector name(s) with regex matching. Uses the current classification for every date, including categories created later.

exclude_sector str | list[str] | None

Sector(s) to exclude (TW only).

industry str | list[str] 預設 'ALL'

Industry filter (international markets).

asset_type str | None

TW only: 'ETF' or 'STOCK_FUTURE'. 'STOCK_FUTURE' uses the latest underlying list for every historical date: stocks appear before their futures listed, and former underlyings disappear. For historical selection, see the stock-futures backtest example below.

security_type str | list[str] 預設 'ALL'

Security type filter (international markets), e.g. 'common_stock'.

index str | None

Market index to filter by (international markets only). For US market: 'SP500'/'SPX', 'NASDAQ100'/'NDX'. Uses the latest constituent list for every historical date. For historical index selection, see the us_universe backtest example.

whitelist str | Iterable[str] | None

Explicit security IDs; a string is one ID. Alone, bypasses the current market catalog, so delisted IDs can be retained. With other filters, takes their intersection. Empty or zero-overlap selections return empty security data. IDs must already exclude unwanted security types; this static set does not encode listing eligibility by date.

market str | None

Legacy alias for TW exchange+asset_type.

category str | list[str] | None

Legacy alias for sector.

exclude_category str | list[str] | None

Legacy alias for exclude_sector.

範例

TW market (default):

from finlab import data
with data.universe(exchange=['TWSE', 'TPEx'], sector=['鋼鐵工業', '航運業']):
    close = data.get('price:收盤價')

Legacy TW usage (still works):

with data.universe(market='TSE_OTC', sector='水泥', exclude_sector='ETF'):
    close = data.get('price:收盤價')

Stock-futures backtest, from each stock's first futures trade (standard or mini contract). Underlyings no longer listed today are not included:

with data.universe():  # Temporarily clear any existing universe filter.
    close = data.get('price:收盤價')
    underlying = data.get('single_stock_futures_and_equity_options_underlying')
    volume = data.get('futures_price:成交量')
underlying = underlying[underlying['是否為股票期貨標的'] == 'Y']
contracts = underlying['股票期貨、選擇權商品代碼'].astype(str) + 'F一般'
traded = volume.reindex(columns=contracts).gt(0)
traded.columns = underlying['symbol'].astype(str)
listed = traded.T.groupby(level=0).any().T.cummax()
has_futures = listed.reindex(close.index, method='ffill', fill_value=False)
score = close.pct_change(20)
position = score.where(has_futures).is_largest(10)

US market (S&P 500):

data.set_market('us')
with data.universe(index='SP500'):
    close = data.get('price:close')

US market (NASDAQ 100 Technology stocks):

data.set_market('us')
with data.universe(index='NDX', sector='Technology'):
    close = data.get('price:close')

JP market:

data.set_market('jp')
with data.universe(sector='Technology'):
    close = data.get('price:close')

us_universe(sector, industry, exchange, security_type, index)

參數

sector str | list[str] 預設 'ALL'

Sector name(s) to include. Supports regex-like substring matching.

industry str | list[str] 預設 'ALL'

Industry name(s) to include. Supports regex-like substring matching.

exchange str | list[str] 預設 'ALL'

Exchange name(s) to include. Common values: 'NASDAQ', 'NYSE', 'AMEX'.

security_type str | list[str] 預設 'ALL'

Security type(s) to include. Use 'common_stock' for clean US equities.

index str | None

Market index to filter by. Supported values: 'SP500'/'SPX' (S&P 500), 'NASDAQ100'/'NDX' (NASDAQ 100). Can be combined with sector/industry/exchange for further filtering.

範例

from finlab import data
with data.us_universe(sector='Technology', exchange='NASDAQ'):
    close = data.get('us_price:close')

Filter to common stocks only:

with data.us_universe(security_type='common_stock'):
    close = data.get('us_price:close')

Filter to the latest S&P 500 constituents (all historical dates):

with data.us_universe(index='SP500'):
    close = data.get('us_price:close')

Filter to the latest NASDAQ 100 Technology stocks (all historical dates):

with data.us_universe(index='NDX', sector='Technology'):
    close = data.get('us_price:close')

Historical index backtest:

with data.us_universe():  # Temporarily clear any existing universe filter.
    close = data.get('us_price:close')
    constituents = data.get('us_index_constituents:sp500')
in_index = constituents.reindex(close.index, method='ffill').eq(True)
score = close.pct_change(20)
position = score.where(in_index).is_largest(3)

For NASDAQ 100, replace us_index_constituents:sp500 with us_index_constituents:nasdaq100.

indicator(indname, adjust_price, resample, strict, **kwargs) -> pd.DataFrame | tuple[pd.DataFrame, ...]

參數

indname str

指標名稱， 以 TA-Lib 舉例，例如 SMA, STOCH, RSI 等，可以參考 talib 文件。

以 Pandas-ta 舉例，例如 supertrend, ssf 等，可以參考 Pandas-ta 文件。

adjust_price bool 預設 False

是否使用還原股價計算。

resample str 預設 'D'

技術指標價格週期，ex: D 代表日線, W 代表週線, ME 代表月線。 MS 這類標在期初的週期，K 棒改標在該期最後一個交易日，避免提早看到期末價格。

market str

市場選擇，ex: TW_STOCK 代表台股, US_STOCK 代表美股。

strict bool 預設 False

預設 False。True 時只接受 TA-Lib 的數值參數名稱， 拒絕輸入價格 selector；pandas_ta 尚不支援，會拋出 NotImplementedError。 例如 data.indicator('RSI', strict=True, timeperiod=14)。 只檢查名稱，不保證參數在每種設定下都影響結果；參數值由 TA-Lib 檢查。 無股票或全 NaN 時不執行指標計算。

**kwargs dict 預設 {}

技術指標的參數設定，TA-Lib 中的 RSI 為例，調整項為計算週期 timeperiod=14。

set_storage(storage) -> None

參數

storage data.Storage

The interface of storage

範例

欲切換成以檔案方式儲存，可以用以下之方式：

from finlab import data
data.set_storage(data.FileStorage())
close = data.get('price:收盤價')

CacheStorage()

範例

欲切換成以檔案方式儲存，可以用以下之方式：

from finlab import data
data.set_storage(data.CacheStorage())
close = data.get('price:收盤價')

可以直接調閱快取資料：

close = data._storage._cache['price:收盤價']

方法與屬性

set_revision(name, revision) -> None

get_time_expired(name) -> datetime.datetime | None

cache_version(name) -> int | None

published_hash(name) -> str | None

read_dataframe_date_range(name, start, end) -> pd.DataFrame | None

clear() -> None

release_memory() -> None

FileStorage(path, use_cache)

參數

path str

資料儲存的路徑。不指定時用固定的資料夾（本機為 ~/finlab_db），不隨工作目錄改變。 自行指定時請用絕對路徑；'./finlab_db' 這類相對路徑會隨每次執行的工作目錄不同而找不到快取，整包重新下載。

use_cache bool 預設 True

是否額外使用快取，將資料複製一份到記憶體中。

範例

欲切換成以檔案方式儲存，可以用以下之方式：

from finlab import data
data.set_storage(data.FileStorage())
close = data.get('price:收盤價')

可以在本地端的 ~/finlab_db/price#收盤價.feather 中，看到下載的資料， 可以使用 pandas.read_feather 調閱歷史資料：

import pandas as pd
close = pd.read_feather('~/finlab_db/price#收盤價.feather')

方法與屬性

get_dataframe_row_count(name) -> int | None

get_dataframe_index(name) -> pd.Index | None

set_dataframe(name, df, revision, content_hash) -> None

has_feather_cache(name) -> bool

merge_recent_delta(name, short_df, expected_hash, revision) -> bool

merge_table_delta(name, delta, expected_hash, revision) -> bool

set_dataframe_bytes(name, payload, revision) -> None

get_time_created(name) -> datetime.datetime | None

get_time_expired(name) -> datetime.datetime | None

cache_version(name) -> tuple[int, int, int] | None

published_hash(name) -> str | None

set_revision(name, revision) -> None

read_dataframe_date_range(name, start, end) -> pd.DataFrame | None

release_memory() -> None

diagnose(dataset) -> None

from finlab import data
data._storage.diagnose()  # 列出所有本地資料
data._storage.diagnose('price:收盤價')  # 檢查特定資料集

get_strategies(api_token) -> dict[str, Any] | str

參數

api_token str

若未帶入finlab模組的api_token，會自動跳出GUI頁面， 複製網頁內的api_token貼至輸入欄位即可。

回傳

dict

strategies data

dict[str, Any] | str

Response detail:

dict[str, Any] | str

dict[str, Any] | str

{ strategy1:{ 'asset_type': '', 'drawdown_details': { '2015-06-04': { 'End': '2015-11-03', 'Length': 152, 'drawdown': -0.19879090089478024 }, ... }, 'fee_ratio': 0.000475, 'last_trading_date': '2022-06-10', 'last_updated': 'Sun, 03 Jul 2022 12:02:27 GMT', 'ndays_return': { '1': -0.01132480035770611, '10': -0.0014737286933147464, '20': -0.06658015749110646, '5': -0.002292995729485159, '60': -0.010108700314771735 }, 'next_trading_date': '2022-06-10', 'positions': { '1413 宏洲': { 'entry_date': '2022-05-10', 'entry_price': 10.05, 'exit_date': '', 'next_weight': 0.1, 'return': -0.010945273631840613, 'status': '買進', 'weight': 0.1479332345384493 }, 'last_updated': 'Sun, 03 Jul 2022 12:02:27 GMT', 'next_trading_date': '2022-06-10', 'trade_at': 'open', 'update_date': '2022-06-10' }, 'return_table': { '2014': { 'Apr': 0.0, 'Aug': 0.06315180932606546, 'Dec': 0.0537589857541485, 'Feb': 0.0, 'Jan': 0.0, 'Jul': 0.02937490104459939, 'Jun': 0.01367930162104769, 'Mar': 0.0, 'May': 0.0, 'Nov': -0.0014734320286596825, 'Oct': -0.045082529665408266, 'Sep': 0.04630906972509852, 'YTD': 0.16626214846456966 }, ... }, 'returns': { 'time': [ '2014-06-10', '2014-06-11', '2014-06-12', ... ], 'value': [ 100, 99.9, 100.2, ... ] }, 'stats': { 'avg_down_month': -0.03304015302646822, 'avg_drawdown': -0.0238021414698247, 'avg_drawdown_days': 19.77952755905512, 'avg_up_month': 0.05293384465715908, 'cagr': 0.33236021285588846, 'calmar': 1.65261094975066, 'daily_kurt': 4.008888367138843, 'daily_mean': 0.3090784769257415, 'daily_sharpe': 1.747909002374217, 'daily_skew': -0.6966018726321078, 'daily_sortino': 2.8300677082214034, ... }, 'tax_ratio': 0.003, 'trade_at': 'open', 'update_date': '2022-06-10' }, strategy2:{...}, ...}

dict[str, Any] | str