Documentation improved (using python docstring).

Tássia Camões Araújo
1 parent 7c99a2c6
Showing 12 changed files with 247 additions and 59 deletions Show diff stats
src/app_recommender.py
src/config.py
src/cross_validation.py
src/data.py
src/demo_rec.py
src/error.py
src/evaluation.py
src/generate_doc.sh
src/recommender.py
src/similarity_measure.py
src/strategy.py
src/user.py
 #!/usr/bin/python
  
-#  AppRecommender - A GNU/Linux application recommender
+#  AppRecommender - a GNU/Linux application recommender.
 #
 #  Copyright (C) 2010  Tassia Camoes <tassia@gmail.com>
 #
 #!/usr/bin/python
  
-#  AppRecommender - A GNU/Linux application recommender
+#  config - python module for configuration options.
 #
 #  Copyright (C) 2010  Tassia Camoes <tassia@gmail.com>
 #
@@ -144,6 +144,9 @@ class Config():
                 assert False, "unhandled option"
  
     def set_logger(self):
+        """
+        Configure application logger and log level.
+        """
         self.logger = getLogger('')  # root logger is used by default
         self.logger.setLevel(DEBUG)
  
 #!/usr/bin/python
  
-#  AppRecommender - A GNU/Linux application recommender
+#  CrossValidation - python module for classes and methods related to
+#                    recommenders evaluation.
 #
 #  Copyright (C) 2010  Tassia Camoes <tassia@gmail.com>
 #
@@ -47,6 +48,7 @@ if __name__ == &#39;__main__&#39;:
         metrics.append(Recall())
         validation = CrossValidation(0.3,10,rec,metrics)
         validation.run(user)
+        print validation
  
         end_time = datetime.datetime.now()
         logging.debug("Cross-validation completed at %s" % end_time)
 #!/usr/bin/python
  
-#  AppRecommender - A GNU/Linux application recommender
+#  data - python module for data sources classes and methods.
 #
 #  Copyright (C) 2010  Tassia Camoes <tassia@gmail.com>
 #
@@ -29,32 +29,50 @@ import hashlib
 from error import Error
  
 class Item:
-    """  """
+    """
+    Generic item definition.
+    """
  
 class Package(Item):
-    """  """
+    """
+    Definition of a GNU/Linux application as a recommender item.
+    """
     def __init__(self,package_name):
-        """  """
+        """
+        Set initial attributes.
+        """
         self.package_name  = package_name
  
-    def load_package_info(self):
-        """  """
-        print "debian pkg",self.id
-
 def normalize_tags(string):
     """
-    Normalize tag string so that it can be indexed and retrieved.
+    Substitute string characters : by _ and - by '.
+    Examples:
+        admin::package-management   ->   admin__package'management
+        implemented-in::c++         ->   implemented-in__c++
     """
     return string.replace(':','_').replace('-','\'')
  
 class Singleton(object):
+    """
+    Base class for inheritance of only-one-instance classes.
+    Singleton design pattern.
+    """
     def __new__(cls, *args, **kwargs):
+        """
+        Creates a new instance of the class only if none already exists.
+        """
         if '_inst' not in vars(cls):
             cls._inst = object.__new__(cls)
         return cls._inst
  
 class TagsXapianIndex(xapian.WritableDatabase,Singleton):
+    """
+    Data source for tags info defined as a singleton xapian database.
+    """
     def __init__(self,cfg):
+        """
+        Set initial attributes.
+        """
         self.path = os.path.expanduser(cfg.tags_index)
         self.db_path = os.path.expanduser(cfg.tags_db)
         self.debtags_db = debtags.DB()
@@ -67,6 +85,9 @@ class TagsXapianIndex(xapian.WritableDatabase,Singleton):
         self.load_index(cfg.reindex)
  
     def load_db(self):
+        """
+        Load debtags database from the source file.
+        """
         tag_filter = re.compile(r"^special::.+$|^.+::TODO$")
         try:
             db_file = open(self.db_path, "r")
 #!/usr/bin/python
  
-#  AppRecommender - A GNU/Linux application recommender
+#  DemoRecommender - demonstration of a GNU/Linux application recommender.
 #
 #  Copyright (C) 2010  Tassia Camoes <tassia@gmail.com>
 #
+#!/usr/bin/python
+
+#  error.py - python module for error definition.
+#
+#  Copyright (C) 2010  Tassia Camoes <tassia@gmail.com>
+#
+#  This program is free software: you can redistribute it and/or modify
+#  it under the terms of the GNU General Public License as published by
+#  the Free Software Foundation, either version 3 of the License, or
+#  (at your option) any later version.
+#
+#  This program is distributed in the hope that it will be useful,
+#  but WITHOUT ANY WARRANTY; without even the implied warranty of
+#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+#  GNU General Public License for more details.
+#
+#  You should have received a copy of the GNU General Public License
+#  along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
 class Error(Exception):
-    """Base class for exceptions."""
+    """
+    Base class for exceptions.
+    """
     pass
 #!/usr/bin/python
  
-#  AppRecommender - A GNU/Linux application recommender
+#  evaluation - python module for classes and methods related to recommenders
+#               evaluation.
 #
 #  Copyright (C) 2010  Tassia Camoes <tassia@gmail.com>
 #
@@ -25,30 +26,57 @@ from user import *
 from recommender import *
  
 class Metric:
-    """  """
+    """
+    Base class for metrics. Strategy design pattern.
+    """
+    pass
  
 class Precision(Metric):
-    """  """
+    """
+    Accuracy evaluation metric defined as the percentage of relevant itens
+    among the predicted ones.
+    """
     def __init__(self):
+        """
+        Set metric description.
+        """
         self.desc = " Precision "
  
     def run(self,evaluation):
+        """
+        Compute metric.
+        """
         return float(len(evaluation.predicted_real))/len(evaluation.predicted_relevant)
  
 class Recall(Metric):
-    """  """
+    """
+    Accuracy evaluation metric defined as the percentage of relevant itens
+    which were predicted as so.
+    """
     def __init__(self):
+        """
+        Set metric description.
+        """
         self.desc = "   Recall  "
  
     def run(self,evaluation):
+        """
+        Compute metric.
+        """
         return float(len(evaluation.predicted_real))/len(evaluation.real_relevant)
  
 class F1(Metric):
     """  """
     def __init__(self):
+        """
+        Set metric description.
+        """
         self.desc = "     F1    "
  
     def run(self,evaluation):
+        """
+        Compute metric.
+        """
         p = Precision().run(evaluation)
         r = Recall().run(evaluation)
         return float((2*p*r)/(p+r))
@@ -56,80 +84,110 @@ class F1(Metric):
 class MAE(Metric):
     """  """
     def __init__(self):
+        """
+        Set metric description.
+        """
         self.desc = "    MAE    "
  
     def run(self,evaluation):
-        print "run"
+        """
+        Compute metric.
+        """
+        print "---" #FIXME
  
 class MSE(Metric):
     """  """
     def __init__(self):
+        """
+        Set metric description.
+        """
         self.desc = "    MSE    "
  
     def run(self,evaluation):
-        print "run"
+        """
+        Compute metric.
+        """
+        print "---" #FIXME
  
 class Coverage(Metric):
     """  """
     def __init__(self):
+        """
+        Set metric description.
+        """
         self.desc = "  Coverage "
  
     def run(self,evaluation):
-        print "run"
+        """
+        Compute metric.
+        """
+        print "---" #FIXME
  
 class Evaluation:
-    """  """
+    """
+    Class designed to perform prediction evaluation, given data and metric.
+    """
     def __init__(self,predicted_result,real_result):
-        """  """
+        """
+        Set initial parameters.
+        """
         self.predicted_item_scores = predicted_result.item_score
         self.predicted_relevant = predicted_result.get_prediction()
         self.real_item_scores = real_result.item_score
         self.real_relevant = real_result.get_prediction()
         self.predicted_real = [v for v in self.predicted_relevant if v in
                                self.real_relevant]
-        print len(self.predicted_relevant)
-        print len(self.real_relevant)
-        print len(self.predicted_real)
+        #print len(self.predicted_relevant)
+        #print len(self.real_relevant)
+        #print len(self.predicted_real)
  
     def run(self,metric):
+        """
+        Perform the evaluation with the given metric.
+        """
         return metric.run(self)
  
 class CrossValidation:
     """
-    Cross-validation method
+    Class designed to perform cross-validation process.
     """
     def __init__(self,partition_proportion,rounds,rec,metrics_list):
         """
-        Set defaults: partition_size, rounds, recommender and metrics_list
+        Set initial parameters.
         """
         if partition_proportion<1 and partition_proportion>0:
             self.partition_proportion = partition_proportion
         else:
-            logging.critical("A proporcao de particao deve ser um avalor ente 0 e 1.")
+            logging.critical("Partition proportion must be a value in the
+                              interval [0,1].")
             raise Error
         self.rounds = rounds
         self.recommender = rec
         self.metrics_list = metrics_list
         self.cross_results = defaultdict(list)
  
-    def print_result(self):
-        print ""
+    def __str__(self):
+        """
+        String representation of the object.
+        """
+        str = "\n"
         metrics_desc = ""
         for metric in self.metrics_list:
             metrics_desc += "%s|" % (metric.desc)
-        print "| Round |%s" % metrics_desc
+        str += "| Round |%s\n" % metrics_desc
         for r in range(self.rounds):
             metrics_result = ""
             for metric in self.metrics_list:
                 metrics_result += ("    %.2f   |" %
                                    (self.cross_results[metric.desc][r]))
-            print "|   %d   |%s" % (r,metrics_result)
+            str += "|   %d   |%s\n" % (r,metrics_result)
         metrics_mean = ""
         for metric in self.metrics_list:
             mean = float(sum(self.cross_results[metric.desc]) /
                          len(self.cross_results[metric.desc]))
             metrics_mean += "    %.2f   |" % (mean)
-        print "|  Mean |%s" % (metrics_mean)
+        str += "|  Mean |%s\n" % (metrics_mean)
+        return str
  
     def run(self,user):
         """
@@ -144,7 +202,7 @@ class CrossValidation:
                 if len(cross_item_score)>0:
                     random_key = random.choice(cross_item_score.keys())
                 else:
-                    logging.critical("cross_item_score vazio")
+                    logging.critical("Empty cross_item_score.")
                     raise Error
                 round_partition[random_key] = cross_item_score.pop(random_key)
             round_user = User(cross_item_score)
@@ -157,5 +215,4 @@ class CrossValidation:
             while len(round_partition)>0:
                 item,score = round_partition.popitem()
                 cross_item_score[item] = score
-        self.print_result()
  
 #!/bin/bash
+#
+#  generate_doc.sh - shell script to generate documentation using doxygen.
+#
+#  Copyright (C) 2010  Tassia Camoes <tassia@gmail.com>
+#
+#  This program is free software: you can redistribute it and/or modify
+#  it under the terms of the GNU General Public License as published by
+#  the Free Software Foundation, either version 3 of the License, or
+#  (at your option) any later version.
+#
+#  This program is distributed in the hope that it will be useful,
+#  but WITHOUT ANY WARRANTY; without even the implied warranty of
+#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+#  GNU General Public License for more details.
+#
+#  You should have received a copy of the GNU General Public License
+#  along with this program.  If not, see <http://www.gnu.org/licenses/>.
  
+# Get project version from git repository
 TAG=$(git describe --tags --abbrev=0)
 sed -i "s/^PROJECT_NUMBER.*$/PROJECT_NUMBER\t\t= $TAG/" ../doc/doxy_config
 rm -Rf ../doc/html
 #!/usr/bin/python
  
-#  AppRecommender - A GNU/Linux application recommender
+#  recommender - python module for classes related to recommenders.
 #
 #  Copyright (C) 2010  Tassia Camoes <tassia@gmail.com>
 #
@@ -23,11 +23,20 @@ from strategy import *
 from error import Error
  
 class RecommendationResult:
+    """
+    Class designed to describe a recommendation result: items and scores.
+    """
     def __init__(self,item_score,size):
+        """
+        Set initial parameters.
+        """
         self.item_score = item_score
         self.size = size
  
     def __str__(self):
+        """
+        String representation of the object.
+        """
         result = self.get_prediction()
         str = "\n"
         for i in range(len(result)):
@@ -35,12 +44,20 @@ class RecommendationResult:
         return str
  
     def get_prediction(self):
+        """
+        Return prediction based on recommendation size (number of items).
+        """
         sorted_result = sorted(self.item_score.items(), key=itemgetter(1))
         return sorted_result[:self.size]
  
 class Recommender:
-    """  """
+    """
+    Class designed to play the role of recommender.
+    """
     def __init__(self,cfg):
+        """
+        Set initial parameters.
+        """
         try:
             strategy = "self."+cfg.strategy+"(cfg)"
             exec(strategy)
@@ -50,17 +67,28 @@ class Recommender:
             raise Error
  
     def ct(self,cfg):
+        """
+        Perform content-based recommendation using tags index as source data.
+        """
         self.items_repository = TagsXapianIndex(cfg)
         self.strategy = ContentBasedStrategy()
  
     def cta(self,cfg):
+        """
+        Perform content-based recommendation using apt-xapian-index as source
+        data.
+        """
         self.items_repository = xapian.Database(cfg.axi)
         self.strategy = AxiContentBasedStrategy()
  
     def set_strategy(self,strategy):
-        """  """
+        """
+        Set the recommendation strategy.
+        """
         self.strategy = strategy
  
     def get_recommendation(self,user):
-        """  """
+        """
+        Produces recommendation using previously loaded strategy.
+        """
         return self.strategy.run(self,user)
 #!/usr/bin/python
  
-#  AppRecommender - A GNU/Linux application recommender
+#  similarity-measure - python module for classes and methods related to
+#                       measuring similarity between two sets of data.
 #
 #  Copyright (C) 2010  Tassia Camoes <tassia@gmail.com>
 #
 #!/usr/bin/python
  
-#  AppRecommender - A GNU/Linux application recommender
+#  strategy - python module for classes and methods related to recommendation
+#             strategies.
 #
 #  Copyright (C) 2010  Tassia Camoes <tassia@gmail.com>
 #
@@ -26,40 +27,51 @@ class ReputationHeuristic:
     """
     Abstraction for diferent reputation heuristics.
     """
+    pass
  
 class BugsHeuristic(ReputationHeuristic):
     """
     Reputation heuristic based on quantity of open bugs.
     """
+    pass
  
 class RCBugsHeuristic(ReputationHeuristic):
     """
     Reputation heuristic based on quantity of RC bugs.
     """
+    pass
  
 class PopularityHeuristic(ReputationHeuristic):
     """
     Reputation heuristic based on popularity of packages.
     """
+    pass
  
  
 class PkgMatchDecider(xapian.MatchDecider):
     """
-    Extends xapian.MatchDecider to disconsider installed packages.
+    Extend xapian.MatchDecider to not consider installed packages.
     """
  
     def __init__(self, installed_pkgs):
+        """
+        Set initial parameters.
+        """
         xapian.MatchDecider.__init__(self)
         self.installed_pkgs = installed_pkgs
  
     def __call__(self, doc):
+        """
+        True if the package is not already installed.
+        """
         return doc.get_data() not in self.installed_pkgs
  
  
 class RecommendationStrategy:
     """
-    Abstraction for diferent recommendation strategy.
+    Base class for recommendation strategies.
     """
+    pass
  
 class ItemReputationStrategy(RecommendationStrategy):
     """
 #!/usr/bin/python
  
-#  AppRecommender - A GNU/Linux application recommender
+#  user - python module for classes and methods related to recommenders' users.
 #
 #  Copyright (C) 2010  Tassia Camoes <tassia@gmail.com>
 #
@@ -23,6 +23,9 @@ import logging
 import apt
  
 class FilterTag(xapian.ExpandDecider):
+    """
+    Extend xapian.ExpandDecider to consider only tag terms.
+    """
     def __call__(self, term):
         """
         Return true if the term is a tag, else false.
@@ -30,29 +33,28 @@ class FilterTag(xapian.ExpandDecider):
         return term[:2] == "XT"
  
 class User:
-    """  """
+    """
+    Define a user of a recommender.
+    """
     def __init__(self,item_score,user_id=0,demographic_profile=0):
-        """  """
+        """
+        Set initial parameters.
+        """
         self.id = user_id
         self.item_score = item_score
         self.pkg_profile = self.item_score.keys()
         self.demographic_profile = demographic_profile
  
     def items(self):
+        """
+        Return dictionary relating items and repective scores.
+        """
         return self.item_score.keys()
  
-    def maximal_pkg_profile(self):
-        cache = apt.Cache()
-        old_profile_size = len(self.pkg_profile)
-        for p in self.pkg_profile[:]:     #iterate list copy
-            pkg = cache[p]
-            if pkg.is_auto_installed:
-                self.pkg_profile.remove(p)
-        profile_size = len(self.pkg_profile)
-        logging.info("Reduced packages profile size from %d to %d." %
-                     (old_profile_size, profile_size))
-
     def axi_tag_profile(self,apt_xapian_index,profile_size):
+        """
+        Return most relevant tags for a list of packages based on axi.
+        """
         terms = []
         for item in self.pkg_profile:
             terms.append("XP"+item)
@@ -70,15 +72,38 @@ class User:
         return profile
  
     def txi_tag_profile(self,tags_xapian_index,profile_size):
+        """
+        Return most relevant tags for a list of packages based on tags index.
+        """
         return tags_xapian_index.relevant_tags_from_db(self.pkg_profile,
                                                        profile_size)
  
 class LocalSystem(User):
-    """  """
+    """
+    Extend the class User to consider the packages installed on the local
+    system as the set of selected itens.
+    """
     def __init__(self):
+        """
+        Set initial parameters.
+        """
         item_score = {}
         dpkg_output = commands.getoutput('/usr/bin/dpkg --get-selections')
         for line in dpkg_output.splitlines():
             pkg = line.split('\t')[0]
             item_score[pkg] = 1
         User.__init__(self,item_score)
+
+    def maximal_pkg_profile(self):
+        """
+        Return list of packages voluntarily installed.
+        """
+        cache = apt.Cache()
+        old_profile_size = len(self.pkg_profile)
+        for p in self.pkg_profile[:]:     #iterate list copy
+            pkg = cache[p]
+            if pkg.is_auto_installed:
+                self.pkg_profile.remove(p)
+        profile_size = len(self.pkg_profile)
+        logging.info("Reduced packages profile size from %d to %d." %
+                     (old_profile_size, profile_size))
1	1	#!/usr/bin/python
2	2
3		-# AppRecommender - A GNU/Linux application recommender
	3	+# AppRecommender - a GNU/Linux application recommender.
4	4	#
5	5	# Copyright (C) 2010 Tassia Camoes <tassia@gmail.com>
6	6	#
...	...
1	1	#!/usr/bin/python
2	2
3		-# AppRecommender - A GNU/Linux application recommender
	3	+# config - python module for configuration options.
4	4	#
5	5	# Copyright (C) 2010 Tassia Camoes <tassia@gmail.com>
6	6	#
...	...	@@ -144,6 +144,9 @@ class Config():
144	144	assert False, "unhandled option"
145	145
146	146	def set_logger(self):
	147	+ """
	148	+ Configure application logger and log level.
	149	+ """
147	150	self.logger = getLogger('') # root logger is used by default
148	151	self.logger.setLevel(DEBUG)
149	152
...	...
1	1	#!/usr/bin/python
2	2
3		-# AppRecommender - A GNU/Linux application recommender
	3	+# CrossValidation - python module for classes and methods related to
	4	+# recommenders evaluation.
4	5	#
5	6	# Copyright (C) 2010 Tassia Camoes <tassia@gmail.com>
6	7	#
...	...	@@ -47,6 +48,7 @@ if __name__ == '__main__':
47	48	metrics.append(Recall())
48	49	validation = CrossValidation(0.3,10,rec,metrics)
49	50	validation.run(user)
	51	+ print validation
50	52
51	53	end_time = datetime.datetime.now()
52	54	logging.debug("Cross-validation completed at %s" % end_time)
...	...
1	1	#!/usr/bin/python
2	2
3		-# AppRecommender - A GNU/Linux application recommender
	3	+# data - python module for data sources classes and methods.
4	4	#
5	5	# Copyright (C) 2010 Tassia Camoes <tassia@gmail.com>
6	6	#
...	...	@@ -29,32 +29,50 @@ import hashlib
29	29	from error import Error
30	30
31	31	class Item:
32		- """ """
	32	+ """
	33	+ Generic item definition.
	34	+ """
33	35
34	36	class Package(Item):
35		- """ """
	37	+ """
	38	+ Definition of a GNU/Linux application as a recommender item.
	39	+ """
36	40	def __init__(self,package_name):
37		- """ """
	41	+ """
	42	+ Set initial attributes.
	43	+ """
38	44	self.package_name = package_name
39	45
40		- def load_package_info(self):
41		- """ """
42		- print "debian pkg",self.id
43		-
44	46	def normalize_tags(string):
45	47	"""
46		- Normalize tag string so that it can be indexed and retrieved.
	48	+ Substitute string characters : by _ and - by '.
	49	+ Examples:
	50	+ admin::package-management -> admin__package'management
	51	+ implemented-in::c++ -> implemented-in__c++
47	52	"""
48	53	return string.replace(':','_').replace('-','\'')
49	54
50	55	class Singleton(object):
	56	+ """
	57	+ Base class for inheritance of only-one-instance classes.
	58	+ Singleton design pattern.
	59	+ """
51	60	def __new__(cls, args, *kwargs):
	61	+ """
	62	+ Creates a new instance of the class only if none already exists.
	63	+ """
52	64	if '_inst' not in vars(cls):
53	65	cls._inst = object.__new__(cls)
54	66	return cls._inst
55	67
56	68	class TagsXapianIndex(xapian.WritableDatabase,Singleton):
	69	+ """
	70	+ Data source for tags info defined as a singleton xapian database.
	71	+ """
57	72	def __init__(self,cfg):
	73	+ """
	74	+ Set initial attributes.
	75	+ """
58	76	self.path = os.path.expanduser(cfg.tags_index)
59	77	self.db_path = os.path.expanduser(cfg.tags_db)
60	78	self.debtags_db = debtags.DB()
...	...	@@ -67,6 +85,9 @@ class TagsXapianIndex(xapian.WritableDatabase,Singleton):
67	85	self.load_index(cfg.reindex)
68	86
69	87	def load_db(self):
	88	+ """
	89	+ Load debtags database from the source file.
	90	+ """
70	91	tag_filter = re.compile(r"^special::.+$\|^.+::TODO$")
71	92	try:
72	93	db_file = open(self.db_path, "r")
...	...
1	1	#!/usr/bin/python
2	2
3		-# AppRecommender - A GNU/Linux application recommender
	3	+# DemoRecommender - demonstration of a GNU/Linux application recommender.
4	4	#
5	5	# Copyright (C) 2010 Tassia Camoes <tassia@gmail.com>
6	6	#
...	...
	1	+#!/usr/bin/python
	2	+
	3	+# error.py - python module for error definition.
	4	+#
	5	+# Copyright (C) 2010 Tassia Camoes <tassia@gmail.com>
	6	+#
	7	+# This program is free software: you can redistribute it and/or modify
	8	+# it under the terms of the GNU General Public License as published by
	9	+# the Free Software Foundation, either version 3 of the License, or
	10	+# (at your option) any later version.
	11	+#
	12	+# This program is distributed in the hope that it will be useful,
	13	+# but WITHOUT ANY WARRANTY; without even the implied warranty of
	14	+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
	15	+# GNU General Public License for more details.
	16	+#
	17	+# You should have received a copy of the GNU General Public License
	18	+# along with this program. If not, see <http://www.gnu.org/licenses/>.
	19	+
1	20	class Error(Exception):
2		- """Base class for exceptions."""
	21	+ """
	22	+ Base class for exceptions.
	23	+ """
3	24	pass
...	...
1	1	#!/usr/bin/python
2	2
3		-# AppRecommender - A GNU/Linux application recommender
	3	+# evaluation - python module for classes and methods related to recommenders
	4	+# evaluation.
4	5	#
5	6	# Copyright (C) 2010 Tassia Camoes <tassia@gmail.com>
6	7	#
...	...	@@ -25,30 +26,57 @@ from user import *
25	26	from recommender import *
26	27
27	28	class Metric:
28		- """ """
	29	+ """
	30	+ Base class for metrics. Strategy design pattern.
	31	+ """
	32	+ pass
29	33
30	34	class Precision(Metric):
31		- """ """
	35	+ """
	36	+ Accuracy evaluation metric defined as the percentage of relevant itens
	37	+ among the predicted ones.
	38	+ """
32	39	def __init__(self):
	40	+ """
	41	+ Set metric description.
	42	+ """
33	43	self.desc = " Precision "
34	44
35	45	def run(self,evaluation):
	46	+ """
	47	+ Compute metric.
	48	+ """
36	49	return float(len(evaluation.predicted_real))/len(evaluation.predicted_relevant)
37	50
38	51	class Recall(Metric):
39		- """ """
	52	+ """
	53	+ Accuracy evaluation metric defined as the percentage of relevant itens
	54	+ which were predicted as so.
	55	+ """
40	56	def __init__(self):
	57	+ """
	58	+ Set metric description.
	59	+ """
41	60	self.desc = " Recall "
42	61
43	62	def run(self,evaluation):
	63	+ """
	64	+ Compute metric.
	65	+ """
44	66	return float(len(evaluation.predicted_real))/len(evaluation.real_relevant)
45	67
46	68	class F1(Metric):
47	69	""" """
48	70	def __init__(self):
	71	+ """
	72	+ Set metric description.
	73	+ """
49	74	self.desc = " F1 "
50	75
51	76	def run(self,evaluation):
	77	+ """
	78	+ Compute metric.
	79	+ """
52	80	p = Precision().run(evaluation)
53	81	r = Recall().run(evaluation)
54	82	return float((2pr)/(p+r))
...	...	@@ -56,80 +84,110 @@ class F1(Metric):
56	84	class MAE(Metric):
57	85	""" """
58	86	def __init__(self):
	87	+ """
	88	+ Set metric description.
	89	+ """
59	90	self.desc = " MAE "
60	91
61	92	def run(self,evaluation):
62		- print "run"
	93	+ """
	94	+ Compute metric.
	95	+ """
	96	+ print "---" #FIXME
63	97
64	98	class MSE(Metric):
65	99	""" """
66	100	def __init__(self):
	101	+ """
	102	+ Set metric description.
	103	+ """
67	104	self.desc = " MSE "
68	105
69	106	def run(self,evaluation):
70		- print "run"
	107	+ """
	108	+ Compute metric.
	109	+ """
	110	+ print "---" #FIXME
71	111
72	112	class Coverage(Metric):
73	113	""" """
74	114	def __init__(self):
	115	+ """
	116	+ Set metric description.
	117	+ """
75	118	self.desc = " Coverage "
76	119
77	120	def run(self,evaluation):
78		- print "run"
	121	+ """
	122	+ Compute metric.
	123	+ """
	124	+ print "---" #FIXME
79	125
80	126	class Evaluation:
81		- """ """
	127	+ """
	128	+ Class designed to perform prediction evaluation, given data and metric.
	129	+ """
82	130	def __init__(self,predicted_result,real_result):
83		- """ """
	131	+ """
	132	+ Set initial parameters.
	133	+ """
84	134	self.predicted_item_scores = predicted_result.item_score
85	135	self.predicted_relevant = predicted_result.get_prediction()
86	136	self.real_item_scores = real_result.item_score
87	137	self.real_relevant = real_result.get_prediction()
88	138	self.predicted_real = [v for v in self.predicted_relevant if v in
89	139	self.real_relevant]
90		- print len(self.predicted_relevant)
91		- print len(self.real_relevant)
92		- print len(self.predicted_real)
	140	+ #print len(self.predicted_relevant)
	141	+ #print len(self.real_relevant)
	142	+ #print len(self.predicted_real)
93	143
94	144	def run(self,metric):
	145	+ """
	146	+ Perform the evaluation with the given metric.
	147	+ """
95	148	return metric.run(self)
96	149
97	150	class CrossValidation:
98	151	"""
99		- Cross-validation method
	152	+ Class designed to perform cross-validation process.
100	153	"""
101	154	def __init__(self,partition_proportion,rounds,rec,metrics_list):
102	155	"""
103		- Set defaults: partition_size, rounds, recommender and metrics_list
	156	+ Set initial parameters.
104	157	"""
105	158	if partition_proportion<1 and partition_proportion>0:
106	159	self.partition_proportion = partition_proportion
107	160	else:
108		- logging.critical("A proporcao de particao deve ser um avalor ente 0 e 1.")
	161	+ logging.critical("Partition proportion must be a value in the
	162	+ interval [0,1].")
109	163	raise Error
110	164	self.rounds = rounds
111	165	self.recommender = rec
112	166	self.metrics_list = metrics_list
113	167	self.cross_results = defaultdict(list)
114	168
115		- def print_result(self):
116		- print ""
	169	+ def __str__(self):
	170	+ """
	171	+ String representation of the object.
	172	+ """
	173	+ str = "\n"
117	174	metrics_desc = ""
118	175	for metric in self.metrics_list:
119	176	metrics_desc += "%s\|" % (metric.desc)
120		- print "\| Round \|%s" % metrics_desc
	177	+ str += "\| Round \|%s\n" % metrics_desc
121	178	for r in range(self.rounds):
122	179	metrics_result = ""
123	180	for metric in self.metrics_list:
124	181	metrics_result += (" %.2f \|" %
125	182	(self.cross_results[metric.desc][r]))
126		- print "\| %d \|%s" % (r,metrics_result)
	183	+ str += "\| %d \|%s\n" % (r,metrics_result)
127	184	metrics_mean = ""
128	185	for metric in self.metrics_list:
129	186	mean = float(sum(self.cross_results[metric.desc]) /
130	187	len(self.cross_results[metric.desc]))
131	188	metrics_mean += " %.2f \|" % (mean)
132		- print "\| Mean \|%s" % (metrics_mean)
	189	+ str += "\| Mean \|%s\n" % (metrics_mean)
	190	+ return str
133	191
134	192	def run(self,user):
135	193	"""
...	...	@@ -144,7 +202,7 @@ class CrossValidation:
144	202	if len(cross_item_score)>0:
145	203	random_key = random.choice(cross_item_score.keys())
146	204	else:
147		- logging.critical("cross_item_score vazio")
	205	+ logging.critical("Empty cross_item_score.")
148	206	raise Error
149	207	round_partition[random_key] = cross_item_score.pop(random_key)
150	208	round_user = User(cross_item_score)
...	...	@@ -157,5 +215,4 @@ class CrossValidation:
157	215	while len(round_partition)>0:
158	216	item,score = round_partition.popitem()
159	217	cross_item_score[item] = score
160		- self.print_result()
161	218
...	...
1	1	#!/bin/bash
	2	+#
	3	+# generate_doc.sh - shell script to generate documentation using doxygen.
	4	+#
	5	+# Copyright (C) 2010 Tassia Camoes <tassia@gmail.com>
	6	+#
	7	+# This program is free software: you can redistribute it and/or modify
	8	+# it under the terms of the GNU General Public License as published by
	9	+# the Free Software Foundation, either version 3 of the License, or
	10	+# (at your option) any later version.
	11	+#
	12	+# This program is distributed in the hope that it will be useful,
	13	+# but WITHOUT ANY WARRANTY; without even the implied warranty of
	14	+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
	15	+# GNU General Public License for more details.
	16	+#
	17	+# You should have received a copy of the GNU General Public License
	18	+# along with this program. If not, see <http://www.gnu.org/licenses/>.
2	19
	20	+# Get project version from git repository
3	21	TAG=$(git describe --tags --abbrev=0)
4	22	sed -i "s/^PROJECT_NUMBER.*$/PROJECT_NUMBER\t\t= $TAG/" ../doc/doxy_config
5	23	rm -Rf ../doc/html
...	...
1	1	#!/usr/bin/python
2	2
3		-# AppRecommender - A GNU/Linux application recommender
	3	+# recommender - python module for classes related to recommenders.
4	4	#
5	5	# Copyright (C) 2010 Tassia Camoes <tassia@gmail.com>
6	6	#
...	...	@@ -23,11 +23,20 @@ from strategy import *
23	23	from error import Error
24	24
25	25	class RecommendationResult:
	26	+ """
	27	+ Class designed to describe a recommendation result: items and scores.
	28	+ """
26	29	def __init__(self,item_score,size):
	30	+ """
	31	+ Set initial parameters.
	32	+ """
27	33	self.item_score = item_score
28	34	self.size = size
29	35
30	36	def __str__(self):
	37	+ """
	38	+ String representation of the object.
	39	+ """
31	40	result = self.get_prediction()
32	41	str = "\n"
33	42	for i in range(len(result)):
...	...	@@ -35,12 +44,20 @@ class RecommendationResult:
35	44	return str
36	45
37	46	def get_prediction(self):
	47	+ """
	48	+ Return prediction based on recommendation size (number of items).
	49	+ """
38	50	sorted_result = sorted(self.item_score.items(), key=itemgetter(1))
39	51	return sorted_result[:self.size]
40	52
41	53	class Recommender:
42		- """ """
	54	+ """
	55	+ Class designed to play the role of recommender.
	56	+ """
43	57	def __init__(self,cfg):
	58	+ """
	59	+ Set initial parameters.
	60	+ """
44	61	try:
45	62	strategy = "self."+cfg.strategy+"(cfg)"
46	63	exec(strategy)
...	...	@@ -50,17 +67,28 @@ class Recommender:
50	67	raise Error
51	68
52	69	def ct(self,cfg):
	70	+ """
	71	+ Perform content-based recommendation using tags index as source data.
	72	+ """
53	73	self.items_repository = TagsXapianIndex(cfg)
54	74	self.strategy = ContentBasedStrategy()
55	75
56	76	def cta(self,cfg):
	77	+ """
	78	+ Perform content-based recommendation using apt-xapian-index as source
	79	+ data.
	80	+ """
57	81	self.items_repository = xapian.Database(cfg.axi)
58	82	self.strategy = AxiContentBasedStrategy()
59	83
60	84	def set_strategy(self,strategy):
61		- """ """
	85	+ """
	86	+ Set the recommendation strategy.
	87	+ """
62	88	self.strategy = strategy
63	89
64	90	def get_recommendation(self,user):
65		- """ """
	91	+ """
	92	+ Produces recommendation using previously loaded strategy.
	93	+ """
66	94	return self.strategy.run(self,user)
...	...
1	1	#!/usr/bin/python
2	2
3		-# AppRecommender - A GNU/Linux application recommender
	3	+# similarity-measure - python module for classes and methods related to
	4	+# measuring similarity between two sets of data.
4	5	#
5	6	# Copyright (C) 2010 Tassia Camoes <tassia@gmail.com>
6	7	#
...	...