WordNet::QueryData - direct perl interface to WordNet database
my $wn = WordNet::QueryData->new( noload => 1);
print "Synset: ", join(", ", $wn->querySense("cat#n#7", "syns")), "\n";
print "Hyponyms: ", join(", ", $wn->querySense("cat#n#1", "hypo")), "\n";
print "Parts of Speech: ", join(", ", $wn->querySense("run")), "\n";
print "Senses: ", join(", ", $wn->querySense("run#v")), "\n";
print "Forms: ", join(", ", $wn->validForms("lay down#v")), "\n";
print "Noun count: ", scalar($wn->listAllWords("noun")), "\n";
print "Antonyms: ", join(", ", $wn->queryWord("dark#n#1", "ants")), "\n";
WordNet::QueryData provides a direct interface to the WordNet database files. It
requires the WordNet package (http://www.cogsci.princeton.edu/~wn/). It allows
the user direct access to the full WordNet semantic lexicon. All parts of
speech are supported and access is generally very efficient because the index
and morphical exclusion tables are loaded at initialization. The module can
optionally be used to load the indexes into memory for extra-fast lookups.
To use QueryData, you must tell it where your WordNet database is. There are two
ways you can do this: 1) by setting the appropriate environment variables, or
2) by passing the location to QueryData when you invoke the "new"
QueryData knows about two environment variables, WNHOME and WNSEARCHDIR. If
WNSEARCHDIR is set, QueryData looks for WordNet data files there. Otherwise,
QueryData looks for WordNet data files in WNHOME/dict (WNHOME\dict on a PC).
If WNHOME is not set, it defaults to "/usr/local/WordNet-3.0" on
Unix and "C:\Program Files\WordNet\3.0" on a PC. Normally, all you
have to do is to set the WNHOME variable to the location where you unpacked
your WordNet distribution. The database files are normally unpacked to the
You can also pass the location of the database files directly to QueryData. To
do this, pass the location to "new":
my $wn = WordNet::QueryData->new("/usr/local/wordnet/dict");
You can instead call the constructor with a hash of params, as in:
my $wn = WordNet::QueryData->new(
dir => "/usr/local/wordnet/dict",
verbose => 0,
noload => 1
When calling "new" in this fashion, two additional arguments are
supported; "verbose" will output debugging information, and
"noload" will cause the object to *not* load the indexes at startup.
The "noload" option results in data being retrieved using a dictionary
lookup rather than caching the indexes in RAM. This method yields an immediate
startup time but *slightly* (though less than you might think) longer lookup
time. For the curious, here are some profile data for each method on a duo
core intel mac, averaged seconds over 10000 iterations:
Caching versus noload times in seconds
noload => 1 noload => 0
new() 0.00001 2.55
queryWord("descending") 0.0009 0.0001
querySense("sunset#n#1", "hype") 0.0007 0.0001
validForms ("lay down#2") 0.0004 0.0001
Obviously the new()
comparison is not very useful, because nothing is
happening with the constructor in the case of noload => 1. Similarly,
lookups with caching are basically just hash lookups, and therefore very fast.
The lookup times for noload => 1 illustrate the tradeoff between caching at
time and using dictionary lookups.
Because of the lookup speed increase when noload => 0, many users will find
it useful to set noload to 1 during development cycles, and to 0 when RAM is
less of a concern than speed. The bottom line is that noload => 1 saves you
over 2 seconds of startup time, and costs you about 0.0005 seconds per lookup.
There are two primary query functions, 'querySense' and 'queryWord'. querySense
accesses semantic (sense to sense) relations; queryWord accesses lexical (word
to word) relations. The majority of relations are semantic. Some relations,
including "also see", antonym, pertainym, "participle of
verb", and derived forms are lexical. See the following WordNet
documentation for additional information:
Both functions take as their first argument a query string that takes one of
(1) word (e.g. "dog")
(2) word#pos (e.g. "house#n")
(3) word#pos#sense (e.g. "ghostly#a#1")
Types (1) or (2) passed to querySense or queryWord will return a list of
possible query strings at the next level of specificity. When type (3) is
passed to querySense or queryWord, it requires a second argument, a relation.
Relations generally only work with one function or the other, though some
relations can be either semantic or lexical; hence they may work for both
functions. Below is a list of known relations, grouped according to the
function they're most likely to work with:
also - also see
ants - antonyms
deri - derived forms (nouns and verbs only)
part - participle of verb (adjectives only)
pert - pertainym (pertains to noun) (adjectives only)
vgrp - verb group (verbs only)
also - also see
glos - word definition
syns - synset words
hype - hypernyms
inst - instance of
hypes - hypernyms and "instance of"
hypo - hyponyms
hasi - has instance
hypos - hyponums and "has instance"
mmem - member meronyms
msub - substance meronyms
mprt - part meronyms
mero - all meronyms
hmem - member holonyms
hsub - substance holonyms
hprt - part holonyms
holo - all holonyms
attr - attributes (?)
sim - similar to (adjectives only)
enta - entailment (verbs only)
caus - cause (verbs only)
domn - domain - all
dmnc - domain - category
dmnu - domain - usage
dmnr - domain - region
domt - member of domain - all (nouns only)
dmtc - member of domain - category (nouns only)
dmtu - member of domain - usage (nouns only)
dmtr - member of domain - region (nouns only)
When called in this manner, querySense and queryWord will return a list of
related words/senses. Note that as of WordNet 2.1, many hypernyms have become
"instance of" and many hyponyms have become "has
Note that querySense and queryWord use type (3) query strings in different ways.
A type (3) string passed to querySense specifies a synset. A type (3) string
passed to queryWord specifies a specific sense of a specific word.
"validForms" accepts a type (1) or (2) query string. It returns a list
of all alternate forms (alternate spellings, conjugations, plural/singular
forms, etc.). The type (1) query returns alternates for all parts of speech
(noun, verb, adjective, adverb). WARNING: Only the first argument returned by
validForms is certain to be valid (i.e. recognized by WordNet). Remaining
arguments may not be valid.
"listAllWords" accepts a part of speech and returns the full list of
words in the WordNet database for that part of speech.
"level" accepts a type (3) query string and returns a distance (not
necessarily the shortest or longest) to the root in the hypernym directed
"offset" accepts a type (3) query string and returns the binary offset
of that sense's location in the corresponding data file.
"tagSenseCnt" accepts a type (2) query string and returns the
tagsense_cnt value for that lemma: "number of senses of lemma that are
ranked according to their frequency of occurrence in semantic concordance
"lexname" accepts a type (3) query string and returns the lexname of
the sense; see WordNet lexnames man page for more information.
"frequency" accepts a type (3) query string and returns the frequency
count of the sense from tagged text; see WordNet cntlist man page for more
See test.pl for additional example usage.
Requires access to WordNet database files (data.noun/noun.dat,
Copyright 2000-2005 Jason Rennie. All rights reserved.
This module is free software; you can redistribute it and/or modify it under the
same terms as Perl itself.