This QuantMar thread contains the full documentation for the Theseus Python library. Theseus is an open source Python library that provides straightforward tools for cohort analysis and general marketing performance analysis. Theseus was created by Eric Benjamin Seufert of Heracles.
For usage examples, see the Theseus GitHub page. The purpose of this thread is to provide documentation on the various functions that are available in the Theseus class.
Generate a retention profile from day-indexed retention data.
Parameters:
days: list. A list of integer day values that correspond to (ie. have the same index as) retention values in the retention_values parameter. The list does not need to be sorted. The list must be of the same length as retention_values. Values cannot be less than 0. Day 0 retention is assumed to always be 100, so Day 0 retention values need not be supplied.
retention_values: list. A list of integer retention values that correspond to (ie. have the same index as) the days parameter. Note that the retention values should represent percentages but be provided as integers (eg. 80% retention is provided in retention_values as 80, not .8). Values cannot be less than 0 or greater than 100. Day 0 retention is assumed to always be 100, so Day 0 retention values need not be supplied.
form: string (optional). The function that should be fit to the retention data to produce the retention profile. If form is not supplied, the best fit function will be fit to the retention data. Form can only take one of the values of: [ 'log', 'exp', 'linear', 'quad', 'weibull', 'power' ].
profile_max: int (optional). The timeline over which the retention profile will be projected. If profile_max is not provided, profile_max will be set to the maximum value from the days paramter (ie. the retention profile curve will only be fit across the data provided and won't be projected past that).
Returns: a dict containing the retention profile and various other meta data for the retention data provided.
Build a forward DAU projection based on a retention profile created via the create_profile method
Parameters:
profile: dict. This is the retention profile generated with create_profile.
periods: int. The number of periods that should be projected. Minimum value is 2.
cohorts: list. A list of integers representing the size of cohorts being projected. Cohort values must be integers greater than 0.
DAU_target: int (optional). A DAU value that the projection should reach over the course of DAU_target_timeline, starting with the last cohort. When DAU_target is set, Theseus will run a linear regression from the value of the DAU at the time of the last cohort through to the DAU target over the course of DAU_target_timeline and insert those regression values as new cohorts into the forward DAU projection. Note that if DAU_target is set, then DAU_target_timeline must also be set.
DAU_target_timeline: int (optional). The timeline over which the DAU_target value should be reached. Since the DAU_target_timeline only starts from the day of the last cohort, the value of DAU_target_timeline must be less than or equal to the number of periods minus the number of cohorts. Note that if DAU_target is set, then DAU_target_timeline must also be set.
start_date: int (optional). The day from which the projection should start. The default value is 1.
Returns: a DataFrame object containing the forward DAU projection.
theseus.theseus.DAU_total
theseus.DAU_total( self, forward_DAU )
Sums the DAU values in a forward DAU projection into totals
Parameters:
forward_DAU: DataFrame. The forward DAU projection that totals should be generated from; each day (column) is summed into a total.
Returns: a DataFrame containing just one row of the total values of the DAU_projection that was passed as a parameter.
Generates and displays a stacked bar graph representing a forward DAU projection, with each cohort being visualized as a bar (Y axis) and each stack summing to the total DAU for that given day (X axis)
Parameters:
forward_DAU: DataFrame. The forward DAU projection being visualized.
forward_DAU_labels: list. A list of labels that will be used for the cohorts as represented by stacked bars in the chart. A sensible value to supply for this parameter is list( forward_DAU.index )
forward_DAU_dates: list. A list of labels that will be used for the days on the X axis. A sensible value to supply for this parameter is list( facebook_DAU.columns ).
show_values: bool (optional). A True / False setting that determines whether the value of each bar is printed onto it. Default value is False. For forward DAU projections with very many days, setting this value to True will render the graph very difficult to read.
show_totals_values: bool (optional). A True / False setting that determines whether the total value for each day of the forward DAU projection will be printed at the top of the stacked bar. Default value is False.
Creates a forward DAU projection that contains the number of DAU on each day that is at least X days old, where X is some age that is provided in the ages parameter. Each value from ages is represented as a row.
Parameters:
profile: dict. This is the retention profile generated with create_profile.
periods: int. The number of periods that should be projected. Minimum value is 2.
cohorts: list. A list of integers representing the size of cohorts being projected. Cohort values must be integers greater than 0.
start_date: int (optional). The day from which the projection should start. The default value is 1.
ages: list. A list of positive integers corresponding to the minimum ages that should be segmented out from overall DAU values.
Returns: a DataFrame containing one row per value submitted in ages with column values corresponding to the number of DAU each day that are at least that old
Creates a forward DAU projection that contains the number of DAU on each day that is exactly X days old, where X is some age that is provided in the ages parameter. Each value from ages is represented as a row.
Parameters:
profile: dict. This is the retention profile generated with create_profile.
periods: int. The number of periods that should be projected. Minimum value is 2.
cohorts: list. A list of integers representing the size of cohorts being projected. Cohort values must be integers greater than 0.
start_date: int (optional). The day from which the projection should start. The default value is 1.
ages: list. A list of positive integers corresponding to the exact ages that should be segmented out from overall DAU values.
Returns: a DataFrame containing one row per value submitted in ages with column values corresponding to the number of DAU each day that are exactly that old
Saves the contents of a forward DAU projection as a .xlsx Excel file
Parameters:
df: DataFrame. The forward DAU projection DataFrame to be exported.
file_name: str (optional). The name of the file that should be saved. The default value is 'theseus_output.xlsx'. Note that this should not include a file path: the file will be saved into the active directory.
sheet_name: str (optional). The name of the worksheet into which the data from the forward DAU projection will be copied. The default value is 'sheet1'.
Returns: None.
theseus.theseus.to_json
theseus.to_json( self, df, file_name = None )
Converts the contents of a forward DAU projection to JSON and saves it as a .json file
Parameters:
df: DataFrame. The forward DAU projection DataFrame to be exported.
file_name: str (optional). The name of the file that should be saved. The default value is 'theseus_output.json'. Note that this should not include a file path: the file will be saved into the active directory.
