NAME SYNOPSIS use Text::StemTagPOS; use Data::Dump qw(dump); my $stemTagger = Text::StemTagPOS->new; my $text = 'The first sentence. Sentence number two.'; dump $stemTagger->getStemmedAndTaggedText ($text); DESCRIPTION "Text::StemTagPOS" uses the modules Lingua::Stem::Snowball and Lingua::EN::Tagger to do part-of-speech tagging and stemming of English text. It was developed to pre-process text for the module Text::Categorize::Textrank. Encoding of all text should be in Perl's internal format; see Encode for converting text from various encodes to a Perl string. CONSTRUCTOR "new" The method "new" creates an instance of the "Text::StemTagPOS" class with the following parameters: "isoLangCode" isoLangCode => 'en' "isoLangCode" is the ISO language code of the language that will be tagged and stemmed by the object. It must be 'en', which is the default; other languages may be added when POS taggers for them are added to CPAN. "endingSentenceTag" endingSentenceTag => 'PP' "endingSentenceTag" is the part-of-speech tag from Lingua::EN::Tagger that will be used to indicate the end of a sentence. The default is 'PP'. The value of "endingSentenceTag" must be a tag generated by the module Lingua::EN::Tagger; see method "getListOfPartOfSpeechTags" for all the possible tags; which are based on the Penn Treebank tagset. "listOfPOSTypesToKeep" and/or "listOfPOSTagsToKeep" listOfPOSTypesToKeep => [...], listOfPOSTagsToKeep => [...] The method "getTaggedTextToKeep" uses "listOfPOSTypesToKeep" and "listOfPOSTagsToKeep" to build the default list of the parts-of-speech to be retained when filtering previously tagged text. The default list is "[qw(TEXTRANK_WORDS)]", which is all the nouns and adjectives in the text, as used in the textrank algorithm. Permitted types for "getTaggedTextToKeep" are 'ALL', 'ADJECTIVES', 'ADVERBS', 'CONTENT_WORDS', 'NOUNS', 'PUNCTUATION', 'TEXTRANK_WORDS', and 'VERBS'. "listOfPOSTagsToKeep" provides finer control over the parts-of-speech to be retained. For a list of all the possible tags see method "getListOfPartOfSpeechTags". METHODS "getStemmedAndTaggedText" getStemmedAndTaggedText (@Text, $Text, \@Text) The method "getStemmedAndTaggedText" returns a hierarchy of array references containing the stemmed words, the original words, their part-of-speech tag, and their word position index within the original text. The hierarchy is of the form [ [ # sentence level: first sentence. [ # word level: first word. stemmed word, original word, part-of-speech tag, word index ] [ # word level: second word. stemmed word, original word, part-of-speech tag, word index ] ... ] [ # sentence level: second sentence. [ # word level: first word. stemmed word, original word, part-of-speech tag, word index ] [ # word level: second word. stemmed word, original word, part-of-speech tag, word index ] ... ] ] Its only parameters are any combination of strings of text as scalars, references to scalars, arrays of strings of text, or references to arrays of strings of text, etc... The following examples below show the various ways to call the method; note that the constants Text::StemTagPOS::WORD_STEMMED, Text::StemTagPOS::WORD_ORIGINAL, Text::StemTagPOS::WORD_POSTAG, and Text::StemTagPOS::WORD_INDEX are used to access the information about each word. use Text::StemTagPOS; use Data::Dump qw(dump); my $stemTagger = Text::StemTagPOS->new; my $text = 'The first sentence. Sentence number two.'; my $stemmedTaggedText = $stemTagger->getStemmedAndTaggedText ($text); dump $stemmedTaggedText; # $stemmedTaggedText will containing the following: # [ # [ # ["the", "The", "/DET", 0], # ["first", "first", "/JJ", 1], # ["sentenc", "sentence", "/NN", 2], # [".", ".", "/PP", 3], # ], # [ # ["sentenc", "Sentence", "/NN", 4], # ["number", "number", "/NN", 5], # ["two", "two", "/CD", 6], # [".", ".", "/PP", 7], # ], # ] my $word = $stemmedTaggedText->[0][0]; print 'WORD_STEMMED: ' . "'" . $word->[Text::StemTagPOS::WORD_STEMMED] . "'\n" . 'WORD_ORIGINAL: ' . "'" . $word->[Text::StemTagPOS::WORD_ORIGINAL] . "'\n" . 'WORD_POSTAG: ' . "'" . $word->[Text::StemTagPOS::WORD_POSTAG] . "'\n" . 'WORD_INDEX: ' . $word->[Text::StemTagPOS::WORD_INDEX] . "\n"; # WORD_STEMMED: 'the' # WORD_ORIGINAL: 'The' # WORD_POSTAG: '/DET' # WORD_INDEX: '0' The following example shows the various ways the text can be passed to the method: use Text::StemTagPOS; use Data::Dump qw(dump); my $stemTagger = Text::StemTagPOS->new; my $text = 'This is a sentence with seven words.'; dump $stemTagger->getStemmedAndTaggedText ($text, [$text, \$text], ($text, \$text)); "getTaggedTextToKeep" getTaggedTextToKeep (stemmedTaggedText => [...], listOfPOSTypesToKeep => [...], listOfPOSTagsToKeep => [...]); The method "getTaggedTextToKeep" returns all the array references of the words that have a part-of-speech tag that is of a type specified by "listOfPOSTypesToKeep" or "listOfPOSTagsToKeep". The word lists returned have the same hierarchical sentence structure used by "stemmedTaggedText". Note "listOfPOSTypesToKeep" and "listOfPOSTagsToKeep" are optional parameters, if neither is defined, then the values used when the object was instantiated are used. If one of them is defined, its values override the default values. "stemmedTaggedText" stemmedTaggedText => [...] "stemmedTaggedText" is the array reference returned by "getStemmedAndTaggedText" or a previous call to "getTaggedTextToKeep". "listOfPOSTypesToKeep" and/or "listOfPOSTagsToKeep" listOfPOSTypesToKeep => [...], listOfPOSTagsToKeep => [...] "listOfPOSTypesToKeep" and "listOfPOSTagsToKeep" define the list of parts-of-speech types to be retained when filtering previously tagged text. Permitted values for "listOfPOSTypesToKeep" are are 'ALL', 'ADJECTIVES', 'ADVERBS', 'CONTENT_WORDS', 'NOUNS', 'PUNCTUATION', 'TEXTRANK_WORDS', and 'VERBS'. For the possible value of "listOfPOSTagsToKeep" see the method "getListOfPartOfSpeechTags". Note "listOfPOSTypesToKeep" and "listOfPOSTagsToKeep" are optional parameters, if neither is defined, then the values used when the object was instantiated are used. If one of them is defined, its values override the default values. use Text::StemTagPOS; use Data::Dump qw(dump); my $stemTagger = Text::StemTagPOS->new; my $text = 'This is the first sentence. This is the last sentence.'; my $stemmedTaggedText = $stemTagger->getStemmedAndTaggedText ($text); dump $stemTagger->getTaggedTextToKeep ( stemmedTaggedText => $stemmedTaggedText); # only the nouns and adjetives are retained by default. # [ # [ # ["first", "first", "/JJ", 3], # ["sentenc", "sentence", "/NN", 4], # ], # [ # ["last", "last", "/JJ", 9], # ["sentenc", "sentence", "/NN", 10], # ], # ] "getWordsPhrasesInTaggedText" getWordsPhrasesInTaggedText (stemmedTaggedText => ..., listOfPhrasesToFind => [...], listOfPOSTypesToKeep => [...], listOfPOSTagsToKeep => [...]); The method "getWordsPhrasesInTaggedText" returns a reference to an array where each entry in the array corresponds to the word or phrase in "listOfPhrasesToFind". The value of each entry is a list of word indices where the words or phrases were found. Each list contains integer pairs of the form [first-word-index, last-word-index] where first-word-index is the index to the first word of the phrase and last-word-index the index of the last word. The values of the index are those assigned to the stemmed and tagged word in "stemmedTaggedText". [ [ # first phrase locations [first word index, last word index], [first word index, last word index], ...] ] [ # second phrase locations [first word index, last word index], [first word index, last word index], ...] ] ... ] "stemmedTaggedText" stemmedTaggedText => [...] "stemmedTaggedText" is the array reference returned by "getStemmedAndTaggedText" or "getTaggedTextToKeep". "listOfPhrasesToFind" listOfPhrasesToFind => [...] "listOfPhrasesToFind" is an array reference containing a list of strings of text that are either single words or phrases that are to be located in the text provided by "stemmedTaggedText". Before the words or phrases are located they are filtered using "listOfPOSTypesToKeep" or "listOfPOSTagsToKeep". "listOfPOSTypesToKeep" and/or "listOfPOSTagsToKeep" listOfPOSTypesToKeep => [...], listOfPOSTagsToKeep => [...] "listOfPOSTypesToKeep" and "listOfPOSTagsToKeep" defines the list of parts-of-speech types to be retained when filtering previously tagged text. Permitted values for "listOfPOSTypesToKeep" are are 'ALL', 'ADJECTIVES', 'ADVERBS', 'CONTENT_WORDS', 'NOUNS', 'PUNCTUATION', 'TEXTRANK_WORDS', and 'VERBS'. For the possible value of "listOfPOSTagsToKeep" see the method "getListOfPartOfSpeechTags". Note "listOfPOSTypesToKeep" and "listOfPOSTagsToKeep" are optional parameters, if neither is defined, then the values used when the object was instantiated are used. If one of them is defined, its values override the default values. The code below illustrates the output format: use Text::StemTagPOS; use Data::Dump qw(dump); my $stemTagger = Text::StemTagPOS->new; my $text = 'This is the first sentence. This is the last sentence.'; my $stemmedTaggedText = $stemTagger->getStemmedAndTaggedText ($text); dump $stemmedTaggedText; my $listOfWordsOrPhrasesToFind = ['first sentence','this is', 'third sentence', 'sentence']; my $phraseLocations = $stemTagger->getWordsPhrasesInTaggedText ( listOfPOSTypesToKeep => [qw(ALL)], stemmedTaggedText => $stemmedTaggedText, listOfWordsOrPhrasesToFind => $listOfWordsOrPhrasesToFind); dump $phraseLocations; # [ # [[3, 4]], # 'first sentence' # [[0, 1], [6, 7]], # 'this is': note period in text has index 5. # [], # 'third sentence' # [[4, 4], [10, 10]] # 'sentence' # ] "getListOfPartOfSpeechTags" The method "getListOfPartOfSpeechTags" takes no parameters. It returns an array reference where each item in the list is of the form "[part of speech tag, description, examples]". It is meant for getting the part-of-speech tags that can be used to populate "listOfPOSTagsToKeep". use Text::StemTagPOS; use Data::Dump qw(dump); my $stemTagger = Text::StemTagPOS->new; dump $stemTagger->getListOfPartOfSpeechTags; "getListOfStemmedWordsInText" The method "getListOfStemmedWordsInText" returns an array reference of the sorted stemmed words in the text given by "stemmedTaggedText". "stemmedTaggedText" stemmedTaggedText => [...] "stemmedTaggedText" is the array reference returned by "getStemmedAndTaggedText" or "getTaggedTextToKeep" of the text. use Text::StemTagPOS; use Data::Dump qw(dump); my $stemTagger = Text::StemTagPOS->new; my $text = 'The first sentence. Sentence number two.'; my $stemmedTaggedText = $stemTagger->getStemmedAndTaggedText ($text); dump $stemTagger->getStemmedAndTaggedText (stemmedTaggedText => $stemmedTaggedText); "getListOfStemmedWordsInAllDocuments" The method "getListOfStemmedWordsInAllDocuments" returns an array reference of the sorted stemmed words of the intersection of all the words in the documents given by "listOfStemmedTaggedText"; "listOfStemmedTaggedText" listOfStemmedTaggedText => [...] "listOfStemmedTaggedText" is a list of document references returned by "getStemmedAndTaggedText" or "getTaggedTextToKeep". INSTALLATION To install the module run the following commands: perl Makefile.PL make make test make install If you are on a windows box you should use 'nmake' rather than 'make'. AUTHOR Jeff Kubina COPYRIGHT Copyright (c) 2009 Jeff Kubina. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The full text of the license can be found in the LICENSE file included with this module. KEYWORDS natural language processing, NLP, part of speech tagging, POS, stemming SEE ALSO Encode, perlunicode, Lingua::Stem::Snowball, Lingua::EN::Tagger, Text::Iconv, Text::Categorize::Textrank, utf8