Base classes (API reference)

These are the extension points of fastcompare. Subclass one and implement its abstract methods to add a component; see Extending fastcompare for worked examples. This page is generated from the docstrings in server/plugins/fastcompare/algo/algorithm_base.py.

Algorithms

plugins.fastcompare.algo.algorithm_base.AlgorithmBase

Bases: ABC

Base class for recommendation algorithms.

Subclasses are discovered automatically and offered in the fastcompare study-creation UI. Implementations must accept **kwargs in __init__.

fit() abstractmethod

Perform the initial training of the algorithm on the dataset.

The data is supplied when the algorithm is constructed rather than passed to fit, because some models have structure that depends on the underlying data (e.g. string lookups in TensorFlow). It therefore makes sense to expect that fitting is done on the same data the model was constructed with.

predict(selected_items, filter_out_items, k) abstractmethod

Recommend for a new, previously unseen user.

The user's history is simulated from selected_items. Returns a list of item indices for the k recommended items. None of the filter_out_items may appear in the result.

name() abstractmethod classmethod

Return the algorithm's display name. Names must be unique.

parameters() abstractmethod classmethod

Return the list of Parameter objects for this algorithm.

These are set by the researcher when creating the user study and are passed to the algorithm's constructor as keyword arguments.

load(instance_cache_path, class_cache_path, semi_local_cache_path)

Load internal state (default implementation uses pickle).

More complex models may need to override this (e.g. TensorFlow models).

Parameters:

Name	Type	Description	Default
instance_cache_path	str	Cache for data specific to this instance (i.e. depends on its parameters).	required
class_cache_path	str	A single cache shared across all parameter combinations (useful for static data).	required
semi_local_cache_path	str	A per-dataset cache for the whole class (other config parameters are ignored).	required

When in doubt, just use instance_cache_path and ignore the others.

save(instance_cache_path, class_cache_path, semi_local_cache_path)

Save internal state (default implementation uses pickle).

More complex models may need to override this. See load for the meaning of the cache-path arguments.

Preference elicitation

plugins.fastcompare.algo.algorithm_base.PreferenceElicitationBase

Bases: ABC

Base class for preference-elicitation methods.

Implementations must accept **kwargs in __init__.

fit() abstractmethod

Perform any dataset-dependent initialization.

Most preference-elicitation methods do not really need this.

get_initial_data(movie_indices_to_ignore=[]) abstractmethod

Return the initial set of items shown to the user to select from.

name() abstractmethod classmethod

Return the method's display name.

Names must be unique; the name is shown to researchers when creating a user study from the fastcompare plugin.

parameters() abstractmethod classmethod

Return the list of Parameter objects for this method.

These are set by the researcher when creating the user study and are passed to the preference-elicitation constructor as keyword arguments.

load(instance_cache_path, class_cache_path, semi_local_cache_path)

Load internal state (default implementation uses pickle).

See AlgorithmBase.load for the meaning of the cache-path arguments.

save(instance_cache_path, class_cache_path, semi_local_cache_path)

Save internal state (default implementation uses pickle).

See AlgorithmBase.load for the meaning of the cache-path arguments.

Data loaders

plugins.fastcompare.algo.algorithm_base.DataLoaderBase

Bases: ABC

Base class for dataset/domain loaders.

Implementations must accept **kwargs in __init__. Conventions:

• ratings_df must contain user and item columns.
• items_df must contain a title column.
• An item id may be non-zero-based, whereas an item index is strictly zero-based. Use get_item_index / get_item_id to convert between them.

ratings_df abstractmethod property

Dataframe of interactions/ratings.

Should contain user, item, and item_id (zero-based) columns. Note that interactions are treated as implicit feedback.

items_df abstractmethod property

Dataframe with item metadata. Should have item_id and title columns.

items_df_indexed abstractmethod property

Same as items_df but indexed by item.

distance_matrix abstractmethod property

Pairwise item distance matrix (used e.g. by the ILD metric).

rating_matrix abstractmethod property

User-by-item rating matrix.

load_data() abstractmethod

Load the data. Long-running work belongs here.

get_item_id_image_url(item_id) abstractmethod

Return the image URL for the given item id.

Either a remote URL (http://…, which can be slow) or a local one produced via Flask's url_for (if you place images under server/static/datasets/<x>/img/*.jpg).

get_item_index_image_url(item_index) abstractmethod

Same as get_item_id_image_url, but for an item index instead of an id.

get_item_index(item_id) abstractmethod

Map an item id to its (zero-based) item index.

get_item_id(item_index) abstractmethod

Map an item index to its item id.

get_item_index_description(item_index) abstractmethod

Return a textual description for the item index (e.g. title, or title + genres).

get_item_id_description(item_id) abstractmethod

Return a textual description for the given item id.

get_item_index_categories(item_index) abstractmethod

Return the list of categories for the given item index.

get_all_categories() abstractmethod

Return all categories available in the dataset.

name() abstractmethod classmethod

Return the data loader's display name.

Names must be unique; the name is shown to researchers when creating a user study from the fastcompare plugin.

parameters() abstractmethod classmethod

Return the list of Parameter objects for this data loader.

These are set by the researcher when creating the user study and are passed to the data loader's constructor as keyword arguments.

Note: currently no data loaders take any parameters. If this changes, the semi-local cache path may need to include the parameter values.

load(instance_cache_path, class_cache_path, semi_local_cache_path)

Load internal state (default implementation uses pickle).

See AlgorithmBase.load for the meaning of the cache-path arguments.

save(instance_cache_path, class_cache_path, semi_local_cache_path)

Save internal state (default implementation uses pickle).

See AlgorithmBase.load for the meaning of the cache-path arguments.

Evaluation metrics

plugins.fastcompare.algo.algorithm_base.EvaluationMetricBase

Bases: ABC

Base class for evaluation metrics shown in the study Results view.

evaluate(shown_items, selected_items) abstractmethod

Compute the metric for one observation.

Takes shown_items (a list of item indices) and selected_items (a list of item indices) and returns a numeric evaluation result.

name() abstractmethod classmethod

Return a unique display name for the metric.

Parameters

plugins.fastcompare.algo.algorithm_base.Parameter

Bases: dict

A single configurable parameter surfaced in the study-creation UI.

Parameters:

Name	Type	Description	Default
param_name	str	Parameter name (also the keyword passed to the component constructor).	required
param_type	str	One of the ParameterType values.	required
param_default_value	Any	Default value shown in the UI.	required
help	str	Inline help text shown next to the field.	None
help_key	str	Key into the translations .json file, so that the help text is translatable (takes precedence over help when translations are available).	None

plugins.fastcompare.algo.algorithm_base.ParameterType

Types of hyperparameters / configurable parameters exposed by a component.

Used as the param_type of a Parameter. OPTIONS lets the user choose one out of several predefined options.