Welcome to watsongraph’s documentation!

Contents:

class conceptmodel.ConceptModel(list_of_concepts=None)

The ConceptModel object is at the core of what this library does.

Each concept in the ConceptModel is mapped to a corresponding unique Wikipedia page. These concepts are connected to one another in turn by relevance edges of a 0-to-1 scaled strength. This ConceptModel can then be associated with any number of applications. Basic bindings are provided, in particular, for a recommendation service using library-provided Item and User classes.

__init__(list_of_concepts=None)

Initializes a ConceptModel around a list of concepts.

Parameters:list_of_concepts – A list of concept labels (eg. [‘Microsoft’, ‘IBM’] or [‘Apple Inc.’]) to initialize the model around.
abridge(concept, level=0, limit=50)

Performs the inverse operation of augment by removing the expansion of the given concept from the graph. This method is an externally-facing wrapper for the internal abridge_by_node() method: the difference is that this method maps a concept while that method maps a node.

Parameters:
  • concept – The concept to be expanded. Note that this concept need not already be present in the graph.
  • level – The limit placed on the depth of the graph. A limit of 0 is highest, corresponding with the most popular articles; a limit of 5 is the broadest and graphs to the widest cachet of articles. This parameter is a parameter that is passed directly to the IBM Watson API call.
  • limit – a cutoff placed on the number of related concepts to be returned. This parameter is passed directly to the IBM Watson API call.
add(concept)

Simple adder method.

Parameters:concept – Concept to be added to the model.
add_edge(source_concept, target_concept, prune=False)

Wrapper for add_edges() for the single-concept case, so that you don’t have to call a list explicitly.

Parameters:
  • source_concept – The source concept edges are being added from.
  • target_concept – The target concept an edge is being added to.
  • prune – Watson returns correlations for edges which it does not know enough about as 0.5, a lack of extensibility which can cause sizable issues: for example you might have both (0.5, IBM, Apple Inc.) and (0.5, IBM, Apple). We as humans know that these are totally not equal comparisons, but the system does not! When this parameter is set to True (it is set to False by default) only edges with a correlation higher than 0.5 are added.
add_edges(source_concept, list_of_target_concepts, prune=False)

Given a source concept and a list of target concepts, creates relevance edges between the source and the targets and adds them to the graph.

Parameters:
  • source_concept – The source concept edges are being added from.
  • list_of_target_concepts – The target concepts edges are being added to.
  • prune – Watson returns correlations for edges which it does not know enough about as 0.5, a lack of extensibility which can cause sizable issues: for example you might have both (0.5, IBM, Apple Inc.) and (0.5, IBM, Apple). We as humans know that these are totally not equal comparisons, but the system does not! When this parameter is set to True (it is set to False by default) only edges with a correlation higher than 0.5 are added.
augment(concept, level=0, limit=50)

Augments the ConceptModel by assigning the given node to a concept and adding newly discovered nodes to the resultant graph. This method is an externally-facing wrapper for the internal augment_by_node() method: the difference is that this method maps a concept while that method maps a node.

Parameters:
  • concept – The concept to be expanded. Note that this concept need not already be present in the graph.
  • level – The limit placed on the depth of the graph. A limit of 0 is the highest, corresponding with the most popular articles; a limit of 5 is the broadest.
  • limit – a cutoff placed on the number of related concepts to be returned. This parameter is passed directly to the IBM Watson API call.
concepts()
Returns:Returns a sorted list of all concepts in the ConceptModel.
concepts_by_property(prop)
Parameters:prop – The property to sort the returned output by.
Returns:Returns a list of (prop, concept) tuples sorted by prop. Note that this method will fail if this property is not initialized for all concepts.
concepts_by_view_count()

Wrapper for concepts_by_property() for the view_count case.

Returns:Returns a list of (view_count, concept) tuples sorted by view_count.
copy()

Returns a deep copy of itself. Used by User.express_interest() to merge Item and User concept models without distorting the Item model.

Returns:A deep copy of the current ConceptModel.
edges()
Returns:Returns a list of all (concept, other concept, strength) tuples in the ConceptModel.
expand(level=0, limit=50, n=1)

Expands a graph by augmenting concepts with only one (or no) edge. Warning: for sufficiently large graphs this is a slow operation! See also the expand() method for a less focused version of this operation.

Parameters:
  • level – The limit placed on the depth of the graph. A limit of 0 is highest, corresponding with the most popular articles; a limit of 5 is the broadest and graphs to the widest cachet of articles. This parameter is a parameter that is passed directly to the IBM Watson API call.
  • limit – a cutoff placed on the number of related concepts to be returned. This parameter is passed directly to the IBM Watson API call.
  • n – The cutoff for the number of neighbors a node can have.
explode(level=0, limit=50)

Explodes a graph by augmenting every concept already in it. Warning: for sufficiently large graphs this is a very slow operation! See also the expand() method for a more focused version of this operation.

Parameters:
  • level – The limit placed on the depth of the graph. A limit of 0 is highest, corresponding with the most popular articles; a limit of 5 is the broadest and graphs to the widest cachet of articles. This parameter is a parameter that is passed directly to the IBM Watson API call.
  • limit – a cutoff placed on the number of related concepts to be returned. This parameter is passed directly to the IBM Watson API call.
explode_edges(prune=False)

Calls add_edges() on everything in the model, all at once. Like explode() but for concept edges!

Parameters:prune – Watson returns correlations for edges which it does not know enough about as 0.5, a lack of extensibility which can cause sizable issues: for example you might have both (0.5, IBM, Apple Inc.) and (0.5, IBM, Apple). We as humans know that these are totally not equal comparisons, but the system does not! When this parameter is set to True (it is set to False by default) only edges with a correlation higher than 0.5 are added.
get_view_count(concept)

Returns the view_count of a concept in the ConceptModel.

Parameters:concept – The concept supposedly in the ConceptModel.
Returns:The view_count int parameter of the concept, if it is found. Throws an error if it is not.
load_from_json(data_repr)

Generates a ConceptModel out of a JSON representation. Counter-operation to to_dict().

Parameters:data_repr – The dictionary being passed to the method.
Returns:The generated ConceptModel.
map_property(prop, func)

Maps the param property of all of the concepts in the ConceptModel object by way of the user-provided func.

Parameters:
  • prop – The parameter being given.
  • func – The function that is called on the concept in order to determine the value of prop.
merge_with(mixin_concept_model)

Merges the given graph into the current one. The nx.compose method used here compares the hashes of the Concept objects being merged, and hashes are overwritten to map to labels. e.g. A = Concept(‘IBM’) and B = Concept(‘IBM’) have the same __hash__(), even though the objects are different, so they will merge into one when composed.

Parameters:mixin_concept_model – The ConceptModel object that is being folded into the current object.
neighborhood(concept)
Parameters:concept – The concept that is the focus of this operation.
Returns:Returns the “neighborhood” of a concept: a list of (correlation, concept) tuples pointing to/from it, plus itself. The neighborhood of the concept, a list of (concept, concept, relevance_edge) tuples much like the ones returned by edges() that contains every edge drawn from the chosen concept to any other in the graph. A concept is considered to be in a neighborhood with itself, with an auto-correlation of 1, so at a minimum expect to get back (lonely_concept, lonely_concept, 1).
remove(concept)

Removes the given concept from the ConceptModel.

Parameters:concept – The concept being removed from the model.
set_property(concept, param, value)

Sets the param property of concept to value.

Parameters:
  • concept – Concept being given a parameter.
  • param – The parameter being given.
  • value – The value the parameter being given takes on.
set_view_counts()

Initializes the view_count property for all of the concepts in the ConceptModel.

to_json()

Returns the JSON representation of a ConceptModel. Counter-operation to load_from_dict().

Parameters:self – A ConceptModel.
Returns:The nx dictionary representation of the ConceptModel.
class item.Item(name='', description='')

The Item object is a generic container for the objects that the application is trying to recommend to its users.

__init__(name='', description='')

Loads an Item object from its description and an associated name.

Parameters:
  • name – The Item’s name.
  • description – A textual description of what the Item is about or describes. This is mined at initialization for the concepts which are associated with this Item’s ConceptModel().
concepts()
Returns:The concepts in the Item model.
load(filename='items.json')

Loads the Item from a JSON representation.

Parameters:filename – The filename for the items storage file; items.json is the default.
load_from_json(data)

Loads an Item from its JSON serialization. Counter-operation to to_json().

Parameters:data – The JSON data being loaded into an Item object.
relevancies()
Returns:Sorted (relevance, concept) pairs associated with the Item.
save(filename='items.json')

Saves the Item to a JSON representation.

Parameters:filename – The filename for the items storage file; items.json is the default.
to_json()

Returns a JSON of the Item object suitable for storage. Counter-operation to load_from_json().

Returns:A JSON serialization of the Item object which is suitable for storage.

Indices and tables