The conceptnet module

The conceptnet module contains the Concept, Relation, Assertion, RawAssertion, Frame, SurfaceForm, and Frequency models, whose database structure appears in the following figure:

It also provides the non-database classes Proposition and Feature.

Concepts

class csc.conceptnet.models.Concept(*args, **kwargs)

Concepts are the nodes of ConceptNet. They are the things that people have common sense knowledge about.

Concepts are expressed in natural language with sets of related words and phrases: for example, “take a picture”, “taking pictures”, “to take pictures”, and “you take a picture” are various surface forms of the same Concept.

language

The Language that this concept is in.

text

The normalized text for this concept.

num_assertions

A cached value representing how many Assertion s this concept appears in.

words

A cached value for the number of words in the concept’s normalized form. This gives an estimate of the complexity of the concept.

classmethod get(text, language, auto_create=False)

Get the Concept represented by a given string of text.

If the Concept does not exist, this method will return None by default. However, if the parameter auto_create=True is given, then this will create the Concept (adding it to the database) instead.

You should not run the string through a normalizer, or use a string which came from Concept.text (which is equivalent). If you have a normalized string, you should use get_raw() instead.

classmethod get_raw(normalized_text, language, auto_create=False)

Get the Concept whose normalized form is the given string.

If the Concept does not exist, this method will raise a Concept.DoesNotExist exception. However, if the parameter auto_create=True is given, then this will create the Concept (adding it to the database) instead.

Normalized forms should not be assumed to be stable; they may change between releases.

get_assertions(useful_only=True)

Get all Assertions about this concept.

get_assertions_forward(useful_only=True)

Get all Assertions with this concept on the left.

get_assertions_reverse(useful_only=True)

Get all Assertions with this concept on the right.

some_surface()

Get an arbitrary SurfaceForm representing this concept.

Returns None if the concept has no surface form.

Relations

class csc.conceptnet.models.Relation(*args, **kwargs)

Relation(id, name, description)

ConceptNet has a closed class of Relations, expressing connections between Concepts. This is the current set of relations, according to what question they each answer:

IsA                   | What kind of thing is it?
HasA                  | What does it possess?
PartOf                | What is it part of?
UsedFor               | What do you use it for?
AtLocation            | Where would you find it?
CapableOf             | What can it do?
MadeOf                | What is it made of?
CreatedBy             | How do you bring it into existence?
HasSubevent           | What do you do to accomplish it?
HasFirstSubevent      | What do you do first to accomplish it?
HasLastSubevent       | What do you do last to accomplish it?
HasPrerequisite       | What do you need to do first?
MotivatedByGoal       | Why would you do it?
Causes                | What does it make happen?
Desires               | What does it want?
CausesDesire          | What does it make you want to do?
HasProperty           | What properties does it have?
ReceivesAction        | What can you do to it?
DefinedAs             | How do you define it?
SymbolOf              | What does it represent?
LocatedNear           | What is it typically near?
ObstructedBy          | What would prevent it from happening?
ConceptuallyRelatedTo | What is related to it in an unknown way?
InheritsFrom          | (not stored, but used in some applications)

text

A standardized string naming this relation.

Assertions

class csc.conceptnet.models.Assertion(*args, **kwargs)

Assertion(id, language_id, relation_id, concept1_id, concept2_id, score, frequency_id, best_surface1_id, best_surface2_id, best_raw_id, best_frame_id)

An Assertion is uniquely defined by the five properties (language, relation, concept1, concept2, frequency).

language

The Language that the assertion is expressed in.

relation

The Relation that connects the two concepts in this assertion.

concept1

The Concept that is the first argument of the relation.

concept2

The Concept that is the second argument of the relation.

frequency

A Frequency expressing how often the given concepts would be related by the given relation, ranging from “never” to “always”.

polarity

A coarse-grained version of the frequency. The polarity is +1 if the assertion makes a positive statement (such as “people want to be happy”) and -1 if it makes a negative statement (such as “people do not want to be shot”).

score

A cached value representing the reliability of this Assertion: the number of people who support it (including anyone who entered a Sentence that it represents), minus the number of people who oppose it. The score is determined from the voting.Vote objects that apply to this Assertion.

best_raw()

Get the highest scoring RawAssertion for this assertion.

set_rating(user, val, activity)

Set a user’s Vote on a certain object. If the user has previously voted on that object, it removes the old vote.

RawAssertions

class csc.conceptnet.models.RawAssertion(*args, **kwargs)

A RawAssertion represents the connection between an Assertion and natural language. Where an Assertion describes a Relation between two Concepts, a RawAssertion describes a sentence Frame that connects the SurfaceForms of those concepts.

A RawAssertion also represents how a particular Sentence can be interpreted to make an Assertion. surface1 and surface2 generally come from chunks of a sentence that someone entered into Open Mind.

sentence

The Sentence that was parsed to form this RawAssertion.

assertion

The Assertion that this RawAssertion describes.

creator

The User responsible for this RawAssertion.

frame

The Frame, or the natural language template whose slots are filled in by this RawAssertion.

surface1

The SurfaceForm of the phrase (concept) that fills the first slot of the frame.

surface2

The SurfaceForm of the phrase (concept) that fills the second slot of the frame.

language

The Language that this RawAssertion is in.

score

A cached value representing the reliability of this RawAssertion: the number of people who support it (including the person who originally entered it), minus the number of people who oppose it. The score is determined from the voting.Vote objects that apply to this RawAssertion.

nl_repr(wrap_text=<function <lambda> at 0x1d2f6e0>)

Reconstruct the natural language representation. The text concepts are passed to the wrap_text function to allow a view to wrap them in a link (or do any other transformation.) The prototype for wrap_text is wrap_text(assertion, text), where assertion is this RawAssertion object and text is the natural-language text of the concept (text1 or text2).

set_rating(user, val, activity)

Set a user’s Vote on a certain object. If the user has previously voted on that object, it removes the old vote.

static make(user, frame, text1, text2, activity, vote=1)

Create a RawAssertion and a corresponding Assertion and Sentence from user input. Assign votes appropriately.

Requires the following arguments:

• user: The user to credit the new assertion to.
• frame: The Frame that is being filled in.
• text1: A string filling the first slot of the frame.
• text2: A string filling the second slot of the frame.
• activity: The event that produced this assertion.
• vote: The user’s vote on the assertion (often +1, but -1 can occur when the user is answering “no” to a question that has not been answered before).

surface(idx)

Get either surface1 or surface2, depending on the (1-based) idx.

Features

class csc.conceptnet.models.Feature(relation, concept)

Features are not models in the database, but they are useful ways to describe the knowledge contained in the edges of ConceptNet.

A Feature is the combination of a Concept and a Relation. The combination of a Concept and a Feature, then, gives a Proposition, a statement that can have a truth value; when given a truth value, this forms an Assertion.

As an example, the relation PartOf(cello, orchestra) breaks down into the concept cello and the feature PartOf(x, orchestra). It also breaks down into orchestra and PartOf(cello, x).

Features can be left features or right features, depending on whether they include the left or right concept (that is, the first or second argument) in the Assertion. The Feature class itself is an abstract class, which is realized in the classes LeftFeature and RightFeature.

Each Assertion can be described with its left concept (concept1) and its right feature, or its right concept (concept2) and its left feature.

The notation is based on putting the relation in a “bucket”. For example, PartOf(cello, orchestra) = cello\PartOf/orchestra. Breaking this apart gives left and right features:

cello: PartOf/orchestra (left concept and right feature)
orchestra: cello\PartOf (right concept and left feature)

Create a LeftFeature or RightFeature (depending on which class you instantiate), with the given relation and concept.

relation

The Relation contained in this feature.

concept

The Concept contained in this feature.

__init__(relation, concept)

Create a LeftFeature or RightFeature (depending on which class you instantiate), with the given relation and concept.

matching_assertions()

Get all Assertions that contain this feature.

matching_raw()

Get all RawAssertions that contain this feature.

fill_in(newconcept)

Fill in the blank of this feature with a Concept. The result is a Proposition.

static from_tuple(tup, lang=<Language: English (en)>, lemmatize=False)

Some systems such as AnalogySpace use a lower-level representation of features, representing them as a tuple of three strings: (left_or_right, relation, concept). This factory method takes in such a tuple and produces a proper Feature object.

nl_statement(gap='...')

Express this feature as a statement in natural language. The omitted concept is replaced by the value in gap.

frame

Get a good natural-language frame for expressing this feature. For backward compatibility, this is a property.

Propositions

class csc.conceptnet.models.Proposition(concept1, rel, concept2, lang)

A Proposition represents a statement that may or may not be true. It is like an Assertion without a truth value.

relation

The Relation expressed by this proposition.

concept1

The first argument of the relation.

concept2

The second argument of the relation.

lang

The language that this proposition is in.

Frames

class csc.conceptnet.models.Frame(*args, **kwargs)

A Frame is a natural-language template containing two slots, representing a way that a Relation could be expressed in language.

It can be used for pattern matching to create a RawAssertion, or to express an existing RawAssertion as a sentence.

fill_in(a, b)

Fill in the slots of this frame with the strings a and b.

Surface forms

class csc.conceptnet.models.SurfaceForm(*args, **kwargs)

A SurfaceForm is a string used to express a Concept in its natural language.

text

The text of this SurfaceForm.

language

The language that this SurfaceForm is in.

concept

The Concept that this SurfaceForm expresses.

residue

A string representation that indicates how to reconstruct this SurfaceForm from the normalized text of a Concept. Not yet standardized.

As an example, the surface form “playing a game” breaks down into the concept <en: play game> and the residue 1+ing a 2.