openseries.ReturnSimulation

class openseries.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.

__init__(**data)

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

data (Any)

Return type:

None

Methods

__init__(**data)

Create a new model by parsing and validating input data from keyword arguments.

construct([_fields_set])

copy(*[, include, exclude, update, deep])

Returns a copy of the model.

dict(*[, include, exclude, by_alias, ...])

from_gbm(number_of_sims, mean_annual_return, ...)

Create a Geometric Brownian Motion simulation.

from_lognormal(number_of_sims, ...[, ...])

Create a Lognormal distribution simulation.

from_merton_jump_gbm(number_of_sims, ...[, ...])

Create a Merton Jump-Diffusion model simulation.

from_normal(number_of_sims, ...[, ...])

Create a Normal distribution simulation.

from_orm(obj)

json(*[, include, exclude, by_alias, ...])

model_construct([_fields_set])

Creates a new instance of the Model class with validated data.

model_copy(*[, update, deep])

!!! abstract "Usage Documentation"

model_dump(*[, mode, include, exclude, ...])

!!! abstract "Usage Documentation"

model_dump_json(*[, indent, ensure_ascii, ...])

!!! abstract "Usage Documentation"

model_json_schema([by_alias, ref_template, ...])

Generates a JSON schema for a model class.

model_parametrized_name(params)

Compute the class name for parametrizations of generic classes.

model_post_init(context, /)

Override this method to perform additional initialization after __init__ and model_construct.

model_rebuild(*[, force, raise_errors, ...])

Try to rebuild the pydantic-core schema for the model.

model_validate(obj, *[, strict, extra, ...])

Validate a pydantic model instance.

model_validate_json(json_data, *[, strict, ...])

!!! abstract "Usage Documentation"

model_validate_strings(obj, *[, strict, ...])

Validate the given object with string data against the Pydantic model.

parse_file(path, *[, content_type, ...])

parse_obj(obj)

parse_raw(b, *[, content_type, encoding, ...])

schema([by_alias, ref_template])

schema_json(*[, by_alias, ref_template])

to_dataframe(name[, start, end, countries, ...])

Create a pandas.DataFrame from simulation(s).

update_forward_refs(**localns)

validate(value)

Attributes

model_computed_fields

model_config

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

model_extra

Get extra fields set during validation.

model_fields

model_fields_set

Returns the set of fields that have been explicitly set on this model instance.

realized_mean_return

Annualized arithmetic mean of returns.

realized_vol

Annualized volatility.

results

Simulation data.

number_of_sims

trading_days

trading_days_in_year

mean_annual_return

mean_annual_vol

dframe

jumps_lamda

jumps_sigma

jumps_mu

seed

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