Merge pull request #24 from zStupan/docs

More docs updates

README.md

@@ -28,12 +28,12 @@ The current version includes (but is not limited to) the following functions:
 
 ## Installation
 
-### pip3
+### pip
 
-Install NiaARM with pip3:
+Install NiaARM with pip:
 
 ```sh
-pip3 install niaarm
+pip install niaarm
 ```
 
 ## Usage
@@ -75,6 +75,10 @@ For a full list of examples see the [examples folder](examples/).
 
 ### Command line interface
 
+We provide a simple command line interface, which allows you to easily
+mine association rules on any input dataset, output them to a csv file and/or perform
+a simple statistical analysis on them.
+
 ```
 niaarm -h
 usage: niaarm [-h] -i INPUT_FILE [-o OUTPUT_FILE] -a ALGORITHM [-s SEED]

docs/api/dataset.rst

@@ -3,3 +3,4 @@ Dataset
 
 .. automodule:: niaarm.dataset
     :members:
+    :show-inheritance:

docs/api/feature.rst

@@ -2,4 +2,5 @@ Feature
 =======
 
 .. automodule:: niaarm.feature
-    :members:
+    :members:
+    :show-inheritance:

docs/api/rule.rst

@@ -2,4 +2,5 @@ Rule
 ====
 
 .. automodule:: niaarm.rule
-    :members:
+    :members:
+    :show-inheritance:

docs/api/stats.rst

@@ -3,3 +3,4 @@ Stats
 
 .. automodule:: niaarm.stats
     :members:
+    :show-inheritance:

docs/cli.rst

@@ -5,9 +5,15 @@ We provide a simple command line interface, which allows you to easily
 mine association rules on any input dataset, output them to a csv file and/or perform
 a simple statistical analysis on them.
 
+Usage
+-----
+
+.. code-block:: shell
+
+    niaarm -h  # or python -m niaarm -h
+
 .. code-block:: text
 
-    niaarm -h
     usage: niaarm [-h] -i INPUT_FILE [-o OUTPUT_FILE] -a ALGORITHM [-s SEED]
                   [--max-evals MAX_EVALS] [--max-iters MAX_ITERS] [--alpha ALPHA]
                   [--beta BETA] [--gamma GAMMA] [--delta DELTA] [--log]
@@ -22,16 +28,84 @@ a simple statistical analysis on them.
       -o OUTPUT_FILE, --output-file OUTPUT_FILE
                             Output file for mined rules
       -a ALGORITHM, --algorithm ALGORITHM
-                            Algorithm to use (niapy class name, e. g.
+                            Algorithm to use (niapy class name, e.g.
                             DifferentialEvolution)
       -s SEED, --seed SEED  Seed for the algorithm's random number generator
       --max-evals MAX_EVALS
                             Maximum number of fitness function evaluations
       --max-iters MAX_ITERS
                             Maximum number of iterations
-      --alpha ALPHA         Alpha parameter. Default 0
-      --beta BETA           Beta parameter. Default 0
-      --gamma GAMMA         Gamma parameter. Default 0
-      --delta DELTA         Delta parameter. Default 0
+      --alpha ALPHA         Support weight. Default: 0. Note: at least one of
+                            alpha, beta, gamma, delta must be set
+      --beta BETA           Confidence weight. Default: 0
+      --gamma GAMMA         Shrinkage weight. Default: 0
+      --delta DELTA         Coverage weight. Default: 0
       --log                 Enable logging of fitness improvements
       --show-stats          Display stats about mined rules
+
+Output rules to csv
+~~~~~~~~~~~~~~~~~~~
+
+Mine Association rules on the Abalone dataset (`available here <https://archive.ics.uci.edu/ml/datasets/Abalone>`_)
+and output them to a csv file. We'll run Differential evolution for 30 iterations, logging fitness improvements.
+We set the support and confidence weights (alpha and beta) to 1.
+
+.. code-block:: shell
+
+    niaarm -i Abalone.csv -a DifferentialEvolution --max-iters 30 --alpha 1 --beta 1 -o output.csv
+
+After running the above command we are prompted to edit the algorithms parameters in a text editor
+(vi or nano on unix, notepad on windows):
+
+.. image:: _static/cli_edit_params.png
+   :width: 500
+
+After we're done editing the parameters, we save the file and exit the editor, so the algorithm can run.
+The output should look like this:
+
+.. code-block:: text
+
+    Fitness: 0.00023943493698845255, Support: 0.00023940627244433804, Confidence:0.00023946360153256704, Coverage:0, Shrinkage:0
+    Fitness: 0.01586342792950406, Support: 0.0009576250897773521, Confidence:0.03076923076923077, Coverage:0, Shrinkage:0
+    Fitness: 0.1618229766922219, Support: 0.1410102944697151, Confidence:0.1826356589147287, Coverage:0, Shrinkage:0
+    Fitness: 0.2611983818591431, Support: 0.009576250897773522, Confidence:0.5128205128205128, Coverage:0, Shrinkage:0
+    Fitness: 0.5001197031362221, Support: 0.00023940627244433804, Confidence:1.0, Coverage:0, Shrinkage:0
+    Fitness: 0.5136461575293273, Support: 0.027292315058654537, Confidence:1.0, Coverage:0, Shrinkage:0
+    Fitness: 0.6330497294288803, Support: 0.3121857792674168, Confidence:0.9539136795903438, Coverage:0, Shrinkage:0
+    Fitness: 0.6739678268052298, Support: 0.3610246588460618, Confidence:0.9869109947643979, Coverage:0, Shrinkage:0
+    Fitness: 0.9755528320322524, Support: 0.9614555901364615, Confidence:0.9896500739280434, Coverage:0, Shrinkage:0
+    Fitness: 0.9997605937275557, Support: 0.9995211874551113, Confidence:1.0, Coverage:0, Shrinkage:0
+    Fitness: 1.0, Support: 1.0, Confidence:1.0, Coverage:0, Shrinkage:0
+    Rules exported to output.csv
+
+Let's make sure it generated a csv file with the rules:
+
+.. code-block:: shell
+
+    head -n 5 output.csv
+
+.. code-block:: text
+
+    antecedent,consequent,fitness,support,confidence,coverage,shrinkage
+    "['Shell weight([0.0015, 1.005])']","['Diameter([0.055, 0.65])', 'Viscera weight([0.0005, 0.76])']",1.0,1.0,1.0,0,0
+    "['Length([0.075, 0.815])']","['Shell weight([0.0015, 1.005])', 'Viscera weight([0.0005, 0.76])']",1.0,1.0,1.0,0,0
+    "['Whole weight([0.002, 2.8255])']","['Viscera weight([0.0005, 0.76])']",1.0,1.0,1.0,0,0
+    "['Rings([1, 29])', 'Diameter([0.055, 0.65])']","['Viscera weight([0.0005, 0.76])']",1.0,1.0,1.0,0,0
+
+Displaying statistics
+~~~~~~~~~~~~~~~~~~~~~
+
+With the ``--show-stats`` flag we can print basic statistics about the mined association rules.
+E.g. (for the above run):
+
+.. code-block:: text
+
+    STATS:
+    Total rules: 550
+    Average fitness: 0.5591053904322874
+    Average support: 0.3881446013885564
+    Average confidence: 0.7300661794760184
+    Average coverage: 0.0
+    Average shrinkage: 0.0
+    Average length of antecedent: 2.0163636363636366
+    Average length of consequent: 1.789090909090909

docs/documentation.rst

@@ -5,7 +5,7 @@ To locally generate and preview documentation run the following commands in the
 
 .. code:: sh
 
-    $ poetry install --extras docs
-    $ poetry run sphinx-build ./docs ./docs/_build
+    poetry install --extras docs
+    poetry run sphinx-build ./docs ./docs/_build
 
 If the build of the documentation is successful, you can preview the documentation in the docs/_build folder by clicking the ``index.html`` file.

docs/index.rst

@@ -17,7 +17,7 @@ NiaARM is a framework for Association Rule Mining based on nature-inspired algor
 Detailed insights
 -----------------------
 
-The current version witholds (but is not limited to) the following functions:
+The current version includes (but is not limited to) the following functions:
 
 - loading datasets in CSV format,
 - preprocessing of data,

examples/basic_run.py

@@ -12,8 +12,8 @@
     # dimension represents the dimension of the problem;
     # features represent the list of features, while transactions depicts the list of transactions
     # the following 4 elements represent weights (support, confidence, coverage, shrinkage)
-    # None defines that criteria are omitted and are, therefore, excluded from the fitness function
-    problem = NiaARM(data.dimension, data.features, data.transactions, alpha=1.0, beta=1.0)
+    # A weight of 0.0 means that criteria are omitted and are, therefore, excluded from the fitness function
+    problem = NiaARM(data.dimension, data.features, data.transactions, alpha=1.0, beta=1.0, logging=True)
 
     # build niapy task
     task = Task(problem=problem, max_iters=30, optimization_type=OptimizationType.MAXIMIZATION)

examples/stats.py

@@ -21,13 +21,4 @@
 
     # Instantiate Stats object and print basic statistics of mined rules.
     stats = Stats(problem.rules)
-
-    print('\nSTATS:')
-    print(f'Total rules: {stats.total_rules}')
-    print(f'Average fitness: {stats.mean_fitness}')
-    print(f'Average support: {stats.mean_support}')
-    print(f'Average confidence: {stats.mean_confidence}')
-    print(f'Average coverage: {stats.mean_coverage}')
-    print(f'Average shrinkage: {stats.mean_shrinkage}')
-    print(f'Average length of antecedent: {stats.mean_ant_len}')
-    print(f'Average length of consequent: {stats.mean_con_len}')
+    print(stats)

niaarm/cli.py

@@ -25,10 +25,11 @@ def get_parser():
     parser.add_argument('-s', '--seed', type=int, help='Seed for the algorithm\'s random number generator')
     parser.add_argument('--max-evals', type=int, default=np.inf, help='Maximum number of fitness function evaluations')
     parser.add_argument('--max-iters', type=int, default=np.inf, help='Maximum number of iterations')
-    parser.add_argument('--alpha', type=float, default=0.0, help='Alpha parameter. Default 0')
-    parser.add_argument('--beta', type=float, default=0.0, help='Beta parameter. Default 0')
-    parser.add_argument('--gamma', type=float, default=0.0, help='Gamma parameter. Default 0')
-    parser.add_argument('--delta', type=float, default=0.0, help='Delta parameter. Default 0')
+    parser.add_argument('--alpha', type=float, default=0.0,
+                        help='Support weight. Default: 0. Note: at least one of alpha, beta, gamma, delta must be set')
+    parser.add_argument('--beta', type=float, default=0.0, help='Confidence weight. Default: 0')
+    parser.add_argument('--gamma', type=float, default=0.0, help='Shrinkage weight. Default: 0')
+    parser.add_argument('--delta', type=float, default=0.0, help='Coverage weight. Default: 0')
     parser.add_argument('--log', action='store_true', help='Enable logging of fitness improvements')
     parser.add_argument('--show-stats', action='store_true', help='Display stats about mined rules')
 
@@ -164,15 +165,7 @@ def main():
 
         if args.show_stats:
             stats = Stats(problem.rules)
-            print('\nSTATS:')
-            print(f'Total rules: {stats.total_rules}')
-            print(f'Average fitness: {stats.mean_fitness}')
-            print(f'Average support: {stats.mean_support}')
-            print(f'Average confidence: {stats.mean_confidence}')
-            print(f'Average coverage: {stats.mean_coverage}')
-            print(f'Average shrinkage: {stats.mean_shrinkage}')
-            print(f'Average length of antecedent: {stats.mean_ant_len}')
-            print(f'Average length of consequent: {stats.mean_con_len}')
+            print(stats)
 
     except Exception as e:
         print('Error:', e, file=sys.stderr)

niaarm/niaarm.py

@@ -70,7 +70,7 @@ def export_rules(self, path):
             writer = csv.writer(f)
 
             # write header
-            writer.writerow(["Antecedent", "consequent", "Fitness", "Support", "Confidence", "Coverage", "Shrinkage"])
+            writer.writerow(["antecedent", "consequent", "fitness", "support", "confidence", "coverage", "shrinkage"])
 
             for rule in self.rules:
                 writer.writerow(

niaarm/stats.py

@@ -53,3 +53,15 @@ def mean_ant_len(self):
     @property
     def mean_con_len(self):
         return np.mean([len(rule.consequent) for rule in self.rules])
+
+    def __str__(self):
+        string = f'STATS:\n' \
+                 f'Total rules: {self.total_rules}\n' \
+                 f'Average fitness: {self.mean_fitness}\n' \
+                 f'Average support: {self.mean_support}\n' \
+                 f'Average confidence: {self.mean_confidence}\n' \
+                 f'Average coverage: {self.mean_coverage}\n' \
+                 f'Average shrinkage: {self.mean_shrinkage}\n' \
+                 f'Average length of antecedent: {self.mean_ant_len}\n' \
+                 f'Average length of consequent: {self.mean_con_len}'
+        return string