Finlab
Simulate Taiwan equity strategies with FinLab `backtest.sim` before risking real capital.
Overview
FinLab is an agent skill most often used in Validate (also Build backend) that guides historical portfolio simulation with FinLab `backtest.sim` and cost-aware exit parameters.
Install
npx skills add https://github.com/koreal6803/finlab-ai --skill finlabWhat is this skill?
- Core `backtest.sim` API with flexible rebalancing and `trade_at_price` controls
- Models Taiwan-style fee_ratio (1.425/1000) and tax_ratio (3/1000) defaults
- Stop-loss, take-profit, trail stop, and touched_exit portfolio exits
- MAE/MFE windows and optional live_performance_start segmentation
- Fast mode, market selection, and optional result upload paths
- Default fee_ratio 1.425/1000 and tax_ratio 3/1000 in documented `backtest.sim` signature
Adoption & trust: 1.3k installs on skills.sh; 373 GitHub stars; 2/3 security scanners passed (skills.sh audits).
What problem does it solve?
You have position signals but no trustworthy equity curve that includes fees, taxes, and stop rules.
Who is it for?
Solo Taiwan-market or FinLab users iterating systematic equity strategies in Python notebooks or small bots.
Skip if: Builders who need live brokerage execution, non-equity asset classes, or stacks with zero pandas/FinLab dependency.
When should I use this skill?
User is implementing or tuning FinLab backtests, `backtest.sim`, or Taiwan equity strategy simulation.
What do I get? / Deliverables
You produce a named backtest simulation with configurable costs, rebalancing, and risk exits to compare strategies apples-to-apples.
- Configured `backtest.sim` run with named strategy output
- Equity curve and performance metrics under specified fee, tax, and exit rules
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Canonical shelf is Validate because backtests prove strategy shape, costs, and risk knobs before full Build automation. Prototype is where position histories become equity curves with fees, taxes, and stop rules exercised.
Where it fits
Run `backtest.sim` on a weekly rebalance signal to see post-fee performance.
Wrap a validated position generator in a job that reuses the same sim parameters.
Compare backtest tail to live period using `live_performance_start`.
How it compares
FinLab simulation reference for position-driven equity curves—not a generic ML experiment tracker.
Common Questions / FAQ
Who is finlab for?
Independent developers and small teams using FinLab in Python to backtest stock strategies with realistic trading costs.
When should I use finlab?
Use it in Validate prototype when tuning signals; in Build backend when wiring scheduled sims; and in Grow analytics when comparing live versus backtest segments via `live_performance_start`.
Is finlab safe to install?
FinLab is a third-party Python library—review the Security Audits panel on this page, pin versions, and avoid uploading sensitive runs if `upload=True` without reviewing FinLab policies.
SKILL.md
READMESKILL.md - Finlab
# Backtesting Reference ## Overview The FinLab backtesting framework allows you to simulate trading strategies using historical data. The `backtest.sim()` function is the core tool for evaluating strategy performance, supporting various parameters for rebalancing, transaction costs, stop-loss/take-profit, and more. --- ## backtest.sim Simulate the equity curve of a stock portfolio based on its position history and market data. This function supports various parameters for rebalancing frequency, transaction costs, stop loss/take profit, and notification via Line. **Import:** ```python from finlab import backtest ``` **Signature:** ```python sim( position: Union[pd.DataFrame, pd.Series], resample: Union[str, None] = None, resample_offset: Union[str, None] = None, trade_at_price: Union[str, pd.DataFrame] = 'close', position_limit: float = 1, fee_ratio: float = 1.425/1000, tax_ratio: float = 3/1000, name: str = '未命名', stop_loss: Union[float, None] = None, take_profit: Union[float, None] = None, trail_stop: Union[float, None] = None, trail_stop_activation: Union[float, None] = None, touched_exit: bool = False, retain_cost_when_rebalance: bool = False, stop_trading_next_period: bool = True, live_performance_start: Union[str, None] = None, mae_mfe_window: int = 0, mae_mfe_window_step: int = 1, market: Union[None, Market] = None, upload: bool = True, fast_mode: bool = False, notification_enable: bool = False, line_access_token: str = '' ) -> report.Report ``` ### Parameters #### position - **Type:** `Union[pd.DataFrame, pd.Series]` - **Required:** Yes - **Description:** A pandas DataFrame or Series representing the buy/sell signals (True indicates holding, False indicates no position). For short positions, negative values can be used. The index should be a DatetimeIndex, and the columns should represent stock IDs. #### resample - **Type:** `Union[str, None]` - **Default:** `None` - **Description:** Trading frequency or rebalancing dates specification. It can be a string (e.g., 'D', 'W', 'M'), a DataFrame, Series, or None. When None, rebalancing only occurs on changes in the position. #### resample_offset - **Type:** `Union[str, None]` - **Default:** `None` - **Description:** An optional time offset (e.g., '1D', '1H') applied to rebalance dates. #### trade_at_price - **Type:** `Union[str, pd.DataFrame]` - **Default:** `'close'` - **Description:** Specifies which market price to use in the simulation. Options include 'close', 'open', 'open_close_avg', 'high_low_avg', or a custom DataFrame with price data. #### position_limit - **Type:** `float` - **Default:** `1` - **Description:** Limit for the maximum weight assigned to any single asset (e.g., 0.2 for 20%). #### fee_ratio - **Type:** `float` - **Default:** Market-specific *(v1.5.9)* — TW: `1.425/1000`, US: resolved from the active `Market` subclass - **Description:** Commission fee ratio applied during trades. When not explicitly provided, `sim()` consults the target `Market` for its default instead of hardcoding TW-market values, so US/CB backtests use the correct fee schedule automatically. #### tax_ratio - **Type:** `float` - **Default:** Market-specific *(v1.5.9)* — TW: `3/1000`, US: `0` - **Description:** Transaction tax ratio applied when selling stocks. Resolved from the active `Market` when omitted. #### name - **Type:** `str` - **Default:** `'未命名'` - **Description:** Name for the strategy (for reporting purposes). #### stop_loss - **Type:** `Union[float, None]` - **Default:** `None` - **Description:** Stop loss percentage threshold. If set to None, stop loss is disabled. #### take_profit - **Type:** `Union[float, None]` - **Default:** `None` - **Description:** Take profit percentage threshold. If set to None, take profit is disabled. #### trail_stop - **Type:** `Union[float, None]` - **Default:** `None` - **Description:** Trailing stop threshold. If set to None, trai