AI::Ca...edgeSet(3pm)

📦
version 0.09 · 2 versions
, in fedora 43

✨ NAME ✨

AI::Categorizer::KnowledgeSet — it encapsulates a whole set of documents, bestie. Like, the whole vibe of "here are my docs, here are my categories, and here's how they relate." 💖

This is the User Contributed Perl Documentation version, so you know it's giving community love.

🎀 SYNOPSIS 🎀

use AI::Categorizer::KnowledgeSet;
my $k = new AI::Categorizer::KnowledgeSet(...parameters...);
my $nb = new AI::Categorizer::Learner::NaiveBayes(...parameters...);
$nb->train(knowledge_set => $k);

okay so that's the whole plot: you make a KnowledgeSet, you make a Learner, you train it. iconic. 🔥

🌸 DESCRIPTION 🌸

The KnowledgeSet class is the one that provides an interface to a set of documents, a set of categories, and a mapping between the two. That's the whole job. Many parameters for controlling the processing of documents are managed by the KnowledgeSet class, so she's kind of the main character here. 💅

🦋 METHODS 🦋

💜 new()

Creates a new KnowledgeSet and returns it. Accepts the following parameters:

  • load — if a load parameter is present, the load() method will be invoked immediately. If the load parameter is a string, it will be passed as the path parameter to load(). If the load parameter is a hash reference, it will represent all the parameters to pass to load(). ✨
  • categories — an optional reference to an array of Category objects representing the complete set of categories in a KnowledgeSet. If used, the documents parameter should also be specified. (they're a package deal, fr fr)
  • documents — an optional reference to an array of Document objects representing the complete set of documents in a KnowledgeSet. If used, the categories parameter should also be specified. (see above, they match each other's energy 🫶)
  • features_kept — a number indicating how many features (words) should be considered when training the Learner or categorizing new documents. May be specified as a positive integer (e.g. 2000) indicating the absolute number of features to be kept, or as a decimal between 0 and 1 (e.g. 0.2) indicating the fraction of the total number of features to be kept, or as 0 to indicate that no feature selection should be done and that the entire set of features should be used. The default is 0.2.
  • feature_selection — a string indicating the type of feature selection that should be performed. Currently the only option is also the default option: document_frequency. (one option and it's the default, lowkey efficient)
  • tfidf_weighting — specifies how document word counts should be converted to vector values. Uses the three-character specification strings from Salton & Buckley's paper "Term-weighting approaches in automatic text retrieval". The three characters indicate the three factors that will be multiplied for each feature to find the final vector value for that feature. The default weighting is xxx.

The first character specifies the "term frequency" component, which can take the following values:

  • b — Binary weighting - 1 for terms present in a document, 0 for terms absent.
  • t — Raw term frequency - equal to the number of times a feature occurs in the document.
  • x — A synonym for t.
  • n — Normalized term frequency - 0.5 + 0.5 * t/max(t). This is the same as the t specification, but with term frequency normalized to lie between 0.5 and 1.

The second character specifies the "collection frequency" component, which can take the following values:

  • f — Inverse document frequency - multiply term t's value by log(N/n), where N is the total number of documents in the collection, and n is the number of documents in which term t is found.
  • p — Probabilistic inverse document frequency - multiply term t's value by log((N-n)/n) (same variable meanings as above).
  • x — No change - multiply by 1.

The third character specifies the "normalization" component, which can take the following values:

  • c — Apply cosine normalization - multiply by 1/length(document_vector).
  • x — No change - multiply by 1.

The three components may alternatively be specified by the term_weighting, collection_weighting, and normalize_weighting parameters respectively. (same energy, three separate params, you pick your lane 🌈)

  • verbose — if set to a true value, some status/debugging information will be output on STDOUT. 🗣️

🍓 categories()

In a list context returns a list of all Category objects in this KnowledgeSet. In a scalar context returns the number of such objects. Context is everything, bestie.

🌈 documents()

In a list context returns a list of all Document objects in this KnowledgeSet. In a scalar context returns the number of such objects. Same deal, different noun.

🎀 document()

Given a document name, returns the Document object with that name, or undef if no such Document object exists in this KnowledgeSet. 💀 (if it's not there, it's just undef, no drama)

✨ features()

Returns a FeatureSet object which represents the features of all the documents in this KnowledgeSet.

💅 verbose()

Returns the verbose parameter of this KnowledgeSet, or sets it with an optional argument. Getter-slash-setter, she does both.

🌸 scan_stats()

Scans all the documents of a Collection and returns a hash reference containing several statistics about the Collection. (XXX need to describe stats) — yes, that note is literally in the original, we keep it, no cap.

🦋 scan_features()

This method scans through a Collection object and determines the "best" features (words) to use when loading the documents and training the Learner. This process is known as "feature selection", and it's a very important part of categorization. like, genuinely important.

The Collection object should be specified as a collection parameter, or by giving the arguments to pass to the Collection's new() method.

The process of feature selection is governed by the feature_selection and features_kept parameters given to the KnowledgeSet's new() method.

This method returns the features as a FeatureVector whose values are the "quality" of each feature, by whatever measure the feature_selection parameter specifies. Normally you won't need to use the return value, because this FeatureVector will become the use_features parameter of any Document objects created by this KnowledgeSet. 🙈

💖 save_features()

Given the name of a file, this method writes the features (as determined by the scan_features method) to the file. Saving your work? obsessed.

🧚 restore_features()

Given the name of a file written by save_features, loads the features from that file and passes them as the use_features parameter for any Document objects created in the future by this KnowledgeSet. round trip ✨

⭐ read()

Iterates through a Collection of documents and adds them to the KnowledgeSet. The Collection can be specified using a collection parameter - otherwise, specify the arguments to pass to the new() method of the Collection class.

👑 load()

This method can do feature selection and load a Collection in one step (though it currently uses two steps internally). Two steps on the inside, one step on the outside. main character energy.

🫶 add_document()

Given a Document object as an argument, this method will add it and any categories it belongs to to the KnowledgeSet. She comes with her whole friend group, naturally.

🍓 make_document()

This method will create a Document object with the given data and then call add_document() to add it to the KnowledgeSet. A categories parameter should specify an array reference containing a list of categories by name. These are the categories that the document belongs to. Any other parameters will be passed to the Document class's new() method.

💜 finish()

This method will be called prior to training the Learner. Its purpose is to perform any operations (such as feature vector weighting) that may require examination of the entire KnowledgeSet. It's the "look at the whole picture before we commit" moment. 🌸

🌈 weigh_features()

This method will be called during finish() to adjust the weights of the features according to the tfidf_weighting parameter.

✨ document_frequency()

Given a single feature (word) as an argument, this method will return the number of documents in the KnowledgeSet that contain that feature.

🎀 partition()

Divides the KnowledgeSet into several subsets. This may be useful for performing cross-validation. The relative sizes of the subsets should be passed as arguments. For example, to split the KnowledgeSet into four KnowledgeSets of equal size, pass the arguments .25, .25, .25 (the final size is 1 minus the sum of the other sizes). The partitions will be returned as a list.

ngl the "final size is 1 minus the sum" thing is the detail everyone forgets, so don't be that person 💅

🌟 AUTHOR 🌟

Ken Williams, ken@mathforum.org

Copyright 2000-2003 Ken Williams. All rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

🌈 SEE ALSO 🌈

okay that's the whole page, bestie — documented by the User Contributed Perl Documentation crew, running on perl v5.42.0, dated 2025-07-25. mwah 💋 go categorize something iconic ✨

📦 where this page comes from