marketflows.analysis.aggregates

Aggregation helpers for analysis.

Builds a master time index, aggregates assets into groups and market-cap ranges, and prepares long-form data for bucketed range calculations.

Functions

`aggregate_cap_range_growths`(*, df_long)	Calculate growths for each market cap bucket.
`aggregate_cap_range_inflections`(*, df_long)	Calculate inflections for each market cap bucket.
`aggregate_cap_ranges`(*, df_long[, bucket_column])	Sum market caps of assets from each group together.
`aggregate_groups`(*, group_assets, df_master)	Sum market caps of assets from each group together.
`create_master_df`(asset_mcs, *, freq, ...)	Create a master dataframe from the asset market caps.
`prepare_cap_ranges`(*, range_lower_limits, ...)	Prepare data for calculating market cap range values, growth, and inflection.

marketflows.analysis.aggregates.aggregate_cap_range_growths(*, df_long)

Calculate growths for each market cap bucket.

Parameters:: df_long (DataFrame) – market caps for all the assets with one master datetime index organized into blocks of one asset after another
Return type:: DataFrame
Returns:: dataframe of market cap growths for each bucket at each master datetime

marketflows.analysis.aggregates.aggregate_cap_range_inflections(*, df_long)

Calculate inflections for each market cap bucket.

Parameters:: df_long (DataFrame) – market caps for all the assets with one master datetime index organized into blocks of one asset after another
Return type:: DataFrame
Returns:: dataframe of market cap inflections for each bucket at each master datetime

marketflows.analysis.aggregates.aggregate_cap_ranges(*, df_long, bucket_column='lower_limit')

Sum market caps of assets from each group together.

Parameters:

df_long (DataFrame) – market caps for all the assets with one master datetime index organized into blocks of one asset after another
bucket_column (str, default: "lower_limit") – name of column that contains buckets

Return type:

DataFrame

Returns:

dataframe of market caps for each group at each master datetime

Examples

>>> import pandas as pd
>>> idx = pd.date_range("2020-01-01", periods=2, freq="1s", tz="UTC", name="Datetime")
>>> index = pd.Index([idx[0], idx[0], idx[1], idx[1]], name="Datetime")
>>> df_long = pd.DataFrame(
...     {"asset": ["a", "b", "a", "b"], "market_caps": [10.0, 20.0, 11.0, 19.0], "lower_limit": [0.0, 0.0, 0.0, 0.0]},
...     index=index,
... )
>>> aggregate_cap_ranges(df_long=df_long).to_dict("list")
{0.0: [30.0, 30.0]}

marketflows.analysis.aggregates.aggregate_groups(*, group_assets, df_master)

Sum market caps of assets from each group together.

Parameters:

group_assets (dict[str, set[str]] | None) – for each group, the set of assets within it
df_master (DataFrame) – market caps for all the assets with one master datetime index

Return type:

DataFrame

Returns:

dataframe of market caps for each group at each master datetime

Examples

>>> import pandas as pd
>>> idx = pd.date_range("2020-01-01", periods=2, freq="1s", tz="UTC", name="Datetime")
>>> df_master = pd.DataFrame({"a": [10.0, 11.0], "b": [20.0, 19.0]}, index=idx)
>>> group_assets = {"grp": {"a", "b"}}
>>> aggregate_groups(group_assets=group_assets, df_master=df_master).to_dict("list")
{'grp': [30.0, 30.0]}

marketflows.analysis.aggregates.create_master_df(asset_mcs, *, freq, min_timestamp, max_timestamp)

Create a master dataframe from the asset market caps.

Creates timestamps from frequency and min timestamp, interpolating the market caps of all other assets to these timestamps.

Parameters:

asset_mcs (dict[str, DataFrame]) – the asset market caps
freq (str) – frequency to interpolate to
min_timestamp (Timestamp) – the min timestamp used to create timestamps
max_timestamp (Timestamp) – the max timestamp used to create timestamps

Return type:

DataFrame

Returns:

master dataframe

Examples

>>> import pandas as pd
>>> asset_mcs = {
...     "nvidia": pd.DataFrame(
...         {"timestamps": [0, 1000], "market_caps": [10.0, 20.0]}
...     )
... }
>>> df = create_master_df(asset_mcs, freq="1s", min_timestamp=pd.Timestamp(0, unit="ms", tz="UTC"), max_timestamp=pd.Timestamp(1000, unit="ms", tz="UTC"))
>>> df.to_dict("list")
{'nvidia': [10.0, 20.0]}
>>> df.index.name
'Datetime'

marketflows.analysis.aggregates.prepare_cap_ranges(*, range_lower_limits, df_master)

Prepare data for calculating market cap range values, growth, and inflection.

Parameters:

range_lower_limits (list[float]) – the lower limits of each of the market cap ranges
df_master (DataFrame) – market caps for all the assets with one master datetime index

Return type:

DataFrame

Returns:

DataFrame with each asset after another

Examples

>>> import pandas as pd
>>> idx = pd.date_range("2020-01-01", periods=2, freq="1s", tz="UTC", name="Datetime")
>>> df_master = pd.DataFrame({"a": [40.0, 60.0], "b": [1.0, 2.0]}, index=idx)
>>> df_long = prepare_cap_ranges(range_lower_limits=[50.0], df_master=df_master)
>>> sorted(df_long["asset"].unique().tolist())
['a']
>>> df_long["lower_limit"].dropna().unique().tolist()
[50.0]
>>> df_long.index.name
'Datetime'