Merge pull request #38 from AP6YC/release/0.3.7

Release/0.3.7

Project.toml

@@ -2,7 +2,7 @@ name = "AdaptiveResonance"
 uuid = "3d72adc0-63d3-4141-bf9b-84450dd0395b"
 authors = ["Sasha Petrenko"]
 description = "A Julia package for Adaptive Resonance Theory (ART) algorithms."
-version = "0.3.6"
+version = "0.3.7"
 
 [deps]
 Distributed = "8ba89e20-285c-5b6f-9357-94700520ee1b"

README.md

@@ -10,7 +10,6 @@ A Julia package for Adaptive Resonance Theory (ART) algorithms.
 | **Dependents** | **Date** | **Status** |
 |:--------------:|:--------:|:----------:|
 | [![deps][deps-img]][deps-url] | [![version][version-img]][version-url] | [![pkgeval][pkgeval-img]][pkgeval-url] |
-<!-- | [![Stable][docs-stable-img]][docs-stable-url] [![Dev][docs-dev-img]][docs-dev-url] | [![Build Status][travis-img]][travis-url] [![Build Status][appveyor-img]][appveyor-url] | [![Codecov][codecov-img]][codecov-url] [![Coveralls][coveralls-img]][coveralls-url] | -->
 
 [deps-img]: https://juliahub.com/docs/AdaptiveResonance/deps.svg
 [deps-url]: https://juliahub.com/ui/Packages/AdaptiveResonance/Sm0We?t=2
@@ -29,8 +28,6 @@ A Julia package for Adaptive Resonance Theory (ART) algorithms.
 
 [ci-img]: https://github.com/AP6YC/AdaptiveResonance.jl/workflows/CI/badge.svg
 [ci-url]: https://github.com/AP6YC/AdaptiveResonance.jl/actions?query=workflow%3ACI
-<!-- [travis-img]: https://travis-ci.com/AP6YC/AdaptiveResonance.jl.svg?branch=master -->
-<!-- [travis-url]: https://travis-ci.com/AP6YC/AdaptiveResonance.jl -->
 
 [appveyor-img]: https://ci.appveyor.com/api/projects/status/github/AP6YC/AdaptiveResonance.jl?svg=true
 [appveyor-url]: https://ci.appveyor.com/project/AP6YC/AdaptiveResonance-jl
@@ -42,12 +39,7 @@ A Julia package for Adaptive Resonance Theory (ART) algorithms.
 [coveralls-url]: https://coveralls.io/github/AP6YC/AdaptiveResonance.jl?branch=master
 
 [issues-url]: https://github.com/AP6YC/AdaptiveResonance.jl/issues
-[contrib-url]: https://juliadocs.github.io/Documenter.jl/dev/contributing/
-[discourse-tag-url]: https://discourse.julialang.org/tags/documenter
-[gitter-url]: https://gitter.im/juliadocs/users
-
-This package is developed and maintained by [Sasha Petrenko](https://github.com/AP6YC) with sponsorship by the [Applied Computational Intelligence Laboratory (ACIL)](https://acil.mst.edu/). This project is supported by grants from the [Night Vision Electronic Sensors Directorate](https://c5isr.ccdc.army.mil/inside_c5isr_center/nvesd/), the [DARPA Lifelong Learning Machines (L2M) program](https://www.darpa.mil/program/lifelong-learning-machines), [Teledyne Technologies](http://www.teledyne.com/), and the [National Science Foundation](https://www.nsf.gov/).
-The material, findings, and conclusions here do not necessarily reflect the views of these entities.
+[contrib-url]: https://ap6yc.github.io/AdaptiveResonance.jl/dev/man/contributing/
 
 Please read the [documentation](https://ap6yc.github.io/AdaptiveResonance.jl/dev/) for detailed usage and tutorials.
 
@@ -56,11 +48,11 @@ Please read the [documentation](https://ap6yc.github.io/AdaptiveResonance.jl/dev
 - [AdaptiveResonance](#adaptiveresonance)
   - [Contents](#contents)
   - [Overview](#overview)
+  - [Contributing](#contributing)
   - [Installation](#installation)
   - [Quickstart](#quickstart)
   - [Implemented Modules](#implemented-modules)
   - [Structure](#structure)
-  - [Contributing](#contributing)
   - [History](#history)
   - [Credits](#credits)
     - [Authors](#authors)
@@ -77,6 +69,20 @@ This package provides implementations of many of these algorithms in Julia for b
 Basic installation is outlined in [Installation](#installation), while a quickstart is provided in [Quickstart](#quickstart).
 Detailed usage and examples are provided in the [documentation](https://ap6yc.github.io/AdaptiveResonance.jl/dev/).
 
+## Contributing
+
+If you have a question or concern, please raise an [issue][issues-url].
+For more details on how to work with the project, propose changes, or even contribute code, please see the [Developer Notes][contrib-url] in the project's documentation.
+
+In summary:
+
+1. Questions and requested changes should all be made in the [issues][issues-url] page.
+These are preferred because they are publicly viewable and could assist or educate others with similar issues or questions.
+2. For changes, this project accepts pull requests (PRs) from `feature/<my-feature>` branches onto the `develop` branch using the [GitFlow](https://nvie.com/posts/a-successful-git-branching-model/) methodology.
+If unit tests pass and the changes are beneficial, these PRs are merged into `develop` and eventually folded into versioned releases.
+3. The project follows the [Semantic Versioning](https://semver.org/) convention of `major.minor.patch` incremental versioning numbers.
+Patch versions are for bug fixes, minor versions are for backward-compatible changes, and major versions are for new and incompatible usage changes.
+
 ## Installation
 
 This project is distributed as a Julia package, available on [JuliaHub](https://juliahub.com/).
@@ -161,8 +167,7 @@ AdaptiveResonance
 ├── examples                // Source: example usage scripts.
 ├── src                     // Source: majority of source code.
 │   ├───ART                 //      ART-based unsupervised modules.
-│   ├───ARTMAP              //      ARTMAP-based supervised modules.
-│   └───CVI                 //      Cluster validity indices.
+│   └───ARTMAP              //      ARTMAP-based supervised modules.
 ├── test                    // Test: Unit, integration, and environment tests.
 ├── .appveyor               // Appveyor: Windows-specific coverage.
 ├── .gitignore              // Git: .gitignore for the whole project.
@@ -171,21 +176,21 @@ AdaptiveResonance
 └── README.md               // Doc: this document.
 ```
 
-## Contributing
-
-Please raise an [issue][issues-url].
-
 ## History
 
 - 7/10/2020 - Begin project.
 - 11/3/2020 - Complete baseline modules and tests.
 - 2/8/2021 - Formalize usage documentation.
+- 10/13/2021 - Initiate GitFlow contribution.
 
 ## Credits
 
 ### Authors
 
-- Sasha Petrenko <[email protected]>
+This package is developed and maintained by [Sasha Petrenko](https://github.com/AP6YC) with sponsorship by the [Applied Computational Intelligence Laboratory (ACIL)](https://acil.mst.edu/). This project is supported by grants from the [Night Vision Electronic Sensors Directorate](https://c5isr.ccdc.army.mil/inside_c5isr_center/nvesd/), the [DARPA Lifelong Learning Machines (L2M) program](https://www.darpa.mil/program/lifelong-learning-machines), [Teledyne Technologies](http://www.teledyne.com/), and the [National Science Foundation](https://www.nsf.gov/).
+The material, findings, and conclusions here do not necessarily reflect the views of these entities.
+
+The users [@aaronpeikert](https://github.com/aaronpeikert), [@hayesall](https://github.com/hayesall), and [@markNZed](https://github.com/markNZed) have graciously contributed their time with reviews and feedback that has greatly improved the project.
 
 ### Software
 

docs/serve.jl

@@ -1,2 +1,7 @@
 using LiveServer
-serve(dir="build")
+
+# Make the documentation
+include("make.jl")
+
+# Serve the documentation for development
+serve(dir="build")

docs/src/man/contributing.md

@@ -1,11 +1,162 @@
 # Contributing
 
-To formally contribute to the package, please follow the usual branch pull request procedure:
+This page serves as the contribution guide for the `AdaptiveResonance.jl` package.
+From top to bottom, the ways of contributing are:
 
-1. Fork the project.
-2. Create your feature branch (git checkout -b my-new-feature).
-3. Commit your changes (git commit -am 'Added some feature').
-4. Push to the branch (git push origin my-new-feature).
-5. Create a new [GitHub pull request](https://github.com/AP6YC/AdaptiveResonance.jl/pulls).
+- [GitHub Issues:](@ref Issues) how to raise an issue with the project.
+- [Julia Development:](@ref Julia-Development) how to download and interact with the package.
+- [GitFlow:](@ref GitFlow) how to directly contribute code to the package in an organized way on GitHub.
+- [Development Details:](@ref Development-Details) how the internals of the package are currently setup if you would like to directly contribute code.
+
+## Issues
+
+The main point of contact is the [GitHub issues](https://github.com/AP6YC/AdaptiveResonance.jl/issues) page for the project.
+This is the easiest way to contribute to the project, as any issue you find or request you have will be addressed there by the authors of the package.
+Depending on the issue, the authors will collaborate with you, and after making changes they will link a [pull request](@ref GitFlow) which addresses your concern or implements your proposed changes.
+
+## Julia Development
+
+As a Julia package, development follows the usual procedure:
+
+1. Clone the project from GitHub
+2. Switch to or create the branch that you wish work on (see [GitFlow](@ref)).
+3. Start Julia at your development folder.
+4. Instantiate the package (i.e., download and install the package dependencies).
+
+For example, you can get the package and startup Julia with
+
+```sh
+git clone [email protected]:AP6YC/AdaptiveResonance.jl.git
+julia --project=.
+```
+
+!!! note "Note"
+    In Julia, you must activate your project in the current REPL to point to the location/scope of installed packages.
+    The above immediately activates the project when starting up Julia, but you may also separately startup the julia and activate the package with the interactive
+    package manager via the `]` syntax:
+
+    ```julia
+    julia
+    julia> ]
+    (@v1.6) pkg> activate .
+    (AdaptiveResonance) pkg>
+    ```
+
+You may run the package's unit tests after the above setup in Julia with
+
+```julia
+julia> using Pkg
+julia> Pkg.instantiate()
+julia> Pkg.test()
+```
+
+or interactively though the Julia package manager with
+
+```julia
+julia> ]
+(AdaptiveResonance) pkg> instantiate
+(AdaptiveResonance) pkg> test
+```
+
+## GitFlow
+
+As of verson `0.3.7`, the `AdaptiveResonance.jl` package follows the [GitFlow](https://nvie.com/posts/a-successful-git-branching-model/) git working model.
+The [original post](https://nvie.com/posts/a-successful-git-branching-model/) by Vincent Driessen outlines this methodology quite well, while [Atlassian](https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow) has a good tutorial as well.
+In summary:
+
+1. Create a feature branch off of the `develop` branch with the name `feature/<my-feature-name>`.
+2. Commit your changes and push to this feature branch.
+3. When you are satisfied with your changes, initiate a [GitHub pull request](https://github.com/AP6YC/AdaptiveResonance.jl/pulls) (PR) to merge the feature branch with `develop`.
+4. If the unit tests pass, the feature branch will first be merged with develop and then be deleted.
+5. Releases will be periodically initiated from the `develop` branch and versioned onto the `master` branch.
+6. Immediate bug fixes circumvent this process through a `hotfix` branch off of `master`.
+
+## Development Details
+
+### Documentation
+
+These docs are currently hosted as a static site on the GitHub pages platform.
+They are setup to be built and served in a separate branch `gh-pages` from the master/development branch of the project.
+
+### Package Structure
+
+The `AdaptiveResonance.jl` package has the following file structure:
+
+```console
+AdaptiveResonance
+├── .github/workflows       // GitHub: workflows for testing and documentation.
+├── data                    // Data: CI data location.
+├── docs                    // Docs: documentation for the module.
+│   └───src                 //      Documentation source files.
+├── examples                // Source: example usage scripts.
+├── src                     // Source: majority of source code.
+│   ├───ART                 //      ART-based unsupervised modules.
+│   └───ARTMAP              //      ARTMAP-based supervised modules.
+├── test                    // Test: Unit, integration, and environment tests.
+├── .appveyor               // Appveyor: Windows-specific coverage.
+├── .gitignore              // Git: .gitignore for the whole project.
+├── LICENSE                 // Doc: the license to the project.
+├── Project.toml            // Julia: the Pkg.jl dependencies of the project.
+└── README.md               // Doc: this document.
+```
+
+ART and ARTMAP algorithms are put into their own files within the `src/ART/` and `src/ARTMAP/` directories, respectively.
+Both of these directories have an "index" file where each module is "included" (i.e., `src/ART/ART.jl`), which is in turn "included" in the package module file `src/AdaptiveResonance.jl`.
+
+Abstract types and common structures/methods are included at the top of the package module file.
+All public methods and structs (i.e., for the end user) are "exported" at the end of this file.
+
+### ART Module Workflow
+
+To write an ART module for this project, it will require the following:
+
+1. A `train!` and `classify` method (within the module).
+2. An keyword-options struct using the `Parameters.jl` macro `@with_kw` with assertions to keep the parameters within correct ranges.
+3. Three constructors:
+   1. A default constructor (i.e. `DDVFA()`).
+   2. A keyword argument constructor (passing the kwargs to the options struct defined above).
+   3. A constructor with the options struct passed itself.
+4. Use of [common type aliases](@ref Type-Aliases) in method definitions.
+5. An internal [`DataConfig`](@ref DataConfig) for setting up the data configuration, especially with `data_setup!` (`src/common.jl`).
+6. An `update_iter` evaluation for each iteration (`src/common.jl`).
+7. Inclusion to the correct ART index file (i.e., `src/ART/ART.jl`).
+8. Exports of the names for the options and module constructors in the module definition (`src/AdaptiveResonance.jl`).
+
+#### DataConfig
+
+The original implementation of ART1 uses binary vectors, which have guaranteed separation between distinct vectors.
+Real-valued ART modules, however, face the problem of permitting vectors to be arbitrarily close to one another.
+Therefore, nearly every real-valued ART module uses [0, 1] normalization and complement-coding.
+This is reflected in the `DataConfig` struct in the common file `src/common.jl`.
+
+#### Type Aliases
+
+In the pursuit of an architecture-agnostic implementation (i.e., support for both 32- and 64-bit systems), type aliases and other special Julia types are used in this project.
+
+This module borrows a convention from the `StatsBase.jl` package by defining a variety of aliases for numerical types used throughout the package to standardize usage.
+This has the benefits of readability and speed by explicitly
+These are defined in `src/common.jl` and are currently as follows:
+
+```julia
+# Real-numbered aliases
+const RealArray{T<:Real, N} = AbstractArray{T, N}
+const RealVector{T<:Real} = AbstractArray{T, 1}
+const RealMatrix{T<:Real} = AbstractArray{T, 2}
+
+# Integered aliases
+const IntegerArray{T<:Integer, N} = AbstractArray{T, N}
+const IntegerVector{T<:Integer} = AbstractArray{T, 1}
+const IntegerMatrix{T<:Integer} = AbstractArray{T, 2}
+
+# Specifically floating-point aliases
+const RealFP = Union{Float32, Float64}
+```
+
+In this package, data samples are always `Real`-valued (with the notable exception of [ART1](@ref DataConfig)), while class labels are integered.
+Furthermore, independent class labels are always `Int` because of the [Julia native support](https://docs.julialang.org/en/v1/manual/integers-and-floating-point-numbers/#Integers) for a given system's signed native integer type.
+
+This project does not currently test for the support of [arbitrary precision arithmetic](https://docs.julialang.org/en/v1/manual/integers-and-floating-point-numbers/#Arbitrary-Precision-Arithmetic) because learning algorithms *in general* do not have a significant need for precision beyond even 32-bit floats.
+
+## Authors
 
 If you simply have suggestions for improvement, Sasha Petrenko (<[email protected]>) is the current developer and maintainer of the AdaptiveResonance.jl package, so please feel free to reach out with thoughts and questions.

src/common.jl

@@ -78,7 +78,7 @@ function DataConfig(mins::RealVector, maxs::RealVector)
     DataConfig(
         true,   # setup
         mins,   # min
-        maxs,    # max
+        maxs,   # max
         dim,    # dim
         dim*2   # dim_comp
     )