1AI::Categorizer(3) User Contributed Perl Documentation AI::Categorizer(3)
2
6 AI::Categorizer - Automatic Text Categorization
7
9 use AI::Categorizer;
10 my $c = new AI::Categorizer(...parameters...);
11 # Run a complete experiment - training on a corpus, testing on a test
13 # set, printing a summary of results to STDOUT
14 $c->run_experiment;
15 # Or, run the parts of $c->run_experiment separately
17 $c->scan_features;
18 $c->read_training_set;
19 $c->train;
20 $c->evaluate_test_set;
21 print $c->stats_table;
22 # After training, use the Learner for categorization
24 my $l = $c->learner;
25 while (...) {
26 my $d = ...create a document...
27 my $hypothesis = $l->categorize($d); # An AI::Categorizer::Hypothesis object
28 print "Assigned categories: ", join ', ', $hypothesis->categories, "\n";
29 print "Best category: ", $hypothesis->best_category, "\n";
30 }
31
33 "AI::Categorizer" is a framework for automatic text categorization. It
34 consists of a collection of Perl modules that implement common
35 categorization tasks, and a set of defined relationships among those
36 modules. The various details are flexible - for example, you can
37 choose what categorization algorithm to use, what features (words or
38 otherwise) of the documents should be used (or how to automatically
39 choose these features), what format the documents are in, and so on.
40 The basic process of using this module will typically involve obtaining
42 a collection of pre-categorized documents, creating a "knowledge set"
43 representation of those documents, training a categorizer on that
44 knowledge set, and saving the trained categorizer for later use. There
45 are several ways to carry out this process. The top-level
46 "AI::Categorizer" module provides an umbrella class for high-level
47 operations, or you may use the interfaces of the individual classes in
48 the framework.
49 A simple sample script that reads a training corpus, trains a
51 categorizer, and tests the categorizer on a test corpus, is distributed
52 as eg/demo.pl .
53 Disclaimer: the results of any of the machine learning algorithms are
55 far from infallible (close to fallible?). Categorization of documents
56 is often a difficult task even for humans well-trained in the
57 particular domain of knowledge, and there are many things a human would
58 consider that none of these algorithms consider. These are only
59 statistical tests - at best they are neat tricks or helpful assistants,
60 and at worst they are totally unreliable. If you plan to use this
61 module for anything really important, human supervision is essential,
62 both of the categorization process and the final results.
63 For the usage details, please see the documentation of each individual
65 module.
66
68 This section explains the major pieces of the "AI::Categorizer" object
69 framework. We give a conceptual overview, but don't get into any of
70 the details about interfaces or usage. See the documentation for the
71 individual classes for more details.
72 A diagram of the various classes in the framework can be seen in
74 "doc/classes-overview.png", and a more detailed view of the same thing
75 can be seen in "doc/classes.png".
76 Knowledge Sets
78 A "knowledge set" is defined as a collection of documents, together
79 with some information on the categories each document belongs to. Note
80 that this term is somewhat unique to this project - other sources may
81 call it a "training corpus", or "prior knowledge". A knowledge set
82 also contains some information on how documents will be parsed and how
83 their features (words) will be extracted and turned into meaningful
84 representations. In this sense, a knowledge set represents not only a
85 collection of data, but a particular view on that data.
86 A knowledge set is encapsulated by the "AI::Categorizer::KnowledgeSet"
88 class. Before you can start playing with categorizers, you will have
89 to start playing with knowledge sets, so that the categorizers have
90 some data to train on. See the documentation for the
91 "AI::Categorizer::KnowledgeSet" module for information on its
92 interface.
93 Feature selection
95 Deciding which features are the most important is a very large part of
97 the categorization task - you cannot simply consider all the words in
98 all the documents when training, and all the words in the document
99 being categorized. There are two main reasons for this - first, it
100 would mean that your training and categorizing processes would take
101 forever and use tons of memory, and second, the significant stuff of
102 the documents would get lost in the "noise" of the insignificant stuff.
103 The process of selecting the most important features in the training
105 set is called "feature selection". It is managed by the
106 "AI::Categorizer::KnowledgeSet" class, and you will find the details of
107 feature selection processes in that class's documentation.
108 Collections
110 Because documents may be stored in lots of different formats, a
111 "collection" class has been created as an abstraction of a stored set
112 of documents, together with a way to iterate through the set and return
113 Document objects. A knowledge set contains a single collection object.
114 A "Categorizer" doing a complete test run generally contains two
115 collections, one for training and one for testing. A "Learner" can
116 mass-categorize a collection.
117 The "AI::Categorizer::Collection" class and its subclasses instantiate
119 the idea of a collection in this sense.
120 Documents
122 Each document is represented by an "AI::Categorizer::Document" object,
123 or an object of one of its subclasses. Each document class contains
124 methods for turning a bunch of data into a Feature Vector. Each
125 document also has a method to report which categories it belongs to.
126 Categories
128 Each category is represented by an "AI::Categorizer::Category" object.
129 Its main purpose is to keep track of which documents belong to it,
130 though you can also examine statistical properties of an entire
131 category, such as obtaining a Feature Vector representing an
132 amalgamation of all the documents that belong to it.
133 Machine Learning Algorithms
135 There are lots of different ways to make the inductive leap from the
136 training documents to unseen documents. The Machine Learning community
137 has studied many algorithms for this purpose. To allow flexibility in
138 choosing and configuring categorization algorithms, each such algorithm
139 is a subclass of "AI::Categorizer::Learner". There are currently four
140 categorizers included in the distribution:
141 AI::Categorizer::Learner::NaiveBayes
143 A pure-perl implementation of a Naive Bayes classifier. No
144 dependencies on external modules or other resources. Naive Bayes
145 is usually very fast to train and fast to make categorization
146 decisions, but isn't always the most accurate categorizer.
147 AI::Categorizer::Learner::SVM
149 An interface to Corey Spencer's "Algorithm::SVM", which implements
150 a Support Vector Machine classifier. SVMs can take a while to
151 train (though in certain conditions there are optimizations to make
152 them quite fast), but are pretty quick to categorize. They often
153 have very good accuracy.
154 AI::Categorizer::Learner::DecisionTree
156 An interface to "AI::DecisionTree", which implements a Decision
157 Tree classifier. Decision Trees generally take longer to train
158 than Naive Bayes or SVM classifiers, but they are also quite fast
159 when categorizing. Decision Trees have the advantage that you can
160 scrutinize the structures of trained decision trees to see how
161 decisions are being made.
162 AI::Categorizer::Learner::Weka
164 An interface to version 2 of the Weka Knowledge Analysis system
165 that lets you use any of the machine learners it defines. This
166 gives you access to lots and lots of machine learning algorithms in
167 use by machine learning researches. The main drawback is that Weka
168 tends to be quite slow and use a lot of memory, and the current
169 interface between Weka and "AI::Categorizer" is a bit clumsy.
170 Other machine learning methods that may be implemented soonish include
172 Neural Networks, k-Nearest-Neighbor, and/or a mixture-of-experts
173 combiner for ensemble learning. No timetable for their creation has
174 yet been set.
175 Please see the documentation of these individual modules for more
177 details on their guts and quirks. See the "AI::Categorizer::Learner"
178 documentation for a description of the general categorizer interface.
179 If you wish to create your own classifier, you should inherit from
181 "AI::Categorizer::Learner" or "AI::Categorizer::Learner::Boolean",
182 which are abstract classes that manage some of the work for you.
183 Feature Vectors
185 Most categorization algorithms don't deal directly with documents'
186 data, they instead deal with a vector representation of a document's
187 features. The features may be any properties of the document that seem
188 helpful for determining its category, but they are usually some version
189 of the "most important" words in the document. A list of features and
190 their weights in each document is encapsulated by the
191 "AI::Categorizer::FeatureVector" class. You may think of this class as
192 roughly analogous to a Perl hash, where the keys are the names of
193 features and the values are their weights.
194 Hypotheses
196 The result of asking a categorizer to categorize a previously unseen
197 document is called a hypothesis, because it is some kind of
198 "statistical guess" of what categories this document should be assigned
199 to. Since you may be interested in any of several pieces of
200 information about the hypothesis (for instance, which categories were
201 assigned, which category was the single most likely category, the
202 scores assigned to each category, etc.), the hypothesis is returned as
203 an object of the "AI::Categorizer::Hypothesis" class, and you can use
204 its object methods to get information about the hypothesis. See its
205 class documentation for the details.
206 Experiments
208 The "AI::Categorizer::Experiment" class helps you organize the results
209 of categorization experiments. As you get lots of categorization
210 results (Hypotheses) back from the Learner, you can feed these results
211 to the Experiment class, along with the correct answers. When all
212 results have been collected, you can get a report on accuracy,
213 precision, recall, F1, and so on, with both micro-averaging and macro-
214 averaging over categories. We use the "Statistics::Contingency" module
215 from CPAN to manage the calculations. See the docs for
216 "AI::Categorizer::Experiment" for more details.
217
219 new()
220 Creates a new Categorizer object and returns it. Accepts lots of
221 parameters controlling behavior. In addition to the parameters
222 listed here, you may pass any parameter accepted by any class that
223 we create internally (the KnowledgeSet, Learner, Experiment, or
224 Collection classes), or any class that they create. This is
225 managed by the "Class::Container" module, so see its documentation
226 for the details of how this works.
227 The specific parameters accepted here are:
229 progress_file
231 A string that indicates a place where objects will be saved
232 during several of the methods of this class. The default value
233 is the string "save", which means files like
234 "save-01-knowledge_set" will get created. The exact names of
235 these files may change in future releases, since they're just
236 used internally to resume where we last left off.
237 verbose
239 If true, a few status messages will be printed during
240 execution.
241 training_set
243 Specifies the "path" parameter that will be fed to the
244 KnowledgeSet's scan_features() and read() methods during our
245 scan_features() and read_training_set() methods.
246 test_set
248 Specifies the "path" parameter that will be used when creating
249 a Collection during the evaluate_test_set() method.
250 data_root
252 A shortcut for setting the "training_set", "test_set", and
253 "category_file" parameters separately. Sets "training_set" to
254 "$data_root/training", "test_set" to "$data_root/test", and
255 "category_file" (used by some of the Collection classes) to
256 "$data_root/cats.txt".
257 learner()
259 Returns the Learner object associated with this Categorizer.
260 Before train(), the Learner will of course not be trained yet.
261 knowledge_set()
263 Returns the KnowledgeSet object associated with this Categorizer.
264 If read_training_set() has not yet been called, the KnowledgeSet
265 will not yet be populated with any training data.
266 run_experiment()
268 Runs a complete experiment on the training and testing data,
269 reporting the results on "STDOUT". Internally, this is just a
270 shortcut for calling the scan_features(), read_training_set(),
271 train(), and evaluate_test_set() methods, then printing the value
272 of the stats_table() method.
273 scan_features()
275 Scans the Collection specified in the "test_set" parameter to
276 determine the set of features (words) that will be considered when
277 training the Learner. Internally, this calls the scan_features()
278 method of the KnowledgeSet, then saves a list of the KnowledgeSet's
279 features for later use.
280 This step is not strictly necessary, but it can dramatically reduce
282 memory requirements if you scan for features before reading the
283 entire corpus into memory.
284 read_training_set()
286 Populates the KnowledgeSet with the data specified in the
287 "test_set" parameter. Internally, this calls the read() method of
288 the KnowledgeSet. Returns the KnowledgeSet. Also saves the
289 KnowledgeSet object for later use.
290 train()
292 Calls the Learner's train() method, passing it the KnowledgeSet
293 created during read_training_set(). Returns the Learner object.
294 Also saves the Learner object for later use.
295 evaluate_test_set()
297 Creates a Collection based on the value of the "test_set"
298 parameter, and calls the Learner's categorize_collection() method
299 using this Collection. Returns the resultant Experiment object.
300 Also saves the Experiment object for later use in the stats_table()
301 method.
302 stats_table()
304 Returns the value of the Experiment's (as created by
305 evaluate_test_set()) stats_table() method. This is a string that
306 shows various statistics about the
307 accuracy/precision/recall/F1/etc. of the assignments made during
308 testing.
309
311 This module is a revised and redesigned version of the previous
312 "AI::Categorize" module by the same author. Note the added 'r' in the
313 new name. The older module has a different interface, and no attempt
314 at backward compatibility has been made - that's why I changed the
315 name.
316 You can have both "AI::Categorize" and "AI::Categorizer" installed at
318 the same time on the same machine, if you want. They don't know about
319 each other or use conflicting namespaces.
320
322 Ken Williams <ken@mathforum.org>
323 Discussion about this module can be directed to the perl-AI list at
325 <perl-ai@perl.org>. For more info about the list, see
326 http://lists.perl.org/showlist.cgi?name=perl-ai
327
329 An excellent introduction to the academic field of Text Categorization
330 is Fabrizio Sebastiani's "Machine Learning in Automated Text
331 Categorization": ACM Computing Surveys, Vol. 34, No. 1, March 2002, pp.
332 1-47.
333
335 Copyright 2000-2003 Ken Williams. All rights reserved.
336 This distribution is free software; you can redistribute it and/or
338 modify it under the same terms as Perl itself. These terms apply to
339 every file in the distribution - if you have questions, please contact
340 the author.
341perl v5.36.0 2023-01-19 AI::Categorizer(3)