Merge pull request #23 from zStupan/docs

Docs Update

docs/api/dataset.rst

@@ -0,0 +1,5 @@
+Dataset
+=======
+
+.. automodule:: niaarm.dataset
+    :members:

docs/api/feature.rst

@@ -0,0 +1,5 @@
+Feature
+=======
+
+.. automodule:: niaarm.feature
+    :members:

docs/api/index.rst

@@ -0,0 +1,10 @@
+API Reference
+=============
+
+.. toctree::
+
+    dataset
+    niaarm
+    stats
+    rule
+    feature

docs/api/niaarm.rst

@@ -0,0 +1,6 @@
+NiaARM
+======
+
+.. automodule:: niaarm.niaarm
+    :members:
+    :show-inheritance:

docs/api/rule.rst

@@ -0,0 +1,5 @@
+Rule
+====
+
+.. automodule:: niaarm.rule
+    :members:

docs/api/stats.rst

@@ -0,0 +1,5 @@
+Stats
+=====
+
+.. automodule:: niaarm.stats
+    :members:

docs/cli.rst

@@ -0,0 +1,37 @@
+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.
+
+.. 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]
+                  [--show-stats]
+
+    Perform ARM, output mined rules as csv, get mined rules' statistics
+
+    options:
+      -h, --help            show this help message and exit
+      -i INPUT_FILE, --input-file INPUT_FILE
+                            Input file containing a csv dataset
+      -o OUTPUT_FILE, --output-file OUTPUT_FILE
+                            Output file for mined rules
+      -a ALGORITHM, --algorithm ALGORITHM
+                            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
+      --log                 Enable logging of fitness improvements
+      --show-stats          Display stats about mined rules

docs/conf.py

@@ -10,9 +10,9 @@
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
-# import os
-# import sys
-# sys.path.insert(0, os.path.abspath('.'))
+import os
+import sys
+sys.path.insert(0, os.path.abspath('../../'))
 
 
 # -- Project information -----------------------------------------------------
@@ -30,7 +30,7 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = ['sphinx.ext.autodoc', 'sphinx_rtd_theme', 'sphinxcontrib.bibtex']
+extensions = ['sphinx.ext.autodoc', 'sphinx_rtd_theme', 'sphinxcontrib.bibtex', 'sphinx.ext.napoleon']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -60,7 +60,7 @@
 bibtex_default_style = 'unsrt'
 
 # Add logo for project
-html_logo = '../.github/logo/logo.png'
+html_logo = '_static/logo.png'
 html_theme_options = {
     'logo_only': True,
     'display_version': False,

docs/documentation.rst

@@ -1,10 +1,11 @@
 Documentation
 =============
 
-To locally generate and preview documentation run the following command in the project root folder:
+To locally generate and preview documentation run the following commands in the project root folder:
 
 .. code:: sh
 
+    $ 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/getting_started.rst

@@ -18,4 +18,4 @@ After the successful installation you are ready to run your first example.
 Examples
 --------
 
-You can find usage examples `here <https://github.com/firefly-cpp/NiaARM`_.
+You can find usage examples `here <https://github.com/firefly-cpp/NiaARM/tree/main/examples>`_.

docs/index.rst

@@ -7,7 +7,7 @@ NiaARM is a minimalistic framework for numerical association rule mining.
 
 * **Free software:** MIT license
 * **Github repository:** https://github.com/firefly-cpp/NiaARM
-* **Python versions:** 3.6.x, 3.7.x, 3.8.x
+* **Python versions:** 3.7.x, 3.8.x, 3.9.x, 3.10.x
 
 General outline of the framework
 ---------------------------------
@@ -33,6 +33,7 @@ The main documentation is organized into a couple of sections:
 
 * :ref:`user-docs`
 * :ref:`dev-docs`
+* :ref:`api-reference`
 * :ref:`about-docs`
 
 .. _user-docs:
@@ -42,6 +43,7 @@ The main documentation is organized into a couple of sections:
    :caption: User Documentation
 
    getting_started
+   cli
 
 .. _dev-docs:
 
@@ -52,6 +54,13 @@ The main documentation is organized into a couple of sections:
    installation
    testing
    documentation
+
+.. _api-reference:
+
+.. toctree::
+   :maxdepth: 2
+   :caption: API Reference
+
    api/index
 
 .. _about-docs:
@@ -64,5 +73,7 @@ The main documentation is organized into a couple of sections:
    code_of_conduct
    license
 
+.. rubric:: References
+
 .. bibliography::
    :all:

docs/installation.rst

@@ -20,24 +20,37 @@ All of the project's dependencies should be installed and the project
 ready for further development. **Note that Poetry creates a separate
 virtual environment for your project.**
 
-Development dependencies
-~~~~~~~~~~~~~~~~~~~~~~~~
-
-List of sport-activities-features dependencies:
+Dependencies
+~~~~~~~~~~~~
 
 +----------------+--------------+------------+
 | Package        | Version      | Platform   |
 +================+==============+============+
-| niapy          | ^2.0.0       | All        |
+| niapy          | ^2.0.1       | All        |
++----------------+--------------+------------+
+| pandas         | ^1.3.5       | All        |
++----------------+--------------+------------+
+| numpy          | ^1.21.5      | All        |
 +----------------+--------------+------------+
 
-
-List of development dependencies:
+Development Dependencies
+~~~~~~~~~~~~~~~~~~~~~~~~
 
 +--------------------+-----------+------------+
 | Package            | Version   | Platform   |
 +====================+===========+============+
-| Sphinx             | ^3.5.1    | Any        |
-+--------------------+-----------+------------+
-| sphinx-rtd-theme   | ^0.5.1    | Any        |
+| Pytest             | ^7.0.1    | Any        |
 +--------------------+-----------+------------+
+
+Extras
+~~~~~~
+
++------------------------------+--------------+------------+
+| Package                      | Version      | Platform   |
++==============================+==============+============+
+| Sphinx                       | ^4.4.0       | Any        |
++------------------------------+--------------+------------+
+| sphinx-rtd-theme             | ^1.0.0       | Any        |
++------------------------------+--------------+------------+
+| sphinxcontrib-bibtex         | ^2.4.1       | Any        |
++------------------------------+--------------+------------+

docs/testing.rst

@@ -5,8 +5,8 @@ Before making a pull request, if possible provide tests for added features or bu
 
 In case any of the test cases fails, those should be fixed before we merge your pull request to master branch.
 
-For the purpose of checking if all test are passing localy you can run following command:
+For the purpose of checking if all test are passing locally you can run following command:
 
 .. code:: sh
 
-    $ poetry run python -m unittest discover
+    $ poetry run pytest

examples/stats.py

@@ -24,10 +24,10 @@
 
     print('\nSTATS:')
     print(f'Total rules: {stats.total_rules}')
-    print(f'Average fitness: {stats.avg_fitness}')
-    print(f'Average support: {stats.avg_support}')
-    print(f'Average confidence: {stats.avg_confidence}')
-    print(f'Average coverage: {stats.avg_coverage}')
-    print(f'Average shrinkage: {stats.avg_shrinkage}')
-    print(f'Average length of antecedent: {stats.avg_ant_len}')
-    print(f'Average length of consequent: {stats.avg_con_len}')
+    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}')

niaarm/__init__.py

@@ -3,6 +3,6 @@
 from niaarm.stats import Stats
 
 
-__all__ = [NiaARM, Dataset, Stats]
+__all__ = ['NiaARM', 'Dataset', 'Stats']
 
 __version__ = "0.1.3"

niaarm/cli.py

@@ -5,7 +5,6 @@
 import platform
 import subprocess
 import sys
-import tempfile
 
 import numpy as np
 from niaarm import NiaARM, Dataset, Stats
@@ -85,7 +84,7 @@ def convert_string(string):
 
 
 def parse_parameters(text, algorithm):
-    lines: list[str] = text.strip().split('\n')
+    lines = text.strip().split('\n')
     lines = [line.strip() for line in lines if line.strip() and not line.strip().startswith('#')]
     parameters = {}
     for line in lines:
@@ -108,8 +107,7 @@ def parse_parameters(text, algorithm):
 def edit_parameters(parameters, algorithm):
     parameters.pop('individual_type', None)
     parameters.pop('initialization_function', None)
-    fd, filename = tempfile.mkstemp()
-    os.close(fd)
+    filename = f'{algorithm.Name[1]}_parameters'
 
     new_parameters = None
     try:
@@ -168,13 +166,13 @@ def main():
             stats = Stats(problem.rules)
             print('\nSTATS:')
             print(f'Total rules: {stats.total_rules}')
-            print(f'Average fitness: {stats.avg_fitness}')
-            print(f'Average support: {stats.avg_support}')
-            print(f'Average confidence: {stats.avg_confidence}')
-            print(f'Average coverage: {stats.avg_coverage}')
-            print(f'Average shrinkage: {stats.avg_shrinkage}')
-            print(f'Average length of antecedent: {stats.avg_ant_len}')
-            print(f'Average length of consequent: {stats.avg_con_len}')
+            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}')
 
     except Exception as e:
         print('Error:', e, file=sys.stderr)

niaarm/dataset.py

@@ -5,6 +5,14 @@
 class Dataset:
     r"""Class for working with a dataset.
 
+    Args:
+        path (str): Path to the dataset (csv) file.
+        delimiter (str): The delimiter in the csv file.
+        header (Optional[int]): Row to use as header (zero-based). Default: 0.
+         Pass ``header=None`` if the file doesn't contain a header.
+        names (Optional[list[str]]): List of feature names to use.
+         If the file already contains a header row, pass ``header=0`` to override the feature names.
+
     Attributes:
         data (pd.DataFrame): Data as a pandas Dataframe.
         transactions (np.ndarray): Transactional data.

niaarm/feature.py

@@ -6,7 +6,7 @@
 class Feature:
     r"""Class representing a feature.
 
-    Attributes:
+    Args:
        name (str): Name of the feature.
        dtype (str): Datatype of the feature.
        min_val (Optional[float]): Minimum value of the feature in the transaction database.