Flow Matrix

The Flow Matrix is the most central component of stock-flow consistent economcis.

enum sfctools.core.flow_matrix.Accounts(value)

Bases: enum.Enum

Enum for account type in flow matrix. Current and capital account is allowed

Valid values are as follows:

KA = <Accounts.KA: 0>
CA = <Accounts.CA: 1>
class sfctools.core.flow_matrix.FlowMatrix(*args, **kwargs)

Bases: sfctools.core.singleton.Singleton

The flow matrix takes care of the flows between agents and the stock-flow consistency. It has the following structure:

Flow Matrix

Agent 1

Agent 2

TOTAL

CA

KA

CA

KA

Flows

-x

+x

0

d(Stocks)

+x

-x

0

TOTAL

0

0

0

0

0
CA: Current Account, KA: Capital Account.

As a consistency check, the sum of rows and columns should be zero after the end of each simulation period. For more information, see

property capital_flow_data

‘shortcut’ property. only returns the data from the capital account

check_consistency()

Checks the consistency of the transaction flow matrix.

convert_sankey_df()

Converts the FlowMatrix data to a sankey-plottable dataframe format. This is meant to increase the flexibility in data retrieval and plotting capabilities. To directly plot the FlowMatrix, see plot_sankey

Returns

tuple of dataframes - sankey_source, sankey_sink

property current_flow_data

‘shortcut’ property. only returns the dta fromt he current flow account

log_flow(kind, quantity, agent_from, agent_to, subject, price=None, invert=False)

Registers a flow at the flow matrix. This is no method for the user in most cases. It is automatically generated in the qattune gui.

Parameters

  • kind – tuple (from_account,to_account)

  • quantity – weight (quantity) of the flow

  • price – float or None (default). If not None, a price conversion factor is applied. Should not be used in most cases

  • invert – reverse sign of the transferred quantity? Default False, should not be used in most cases

  • agent_from – Agent instance (optionally str), sender agent

  • agent_to – Agent instnace (optionally str), receiver agent

Example

from sfctools import FlowMatrix, Accounts
CA = Accounts.CA
KA = Accounts.KA

flow = (CA,KA) # from account -> to account
FlowMatrix().log_flow(flow, 42.0, agent1, agent2, subject="my_subject")
# ...

df = FlowMatrix().to_dataframe(group=True)
print(FlowMatrix().to_string(group=True))
FlowMatrix().check_consistency() # ok if no error is raised
plot(group=True)
plot_colored(show_plot=True, group=True, cmap='coolwarm', show_values=True)

Plots the flow matrix as a nice colored heat map. This will open up a matplotlib window…

Parameters

  • show_plot – show the plot as window? default True. If False, figure is returned instead

  • group – aggregated view?

  • cmap – colormap to use (default ‘coolwarm’)

  • show_values – (default True) show numerical values above colored tiles

Return fig

figure object

plot_sankey(show_values=True, show_plot=True, colors=None, label_rot=0.0, filling_fraction=0.85)

plots a sankey diagram of the flow matrix

Parameters

  • show_values – boolean switch to plot the values of the edge weights

  • show_plot – show the plot as window? default True. If False, figure is returned instead.

  • colors – (optional) a list of colors (if None, default colors are chosen)

  • label_rot – rotation of the labels

  • filling_fraction – controls the ‘thickness’ of the Sankey bands

Return fig

figure object

reset(verbose=False)

reset the data :param verbose: boolean (default False), triggers a reset warning if True

reset_count = 0
to_dataframe(group=True, insert_nullsym=True)

Converts the data structure to a human-readable dataframe format. WARNING this is slow

Parameters

  • group – boolean switch (default True), if True it will group the agents of the same class together

  • insert_nullsym – will insert ‘.-‘ symbol instead of zero, default True

Returns

pandas dataframe object

to_string(group=True)

converts the flow matrix to string representation :return : str