Forecaster¶
Conversational Forecasting Transformers.
Refer to CRAFT Model and Cumulative Bag-of-Words for the models that Forecaster can be loaded with.
Example usage: CRAFT forecasting of conversational derailment.
Example usage: Forecasting of conversational derailment using a cumulative bag-of-words model.
-
class
convokit.forecaster.forecaster.
Forecaster
(forecaster_model: convokit.forecaster.forecasterModel.ForecasterModel = None, forecast_mode: str = 'future', convo_structure: str = 'branched', text_func=<function Forecaster.<lambda>>, label_func: Callable[[convokit.model.utterance.Utterance], bool] = <function Forecaster.<lambda>>, use_last_only: bool = False, skip_broken_convos: bool = True, forecast_attribute_name: str = 'forecast', forecast_prob_attribute_name: str = 'forecast_prob')¶ Implements basic Forecaster behavior.
- Parameters
forecaster_model – ForecasterModel to use, e.g. cumulativeBoW or CRAFT
forecast_mode – ‘future’ or ‘past’. ‘future’ (the default behavior) annotates each utterance with a forecast score using all context up to and including that utterance (i.e., a prediction of the future state of the conversation after this utterance). ‘past’ annotates each utterance with a forecast score using all context prior to that utterance (i.e., what the model believed this utterance would look like prior to actually seeing it)
convo_structure – conversations in expected corpus are ‘branched’ or ‘linear’, default: “branched”
text_func – optional function for extracting the text of the utterance, default: uses utterance’s text attribute
label_func – callable function for getting the utterance’s forecast label (True or False); only used in training
use_last_only – if forecast_mode is ‘past’ and use_last_only is True, for each dialog, use only the context-reply pair where the reply is the last utterance in the dialog
skip_broken_convos – if True and convo_structure is ‘branched’, exclude all conversations that have broken reply-to structures, default: True
forecast_attribute_name – metadata feature name to use in annotation for forecast result, default: “forecast”
forecast_prob_attribute_name – metadata feature name to use in annotation for forecast result probability, default: “forecast_prob”
-
fit
(corpus: convokit.model.corpus.Corpus, y=None, selector: Callable[[convokit.model.conversation.Conversation], bool] = <function Forecaster.<lambda>>, ignore_utterances: Callable[[convokit.model.utterance.Utterance], bool] = <function Forecaster.<lambda>>)¶ Train the ForecasterModel on the given corpus.
- Parameters
corpus – target Corpus
selector – a (lambda) function that takes a Conversation and returns a bool: True if the Conversation is to be included in the fitting step. By default, includes all Conversations.
ignore_utterances – a (lambda) function that takes an Utterance and returns a bool: True if the Utterance should be excluded from the Conversation in the fitting step. By default, all Utterances are included.
- Returns
fitted Forecaster Transformer
-
fit_transform
(corpus: convokit.model.corpus.Corpus, y=None, selector: Callable[[convokit.model.conversation.Conversation], bool] = <function Forecaster.<lambda>>, ignore_utterances: Callable[[convokit.model.utterance.Utterance], bool] = <function Forecaster.<lambda>>) → convokit.model.corpus.Corpus¶ Fit and run the Transformer on a single Corpus.
- Parameters
corpus – the Corpus to use
- Returns
same as transform
-
get_model
()¶ Get the forecaster model object
-
set_model
(forecaster_model)¶ Set the forecaster model :return:
-
summarize
(corpus: convokit.model.corpus.Corpus, selector: Callable[[convokit.model.conversation.Conversation], bool] = <function Forecaster.<lambda>>, ignore_utterances: Callable[[convokit.model.utterance.Utterance], bool] = <function Forecaster.<lambda>>, exclude_na=True)¶ Returns a DataFrame of utterances and their forecasts (and forecast probabilities)
- Parameters
corpus – target Corpus
exclude_na – whether to drop NaN results
selector – a (lambda) function that takes a Conversation and returns a bool: True if the Conversation is to be included in the summary step. By default, includes all Conversations.
ignore_utterances – a (lambda) function that takes an Utterance and returns a bool: True if the Utterance should be excluded from the Conversation in the summary step. By default, all Utterances are included.
- Returns
a pandas DataFrame
-
transform
(corpus: convokit.model.corpus.Corpus, selector: Callable[[convokit.model.conversation.Conversation], bool] = <function Forecaster.<lambda>>, ignore_utterances: Callable[[convokit.model.utterance.Utterance], bool] = <function Forecaster.<lambda>>) → convokit.model.corpus.Corpus¶ Annotate the corpus utterances with forecast and forecast score information
- Parameters
corpus – target Corpus
selector – a (lambda) function that takes a Conversation and returns a bool: True if the Conversation is to be included in the transformation step. By default, includes all Conversations.
ignore_utterances – a (lambda) function that takes an Utterance and returns a bool: True if the Utterance should be excluded from the Conversation in the transformation step. By default, all Utterances are included.
- Returns
annotated Corpus
-
class
convokit.forecaster.forecasterModel.
ForecasterModel
(forecast_attribute_name: str = 'prediction', forecast_prob_attribute_name: str = 'score')¶ -
abstract
forecast
(id_to_context_reply_label)¶ Use the Forecaster Model to compute forecasts and scores for given context-reply pairs and return a results dataframe
-
abstract
train
(id_to_context_reply_label)¶ Train the Forecaster Model with the context-reply-label tuples
-
abstract