TradingGym

https://github.com/yvictor/tradinggym
Admin
TradingGym is a toolkit for training and backtesting reinforcement learning algorithms on financial...
Tokens:5,364
Snippets:35
Trust Score:9.3
License:MIT
Update:5 months ago
Show doc for...
Tokens:
Raw
### Install TradingGym

Source: https://github.com/yvictor/tradinggym/blob/master/README.md

Clone the repository, navigate to the directory, and install the package using setup.py.

```bash
git clone https://github.com/Yvictor/TradingGym.git
cd TradingGym
python setup.py install
```

--------------------------------

### env.reset

Source: https://context7.com/yvictor/tradinggym/llms.txt

Starts a new training episode by selecting a trading session and initializing environment states.

```APIDOC
## env.reset — Start a new training episode

### Description
Randomly selects one trading session (identified by `serial_number == 0` boundaries) from the DataFrame, initialises all position and reward arrays to zero, and returns the first observation window. For `backtest_v0` / `backtest_v1`, `reset` uses the full dataset instead of sampling.

### Method
`reset()`

### Parameters
None

### Response
- **obs** (np.ndarray) - The first observation window for the new episode.

### Request Example
```python
import numpy as np

obs = env.reset()
print(obs.shape)
print('Session date:', env.df_sample['datetime'].iloc[0].date())
```
```

--------------------------------

### Execute Backtest Loop

Source: https://github.com/yvictor/tradinggym/blob/master/README.md

Instantiate your agent and run the backtesting loop. The loop continues until `env.backtest_done` is true. Inside the loop, call `env.backtest()` to get the state, then `env.step()` with the agent's action to advance the environment. Transaction information is collected and concatenated into a pandas DataFrame.

```python
agent = YourAgent()

transactions = []
while not env.backtest_done:
    state = env.backtest()
    done = False
    while not done:
        state, reward, done, info = env.step(agent.choice_action(state))
        #print(state, reward)
        #env.render()
        if done:
            transactions.append(info)
            break
transaction = pd.concate(transactions)
transaction
```

--------------------------------

### Reset Trading Environment Episode with env.reset

Source: https://context7.com/yvictor/tradinggym/llms.txt

Call `env.reset()` to start a new episode. For training environments, it randomly samples a trading session. For backtesting environments, it uses the full dataset. The function returns the initial observation window.

```python
import numpy as np

obs = env.reset()
# obs shape: (obs_data_len, len(feature_names) + 9)   when return_transaction=True (training_v1)
# obs shape: (obs_data_len, len(feature_names))        when return_transaction=False
print(obs.shape)   # e.g. (256, 17)  — 8 features + 9 transaction columns
print('Session date:', env.df_sample['datetime'].iloc[0].date())
```

--------------------------------

### Define a Custom Trading Agent

Source: https://github.com/yvictor/tradinggym/blob/master/README.md

Create a custom agent class by inheriting from a base agent or implementing the `choice_action` method. This method should return an integer representing the action: 0 for no action, 1 for buy, and 2 for sell. The example shows a random policy.

```python
class YourAgent:
    def __init__(self):
        # build your network and so on
        pass
    def choice_action(self, state):
        ## your rule base conditon or your max Qvalue action or Policy Gradient action
         # action=0 -> do nothing
         # action=1 -> buy 1 share
         # action=2 -> sell 1 share
        ## in this testing case we just build a simple random policy 
        return np.random.randint(3)
```

--------------------------------

### MA Crossover Rule-Based Agent

Source: https://github.com/yvictor/tradinggym/blob/master/README.md

Example of setting up a TradingGym environment for backtesting and defining a rule-based agent that uses Moving Average (MA) crossovers for trading decisions. The agent returns 1 for a buy signal (MA crossover), 2 for a sell signal (MA crossunder), and 0 otherwise. Requires the 'Price' and 'MA' features.

```python
env = trading_env.make(env_id='backtest_v1', obs_data_len=10, step_len=1,
                       df=df, fee=0.1, max_position=5, deal_col_name='Price', 
                       feature_names=['Price', 'MA'])
class MaAgent:
    def __init__(self):
        pass
        
    def choice_action(self, state):
        if state[-1][0] > state[-1][1] and state[-2][0] <= state[-2][1]:
            return 1
        elif state[-1][0] < state[-1][1] and state[-2][0] >= state[-2][1]:
            return 2
        else:
            return 0
# then same as above
```

--------------------------------

### Initialize and Run Trading Environment

Source: https://github.com/yvictor/tradinggym/blob/master/README.md

Demonstrates how to initialize a trading environment with specified parameters, reset it, take random steps, and render the environment. The loop continues until the episode is done.

```python
import random
import numpy as np
import pandas as pd
import trading_env

df = pd.read_hdf('dataset/SGXTW.h5', 'STW')

env = trading_env.make(env_id='training_v1', obs_data_len=256, step_len=128,
                       df=df, fee=0.1, max_position=5, deal_col_name='Price', 
                       feature_names=['Price', 'Volume', 
                                      'Ask_price','Bid_price', 
                                      'Ask_deal_vol','Bid_deal_vol',
                                      'Bid/Ask_deal', 'Updown'])

env.reset()
env.render()

state, reward, done, info = env.step(random.randrange(3))

### randow choice action and show the transaction detail
for i in range(500):
    print(i)
    state, reward, done, info = env.step(random.randrange(3))
    print(state, reward)
    env.render()
    if done:
        break
env.transaction_details
```

--------------------------------

### Initialize Backtesting Environment

Source: https://github.com/yvictor/tradinggym/blob/master/README.md

Load the backtesting environment using `trading_env.make`. Ensure all necessary parameters like observation data length, step length, DataFrame, fee, max position, deal column name, and feature names are provided.

```python
env = trading_env.make(env_id='backtest_v1', obs_data_len=1024, step_len=512,
                       df=df, fee=0.1, max_position=5, deal_col_name='Price', 
                        feature_names=['Price', 'Volume', 
                                       'Ask_price','Bid_price', 
                                       'Ask_deal_vol','Bid_deal_vol',
                                       'Bid/Ask_deal', 'Updown'])
```

--------------------------------

### env.step

Source: https://context7.com/yvictor/tradinggym/llms.txt

Advances the environment by one action, executes a trade, updates states, and returns the standard Gym tuple.

```APIDOC
## env.step — Advance the environment by one action

### Description
Accepts a discrete action integer, advances the internal rolling window by `step_len` ticks, executes the trade, updates position / reward arrays, and returns the standard Gym tuple `(observation, reward, done, info)`. When `done=True` the `info` attribute on `training_v1` / `backtest_v1` is a DataFrame joining the original tick data with per-tick position, reward, and P&L columns.

### Method
`step(action: int)`

### Parameters
- **action** (int) - Required - The discrete action to take (0=hold, 1=buy/long, 2=sell/short).

### Response
- **obs** (np.ndarray) - The next observation window.
- **reward** (float) - The scalar reward received.
- **done** (bool) - A flag indicating if the episode has ended.
- **info** (pd.DataFrame or None) - Additional information, potentially a DataFrame with transaction details if `done=True` for `training_v1`/`backtest_v1`.

### Request Example
```python
import random

obs = env.reset()
total_reward = 0.0

for _ in range(1000):
    action = random.randrange(3)   # 0=hold, 1=buy/long, 2=sell/short
    obs, reward, done, info = env.step(action)
    total_reward += reward
    if done:
        if info is not None:
            print(info[['Price', 'position', 'reward']].tail())
        print(f'Episode finished. Total reward: {total_reward:.4f}')
        break
```
```

--------------------------------

### Create Trading Environment with trading_env.make

Source: https://context7.com/yvictor/tradinggym/llms.txt

Use `trading_env.make` to instantiate a trading environment. Ensure your DataFrame has a 'serial_number' column for session identification. Configure parameters like observation window length, step length, fees, and maximum position size.

```python
import pandas as pd
import trading_env

# Load tick-level data; DataFrame must contain 'serial_number' (resets to 0 at each session start)
df = pd.read_csv('trading_env/test/data/SGXTWsample.csv',
                 index_col=0, parse_dates=['datetime'])

# Create a training environment (training_v1 is the current recommended version)
env = trading_env.make(
    env_id='training_v1',          # 'training_v0', 'training_v1', 'backtest_v0', 'backtest_v1'
    obs_data_len=256,              # sliding window length fed to the agent
    step_len=128,                  # ticks the window advances per step
    df=df,
    fee=0.1,                       # per-trade fee deducted from reward
    max_position=5,                # maximum long (+5) or short (-5) shares held
    deal_col_name='Price',         # column used to compute P&L
    feature_names=['Price', 'Volume',
                   'Ask_price', 'Bid_price',
                   'Ask_deal_vol', 'Bid_deal_vol',
                   'Bid/Ask_deal', 'Updown'],
    fluc_div=100.0,                # denominator for unrealised-reward normalisation
    gameover_limit=5               # episode ends early if cumulative reward < -gameover_limit
)
# env.action_space  → 3
# env.observation_space → array([obs_data_len * len(feature_names)])
print(trading_env.available_envs())
# ['training_v0', 'training_v1', 'backtest_v0', 'backtest_v1']
```

--------------------------------

### Advance Environment Step with env.step

Source: https://context7.com/yvictor/tradinggym/llms.txt

Use `env.step(action)` to execute a trade and advance the environment. The action is a discrete integer (0=hold, 1=buy, 2=sell). The function returns the next observation, reward, done flag, and info. For `training_v1`/`backtest_v1`, `info` contains detailed transaction data when `done=True`.

```python
import random

obs = env.reset()
total_reward = 0.0

for _ in range(1000):
    action = random.randrange(3)   # 0=hold, 1=buy/long, 2=sell/short
    obs, reward, done, info = env.step(action)
    total_reward += reward
    if done:
        # info is a DataFrame with columns:
        # position, position_variation, entry_cover, price_mean,
        # reward_fluctuant, reward_makereal, reward  (training_v1 / backtest_v1)
        if info is not None:
            print(info[['Price', 'position', 'reward']].tail())
        print(f'Episode finished. Total reward: {total_reward:.4f}')
        break
```

--------------------------------

### Sequential Backtesting with env.backtest_v1

Source: https://context7.com/yvictor/tradinggym/llms.txt

Performs sequential backtesting session by session using `backtest_v1`. The `backtest_done` flag indicates the end of the dataset. Collected `info` DataFrames can be concatenated for analysis.

```python
import numpy as np
import pandas as pd

env = trading_env.make(
    env_id='backtest_v1', obs_data_len=1024, step_len=512,
    df=df, fee=0.1, max_position=5, deal_col_name='Price',
    feature_names=['Price', 'Volume', 'Ask_price', 'Bid_price',
                   'Ask_deal_vol', 'Bid_deal_vol', 'Bid/Ask_deal', 'Updown']
)

class RandomAgent:
    def choice_action(self, state):
        # action=0 hold | action=1 buy | action=2 sell
        return np.random.randint(3)

agent = RandomAgent()
transactions = []

while not env.backtest_done:
    state = env.backtest()       # advances to next session, returns first obs
    done = False
    while not done:
        state, reward, done, info = env.step(agent.choice_action(state))
        if done:
            transactions.append(info)   # info is a full-session DataFrame
            break

all_transactions = pd.concat(transactions)
print(all_transactions[['datetime', 'position', 'reward']].head(10))
```

--------------------------------

### trading_env.make

Source: https://context7.com/yvictor/tradinggym/llms.txt

Factory function to create a trading environment. It validates input data and instantiates one of the four registered environment classes.

```APIDOC
## trading_env.make — Create a trading environment

### Description
The top-level factory function that validates the input DataFrame, checks that required columns exist, and instantiates one of the four registered environment classes (`training_v0`, `training_v1`, `backtest_v0`, `backtest_v1`). The returned object exposes `reset`, `step`, `render`, and `backtest` methods.

### Parameters
- **env_id** (str) - Required - The ID of the environment to create (e.g., 'training_v1').
- **obs_data_len** (int) - Required - The length of the sliding window observation fed to the agent.
- **step_len** (int) - Required - The number of ticks the window advances per step.
- **df** (pd.DataFrame) - Required - The input DataFrame containing market data.
- **fee** (float) - Optional - The per-trade fee deducted from the reward.
- **max_position** (int) - Optional - The maximum number of shares held (long or short).
- **deal_col_name** (str) - Optional - The column name used to compute Profit and Loss.
- **feature_names** (list[str]) - Optional - A list of feature column names to use for observations.
- **fluc_div** (float) - Optional - Denominator for unrealized reward normalization.
- **gameover_limit** (int) - Optional - The episode ends early if cumulative reward is less than this limit.

### Request Example
```python
import pandas as pd
import trading_env

df = pd.read_csv('trading_env/test/data/SGXTWsample.csv',
                 index_col=0, parse_dates=['datetime'])

env = trading_env.make(
    env_id='training_v1',
    obs_data_len=256,
    step_len=128,
    df=df,
    fee=0.1,
    max_position=5,
    deal_col_name='Price',
    feature_names=['Price', 'Volume',
                   'Ask_price', 'Bid_price',
                   'Ask_deal_vol', 'Bid_deal_vol',
                   'Bid/Ask_deal', 'Updown'],
    fluc_div=100.0,
    gameover_limit=5
)
```

### Response
- **env** (object) - The created trading environment object.
```

--------------------------------

### Live Matplotlib Visualization with env.render

Source: https://context7.com/yvictor/tradinggym/llms.txt

Renders a live, multi-panel chart during environment interaction. Subsequent calls update the chart in-place. Pass `save=True` to write PNG frames to disk.

```python
import random

obs = env.reset()
env.render()                    # open the live chart

for i in range(500):
    state, reward, done, info = env.step(random.randrange(3))
    env.render()                # update the chart each step
    env.render(save=True)       # also save frame to fig/<t_index>.png
    if done:
        break
```

--------------------------------

### Trade Pattern and Future Inspection

Source: https://context7.com/yvictor/tradinggym/llms.txt

Inspects market context around transactions using `show_pattern` (before trade) and `show_future` (after trade) on `backtest_v0` or `training_v0`. Requires a completed episode or backtest.

```python
# After a completed episode/backtest on backtest_v0 or training_v0:
print(env.transaction_details)      # all recorded trades as a DataFrame
#    step            datetime transact transact_type   price  share  price_mean  ...

# Inspect the 256-tick window leading up to transaction index 3:
pattern = env.show_pattern(3)
print(pattern[['datetime', 'Price', 'Volume']].tail())

# Inspect ticks from transaction 3 to the start of the next session:
future = env.show_future(3)
print(future[['datetime', 'Price']].head())
```

--------------------------------

### Moving-Average Crossover Rule-Based Agent

Source: https://context7.com/yvictor/tradinggym/llms.txt

A rule-based agent for `backtest_v1` that uses price and a moving-average feature to decide trades. It buys on a golden cross and sells on a death cross.

```python
import numpy as np
import pandas as pd

# df must include a pre-computed 'MA' column alongside 'Price'
env = trading_env.make(
    env_id='backtest_v1', obs_data_len=10, step_len=1,
    df=df, fee=0.1, max_position=5,
    deal_col_name='Price', feature_names=['Price', 'MA']
)

class MACrossAgent:
    def choice_action(self, state):
        # state[-1] = last row, state[-2] = previous row
        # column 0 = Price, column 1 = MA
        price_now, ma_now   = state[-1][0], state[-1][1]
        price_prev, ma_prev = state[-2][0], state[-2][1]
        if price_now > ma_now and price_prev <= ma_prev:   # golden cross → buy
            return 1
        elif price_now < ma_now and price_prev >= ma_prev: # death cross  → sell
            return 2
        return 0  # hold

agent = MACrossAgent()
transactions = []

while not env.backtest_done:
    state = env.backtest()
    done = False
    while not done:
        state, reward, done, info = env.step(agent.choice_action(state))
        if done:
            transactions.append(info)
            break

results = pd.concat(transactions)
print('Total reward:', results['reward'].sum())
```
Tokens:
Raw