Simulation

The ReturnSimulation class.

class openseries.simulation.ReturnSimulation(*, number_of_sims, trading_days, trading_days_in_year, mean_annual_return, mean_annual_vol, dframe, jumps_lamda=0.0, jumps_sigma=0.0, jumps_mu=0.0, seed=None)[source]

Bases: BaseModel

The class ReturnSimulation allows for simulating financial timeseries.

Parameters:

  • number_of_sims (Annotated[int, Gt(gt=0)]) – Number of simulations to generate.

  • trading_days (Annotated[int, Gt(gt=0)]) – Total number of days to simulate.

  • trading_days_in_year (Annotated[int, Strict(strict=True), Ge(ge=1), Le(le=366)]) – Number of trading days used to annualize.

  • mean_annual_return (float) – Mean annual return of the distribution.

  • mean_annual_vol (Annotated[float, Gt(gt=0)]) – Mean annual standard deviation of the distribution.

  • dframe (DataFrame) – Pandas DataFrame object holding the resulting values.

  • jumps_lamda (Annotated[float, Ge(ge=0)]) – This is the probability of a jump happening at each point in time. Defaults to 0.0.

  • jumps_sigma (Annotated[float, Ge(ge=0)]) – This is the volatility of the jump size. Defaults to 0.0.

  • jumps_mu (float) – This is the average jump size. Defaults to 0.0.

  • seed (int | None) – Seed for random process initiation.

number_of_sims: PositiveInt
trading_days: PositiveInt
trading_days_in_year: DaysInYearType
mean_annual_return: float
mean_annual_vol: PositiveFloat
dframe: DataFrame
jumps_lamda: NonNegativeFloat
jumps_sigma: NonNegativeFloat
jumps_mu: float
seed: int | None
model_config = {'arbitrary_types_allowed': True, 'revalidate_instances': 'always', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

property results: DataFrame[source]

Simulation data.

Returns:

Simulation data.

property realized_mean_return: float

Annualized arithmetic mean of returns.

Returns:

Annualized arithmetic mean of returns.

property realized_vol: float

Annualized volatility.

Returns:

Annualized volatility.

classmethod from_normal(number_of_sims, mean_annual_return, mean_annual_vol, trading_days, trading_days_in_year=252, seed=None, randomizer=None)[source]

Create a Normal distribution simulation.

Parameters:

  • number_of_sims (Annotated[int, Gt(gt=0)]) – Number of simulations to generate.

  • trading_days (Annotated[int, Gt(gt=0)]) – Number of trading days to simulate.

  • mean_annual_return (float) – Mean return.

  • mean_annual_vol (Annotated[float, Gt(gt=0)]) – Mean standard deviation.

  • trading_days_in_year (Annotated[int, FieldInfo(annotation=NoneType, required=True, metadata=[Strict(strict=True), Ge(ge=1), Le(le=366)])]) – Number of trading days used to annualize. Defaults to 252.

  • seed (int | None) – Seed for random process initiation.

  • randomizer (Generator | None) – Random process generator.

Returns:

Normal distribution simulation.

Return type:

ReturnSimulation

classmethod from_lognormal(number_of_sims, mean_annual_return, mean_annual_vol, trading_days, trading_days_in_year=252, seed=None, randomizer=None)[source]

Create a Lognormal distribution simulation.

Parameters:

  • number_of_sims (Annotated[int, Gt(gt=0)]) – Number of simulations to generate.

  • trading_days (Annotated[int, Gt(gt=0)]) – Number of trading days to simulate.

  • mean_annual_return (float) – Mean return.

  • mean_annual_vol (Annotated[float, Gt(gt=0)]) – Mean standard deviation.

  • trading_days_in_year (Annotated[int, FieldInfo(annotation=NoneType, required=True, metadata=[Strict(strict=True), Ge(ge=1), Le(le=366)])]) – Number of trading days used to annualize. Defaults to 252.

  • seed (int | None) – Seed for random process initiation.

  • randomizer (Generator | None) – Random process generator.

Returns:

Lognormal distribution simulation.

Return type:

ReturnSimulation

classmethod from_gbm(number_of_sims, mean_annual_return, mean_annual_vol, trading_days, trading_days_in_year=252, seed=None, randomizer=None)[source]

Create a Geometric Brownian Motion simulation.

Parameters:

  • number_of_sims (Annotated[int, Gt(gt=0)]) – Number of simulations to generate.

  • trading_days (Annotated[int, Gt(gt=0)]) – Number of trading days to simulate.

  • mean_annual_return (float) – Mean return.

  • mean_annual_vol (Annotated[float, Gt(gt=0)]) – Mean standard deviation.

  • trading_days_in_year (Annotated[int, FieldInfo(annotation=NoneType, required=True, metadata=[Strict(strict=True), Ge(ge=1), Le(le=366)])]) – Number of trading days used to annualize. Defaults to 252.

  • seed (int | None) – Seed for random process initiation.

  • randomizer (Generator | None) – Random process generator.

Returns:

Geometric Brownian Motion simulation.

Return type:

ReturnSimulation

classmethod from_merton_jump_gbm(number_of_sims, trading_days, mean_annual_return, mean_annual_vol, jumps_lamda, jumps_sigma=0.0, jumps_mu=0.0, trading_days_in_year=252, seed=None, randomizer=None)[source]

Create a Merton Jump-Diffusion model simulation.

Parameters:

  • number_of_sims (Annotated[int, Gt(gt=0)]) – Number of simulations to generate.

  • trading_days (Annotated[int, Gt(gt=0)]) – Number of trading days to simulate.

  • mean_annual_return (float) – Mean return.

  • mean_annual_vol (Annotated[float, Gt(gt=0)]) – Mean standard deviation.

  • jumps_lamda (Annotated[float, Ge(ge=0)]) – This is the probability of a jump happening at each point in time.

  • jumps_sigma (Annotated[float, Ge(ge=0)]) – This is the volatility of the jump size. Defaults to 0.0.

  • jumps_mu (float) – This is the average jump size. Defaults to 0.0.

  • trading_days_in_year (Annotated[int, FieldInfo(annotation=NoneType, required=True, metadata=[Strict(strict=True), Ge(ge=1), Le(le=366)])]) – Number of trading days used to annualize. Defaults to 252.

  • seed (int | None) – Seed for random process initiation.

  • randomizer (Generator | None) – Random process generator.

Returns:

Merton Jump-Diffusion model simulation.

Return type:

ReturnSimulation

to_dataframe(name, start=None, end=None, countries='SE', markets=None)[source]

Create a pandas.DataFrame from simulation(s).

Parameters:

  • name (str) – Name label of the serie(s).

  • start (dt.date | None) – Date when the simulation starts.

  • end (dt.date | None) – Date when the simulation ends.

  • countries (CountriesType) – (List of) country code(s) according to ISO 3166-1 alpha-2. Defaults to “SE”.

  • markets (list[str] | str | None) – (List of) markets code(s) supported by exchange_calendars.

  • self (Self)

Returns:

The simulation(s) data.

Return type:

DataFrame

ReturnSimulation Class

class openseries.simulation.ReturnSimulation(*, number_of_sims, trading_days, trading_days_in_year, mean_annual_return, mean_annual_vol, dframe, jumps_lamda=0.0, jumps_sigma=0.0, jumps_mu=0.0, seed=None)[source]

Bases: BaseModel

The class ReturnSimulation allows for simulating financial timeseries.

Parameters:

  • number_of_sims (Annotated[int, Gt(gt=0)]) – Number of simulations to generate.

  • trading_days (Annotated[int, Gt(gt=0)]) – Total number of days to simulate.

  • trading_days_in_year (Annotated[int, Strict(strict=True), Ge(ge=1), Le(le=366)]) – Number of trading days used to annualize.

  • mean_annual_return (float) – Mean annual return of the distribution.

  • mean_annual_vol (Annotated[float, Gt(gt=0)]) – Mean annual standard deviation of the distribution.

  • dframe (DataFrame) – Pandas DataFrame object holding the resulting values.

  • jumps_lamda (Annotated[float, Ge(ge=0)]) – This is the probability of a jump happening at each point in time. Defaults to 0.0.

  • jumps_sigma (Annotated[float, Ge(ge=0)]) – This is the volatility of the jump size. Defaults to 0.0.

  • jumps_mu (float) – This is the average jump size. Defaults to 0.0.

  • seed (int | None) – Seed for random process initiation.

number_of_sims: PositiveInt
trading_days: PositiveInt
trading_days_in_year: DaysInYearType
mean_annual_return: float
mean_annual_vol: PositiveFloat
dframe: DataFrame
jumps_lamda: NonNegativeFloat
jumps_sigma: NonNegativeFloat
jumps_mu: float
seed: int | None
model_config = {'arbitrary_types_allowed': True, 'revalidate_instances': 'always', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

property results: DataFrame[source]

Simulation data.

Returns:

Simulation data.

property realized_mean_return: float

Annualized arithmetic mean of returns.

Returns:

Annualized arithmetic mean of returns.

property realized_vol: float

Annualized volatility.

Returns:

Annualized volatility.

classmethod from_normal(number_of_sims, mean_annual_return, mean_annual_vol, trading_days, trading_days_in_year=252, seed=None, randomizer=None)[source]

Create a Normal distribution simulation.

Parameters:

  • number_of_sims (Annotated[int, Gt(gt=0)]) – Number of simulations to generate.

  • trading_days (Annotated[int, Gt(gt=0)]) – Number of trading days to simulate.

  • mean_annual_return (float) – Mean return.

  • mean_annual_vol (Annotated[float, Gt(gt=0)]) – Mean standard deviation.

  • trading_days_in_year (Annotated[int, FieldInfo(annotation=NoneType, required=True, metadata=[Strict(strict=True), Ge(ge=1), Le(le=366)])]) – Number of trading days used to annualize. Defaults to 252.

  • seed (int | None) – Seed for random process initiation.

  • randomizer (Generator | None) – Random process generator.

Returns:

Normal distribution simulation.

Return type:

ReturnSimulation

classmethod from_lognormal(number_of_sims, mean_annual_return, mean_annual_vol, trading_days, trading_days_in_year=252, seed=None, randomizer=None)[source]

Create a Lognormal distribution simulation.

Parameters:

  • number_of_sims (Annotated[int, Gt(gt=0)]) – Number of simulations to generate.

  • trading_days (Annotated[int, Gt(gt=0)]) – Number of trading days to simulate.

  • mean_annual_return (float) – Mean return.

  • mean_annual_vol (Annotated[float, Gt(gt=0)]) – Mean standard deviation.

  • trading_days_in_year (Annotated[int, FieldInfo(annotation=NoneType, required=True, metadata=[Strict(strict=True), Ge(ge=1), Le(le=366)])]) – Number of trading days used to annualize. Defaults to 252.

  • seed (int | None) – Seed for random process initiation.

  • randomizer (Generator | None) – Random process generator.

Returns:

Lognormal distribution simulation.

Return type:

ReturnSimulation

classmethod from_gbm(number_of_sims, mean_annual_return, mean_annual_vol, trading_days, trading_days_in_year=252, seed=None, randomizer=None)[source]

Create a Geometric Brownian Motion simulation.

Parameters:

  • number_of_sims (Annotated[int, Gt(gt=0)]) – Number of simulations to generate.

  • trading_days (Annotated[int, Gt(gt=0)]) – Number of trading days to simulate.

  • mean_annual_return (float) – Mean return.

  • mean_annual_vol (Annotated[float, Gt(gt=0)]) – Mean standard deviation.

  • trading_days_in_year (Annotated[int, FieldInfo(annotation=NoneType, required=True, metadata=[Strict(strict=True), Ge(ge=1), Le(le=366)])]) – Number of trading days used to annualize. Defaults to 252.

  • seed (int | None) – Seed for random process initiation.

  • randomizer (Generator | None) – Random process generator.

Returns:

Geometric Brownian Motion simulation.

Return type:

ReturnSimulation

classmethod from_merton_jump_gbm(number_of_sims, trading_days, mean_annual_return, mean_annual_vol, jumps_lamda, jumps_sigma=0.0, jumps_mu=0.0, trading_days_in_year=252, seed=None, randomizer=None)[source]

Create a Merton Jump-Diffusion model simulation.

Parameters:

  • number_of_sims (Annotated[int, Gt(gt=0)]) – Number of simulations to generate.

  • trading_days (Annotated[int, Gt(gt=0)]) – Number of trading days to simulate.

  • mean_annual_return (float) – Mean return.

  • mean_annual_vol (Annotated[float, Gt(gt=0)]) – Mean standard deviation.

  • jumps_lamda (Annotated[float, Ge(ge=0)]) – This is the probability of a jump happening at each point in time.

  • jumps_sigma (Annotated[float, Ge(ge=0)]) – This is the volatility of the jump size. Defaults to 0.0.

  • jumps_mu (float) – This is the average jump size. Defaults to 0.0.

  • trading_days_in_year (Annotated[int, FieldInfo(annotation=NoneType, required=True, metadata=[Strict(strict=True), Ge(ge=1), Le(le=366)])]) – Number of trading days used to annualize. Defaults to 252.

  • seed (int | None) – Seed for random process initiation.

  • randomizer (Generator | None) – Random process generator.

Returns:

Merton Jump-Diffusion model simulation.

Return type:

ReturnSimulation

to_dataframe(name, start=None, end=None, countries='SE', markets=None)[source]

Create a pandas.DataFrame from simulation(s).

Parameters:

  • name (str) – Name label of the serie(s).

  • start (dt.date | None) – Date when the simulation starts.

  • end (dt.date | None) – Date when the simulation ends.

  • countries (CountriesType) – (List of) country code(s) according to ISO 3166-1 alpha-2. Defaults to “SE”.

  • markets (list[str] | str | None) – (List of) markets code(s) supported by exchange_calendars.

  • self (Self)

Returns:

The simulation(s) data.

Return type:

DataFrame

The ReturnSimulation class is used to create simulated financial time series for testing and analysis purposes. It provides methods to generate realistic return patterns based on statistical distributions.