Merge d965795 into c179b3a

.github/workflows/CI.yml

@@ -63,6 +63,12 @@ jobs:
         with:
           file: lcov.info
 
+      - name: Coveralls
+        uses: coverallsapp/github-action@master
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          path-to-lcov: lcov.info
+
   # docs:
   #   name: Documentation
   #   runs-on: ubuntu-latest

.gitignore

@@ -1,14 +1,13 @@
-# IDE ignores
-.vscode/
+# -----------------------------------------------------------------------------
+# PROJECT IGNORES
+# -----------------------------------------------------------------------------
 
-# Development ignores
-# _dev/
-_dev/*.jld
-_dev/*.jld2
+# Development/scratch folder
+_dev/
 dev/
 
-# Project-specific ignores
-default_rocket.jld2
+# IDE ignores
+.vscode/
 
 # Ignore generated results
 data/results/*
@@ -17,6 +16,17 @@ data/results/*
 data/models/*
 !data/models/.gitkeep
 
+# DemoCards intermediate compilation directories
+docs/src/democards/
+docs/src/examples/
+
+# Downloads folder for files grabbed during docs generation
+docs/src/assets/downloads/
+
+# -----------------------------------------------------------------------------
+# JULIA IGNORES
+# -----------------------------------------------------------------------------
+
 # Files generated by invoking Julia with --code-coverage
 *.jl.cov
 *.jl.*.cov

Project.toml

@@ -7,30 +7,26 @@ version = "0.1.3"
 ClusterValidityIndices = "2fefd308-f647-4698-a2f0-e90cfcbca9ad"
 DelimitedFiles = "8bb1440f-4735-579b-a4ab-409b98df4dab"
 DocStringExtensions = "ffbed154-4ef7-542d-bbb7-c09d3a79fcae"
-JLD = "4138dd39-2aa7-5051-a626-17a0bb65d9c8"
 JLD2 = "033835bb-8acc-5ee8-8aae-3f567f8a3819"
 Logging = "56ddb016-857b-54e1-b83d-db4d58db5568"
 NumericalTypeAliases = "be9b823e-291e-41a1-b8ce-806204e78f92"
 Parameters = "d96e819e-fc66-5662-9728-84c9c7592b0a"
 PrecompileSignatures = "91cefc8d-f054-46dc-8f8c-26e11d7c5411"
 ProgressMeter = "92933f4c-e287-5a05-a399-4b506db050ca"
 PyCall = "438e738f-606a-5dbb-bf0a-cddfbfd45ab0"
-PyCallJLD = "de320387-30cd-5f83-91a8-a6e0ae8b8444"
 Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
 ScikitLearn = "3646fa90-6ef7-5e7e-9f22-8aca16db6324"
 StatsBase = "2913bbd2-ae8a-5f71-8c99-4fb6c76f3a91"
 
 [compat]
 ClusterValidityIndices = "0.6"
 DocStringExtensions = "0.8, 0.9"
-JLD = "0.12"
 JLD2 = "0.4"
 NumericalTypeAliases = "0.1, 0.2"
 Parameters = "0.12"
 ProgressMeter = "1"
 PyCall = "1"
-PyCallJLD = "0.2"
-ScikitLearn = "0.6"
+ScikitLearn = "0.7"
 StatsBase = "0.33"
 julia = "1"
 

README.md

@@ -1,23 +1,49 @@
 # MetaICVI
 
-A Julia implementation of the Meta-ICVI method as a separate package.
+A Julia implementation of the Meta-ICVI method as a standalone package.
 
-| **Documentation**  | **Build Status** | **Coverage** |
-|:------------------:|:----------------:|:------------:|
-| [![Stable][docs-stable-img]][docs-stable-url] [![Dev][docs-dev-img]][docs-dev-url] | [![Build Status][ci-img]][ci-url] | [![Codecov][codecov-img]][codecov-url]
+Please see the official [documentation][docs-dev-url] for usage and contribution guidelines.
+
+| **Documentation** | **Coverage** | **CI Status** | **Releases** |
+|:-----------------:|:------------:|:-------------:|:------------:|
+| [![Dev][docs-dev-img]][docs-dev-url] | [![Codecov][codecov-img]][codecov-url] | [![CI Status][ci-img]][ci-url] | [![Zenodo][zenodo-img]][zenodo-url] |
+| [![Stable][docs-stable-img]][docs-stable-url] | [![Coveralls][coveralls-img]][coveralls-url] | [![Documentation][doc-status-img]][doc-status-url] | [![version][version-img]][version-url] |
+| **Dependents** | **Issues** | **JuliaHub Status** | **Downloads** |
+| [![deps][deps-img]][deps-url] | [![GitHubIssues][issues-img]][issues-url] | [![JuliaHub][pkgeval-img]][pkgeval-url] | [![Downloads][downloads-img]][downloads-url] |
+
+[version-img]: https://juliahub.com/docs/General/MetaICVI/stable/version.svg
+[version-url]: https://juliahub.com/ui/Packages/General/MetaICVI
+
+[deps-img]: https://juliahub.com/docs/General/MetaICVI/stable/deps.svg
+[deps-url]: https://juliahub.com/ui/Packages/General/MetaICVI?t=2
+
+[downloads-img]: https://shields.io/endpoint?url=https://pkgs.genieframework.com/api/v1/badge/MetaICVI
+[downloads-url]: https://pkgs.genieframework.com?packages=MetaICVI
+
+[issues-img]: https://img.shields.io/github/issues/AP6YC/MetaICVI.jl
+[issues-url]: https://github.com/AP6YC/MetaICVI.jl/issues
+
+[zenodo-img]: https://zenodo.org/badge/DOI/10.5281/zenodo.5633988.svg
+[zenodo-url]: https://doi.org/10.5281/zenodo.5633988
 
 [docs-stable-img]: https://img.shields.io/badge/docs-stable-blue.svg
 [docs-stable-url]: https://AP6YC.github.io/MetaICVI.jl/stable
 
 [docs-dev-img]: https://img.shields.io/badge/docs-dev-blue.svg
 [docs-dev-url]: https://AP6YC.github.io/MetaICVI.jl/dev
 
+[doc-status-img]: https://github.com/AP6YC/MetaICVI.jl/actions/workflows/Documentation.yml/badge.svg
+[doc-status-url]: https://github.com/AP6YC/MetaICVI.jl/actions/workflows/Documentation.yml
+
 [ci-img]: https://github.com/AP6YC/MetaICVI.jl/workflows/CI/badge.svg
 [ci-url]: https://github.com/AP6YC/MetaICVI.jl/actions
 
 [codecov-img]: https://codecov.io/gh/AP6YC/MetaICVI.jl/branch/main/graph/badge.svg
 [codecov-url]: https://codecov.io/gh/AP6YC/MetaICVI.jl
 
+[pkgeval-img]: https://juliahub.com/docs/MetaICVI/pkgeval.svg
+[pkgeval-url]: https://juliahub.com/ui/Packages/MetaICVI/N0cWm
+
 [issues-url]: https://github.com/AP6YC/MetaICVI.jl/issues
 
 ## Table of Contents
@@ -47,7 +73,7 @@ Their installation followa the usual Julia package installation procedure, and t
 
 ```julia-repl
 julia> ]
-(@v1.8) pkg> add PyCallJLD MetaICVI
+(@v1.9) pkg> add PyCallJLD MetaICVI
 ```
 
 or programmatically:
@@ -62,7 +88,7 @@ You may also get the most recent changes directly from the GitHub repository wit
 
 ```julia-repl
 julia> ]
-(@v1.8) pkg> add https://github.com/AP6YC/MetaICVI.jl
+(@v1.9) pkg> add https://github.com/AP6YC/MetaICVI.jl
 ```
 
 or programmatically, also with the GitHub link:
@@ -107,7 +133,7 @@ you can specify the MetaICVI options with
 ```julia
 opts = MetaICVIOpts(
     classifier_selection = :SGDClassifier,
-    classifier_opts = (loss="log", max_iter=30),
+    classifier_opts = (loss="log_loss", max_iter=30),
     icvi_window = 5,
     correlation_window = 5,
     n_rocket = 5,
@@ -136,7 +162,6 @@ Please raise an [issue][issues-url].
 
 ## Acknowledgements
 
-
 ### Authors
 
 - Sasha Petrenko <sap625@mst.edu>

docs/Project.toml

@@ -1,4 +1,8 @@
 [deps]
+DemoCards = "311a05b2-6137-4a5a-b473-18580a3d38b5"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 LiveServer = "16fef848-5104-11e9-1b77-fb7a48bbb589"
 MetaICVI = "778c5047-3e82-4d04-81b5-6fafe2d2d704"
+NumericalTypeAliases = "be9b823e-291e-41a1-b8ce-806204e78f92"
+PyCallJLD = "de320387-30cd-5f83-91a8-a6e0ae8b8444"
+Revise = "295af30f-e4ad-537b-8983-00126c2a3abe"

docs/examples/config.json

@@ -0,0 +1,6 @@
+{
+    "theme": "grid",
+    "order": [
+        "tutorials"
+      ]
+}

docs/examples/index.md

@@ -0,0 +1,15 @@
+# [Examples](@id examples)
+
+This section contains some examples using the `MetaICVI` package with topics ranging from how to the internals of package work to practical examples on different datasets.
+
+---
+
+{{{democards}}}
+
+---
+
+## [Attribution](@id examples-attribution)
+
+Icons used for the covers of these demo cards are attributed to the following sites:
+
+- [Clustering icons created by Paul J. - Flaticon](https://www.flaticon.com/free-icons/clustering)([clustering_8847040](https://www.flaticon.com/free-icon/clustering_8847040))

docs/examples/tutorials/config.json

@@ -0,0 +1,4 @@
+{
+    "title": "Tutorials",
+    "description": "These examples demonstrate how to use the MetaICVI package."
+}

docs/examples/tutorials/metaicvi.jl

@@ -0,0 +1,25 @@
+# ---
+# title: MetaICVI
+# id: metaicvi-example
+# date: 2023-5-15
+# cover: ../assets/clustering.png
+# author: "[Sasha Petrenko](https://github.com/AP6YC)"
+# julia: 1.9
+# description: This demo provides a quick example of how use the MetaICVI module.
+# ---
+
+# ## Overview
+
+# This example demonstrates the basic usage of the MetaICVI method, including special considerations on how to load the package and how to use modules in the package.
+
+# ## Setup
+
+# First, we load our dependencies
+
+## Multi-line using statements are permitted in Julia to gather all requirements and compile at once
+using
+    PyCallJLD,  # For loading Python scikit-learn objects
+    MetaICVI    # This project
+
+# Next, we will include some utilties used in the testing process for the sake of loading and formatting the IRIS dataset for our purposes
+include("../../../../test/test_utils.jl")

docs/make.jl

@@ -1,8 +1,12 @@
 """
     make.jl
 
-This file builds the documentation for the ClusterValidityIndices.jl package
+# Description
+This file builds the documentation for the MetaICVI.jl package
 using Documenter.jl and other tools.
+
+# Authors
+- Sasha Petrenko <petrenkos@mst.edu>
 """
 
 # --------------------------------------------------------------------------- #
@@ -11,7 +15,9 @@ using Documenter.jl and other tools.
 
 # using MetaICVI
 using
-    Documenter
+    Documenter,
+    DemoCards,
+    Pkg
 
 # --------------------------------------------------------------------------- #
 # SETUP
@@ -50,30 +56,52 @@ end
 # GENERATE
 # --------------------------------------------------------------------------- #
 
-DocMeta.setdocmeta!(MetaICVI, :DocTestSetup, :(using MetaICVI); recursive=true)
+# DocMeta.setdocmeta!(MetaICVI, :DocTestSetup, :(using MetaICVI); recursive=true)
+
+# Generate the demo files
+# this is the relative path to docs/
+demopage, postprocess_cb, demo_assets = makedemos("examples")
+
+assets = [
+    joinpath("assets", "favicon.ico"),
+]
 
-makedocs(;
+# if there are generated css assets, pass it to Documenter.HTML
+isnothing(demo_assets) || (push!(assets, demo_assets))
+
+# Make the documentation
+makedocs(
     modules=[MetaICVI],
     authors="Sasha Petrenko",
     repo="https://github.com/AP6YC/MetaICVI.jl/blob/{commit}{path}#{line}",
     sitename="MetaICVI.jl",
     format=Documenter.HTML(;
-        prettyurls=get(ENV, "CI", "false") == "true",
+    prettyurls = get(ENV, "CI", nothing) == "true",
         canonical="https://AP6YC.github.io/MetaICVI.jl",
-        assets=String[],
+        assets = assets,
     ),
     pages=[
         "Home" => "index.md",
-        "Tutorial" => [
+        "Manual" => [
             "Guide" => "man/guide.md",
-            "Examples" => "man/examples.md",
+            demopage,
+        ],
+        "Internals" => [
+            "Index" => "man/full-index.md",
+            "Dev Index" => "man/dev-index.md",
             "Contributing" => "man/contributing.md",
-            "Index" => "man/full-index.md"
         ]
     ],
 )
 
+# 3. postprocess after makedocs
+postprocess_cb()
+
+# -----------------------------------------------------------------------------
+# DEPLOY
+# -----------------------------------------------------------------------------
+
 deploydocs(;
     repo="github.com/AP6YC/MetaICVI.jl",
-    devbranch = "main",
+    devbranch = "devbranch",
 )

docs/serve.jl

@@ -1,5 +1,30 @@
+"""
+    serve.jl
+
+# Description
+Convenience script that serves the locally built documentation.
+
+# Authors
+- Sasha Petrenko <petrenkos@mst.edu>
+"""
+
+# -----------------------------------------------------------------------------
+# DEPENDENCIES
+# -----------------------------------------------------------------------------
+
+using Revise
 using LiveServer
 
+# -----------------------------------------------------------------------------
+# INCLUDES
+# -----------------------------------------------------------------------------
+
+# Make the documentation
 include("make.jl")
 
+# -----------------------------------------------------------------------------
+# SERVE
+# -----------------------------------------------------------------------------
+
+# Serve the documentation for development
 serve(dir="build")

docs/src/index.md

@@ -18,16 +18,18 @@ This documentation is split into the following sections:
 ```@contents
 Pages = [
     "man/guide.md",
-    "man/examples.md",
+    "../examples/index.md",
     "man/contributing.md",
     "man/full-index.md",
+    "man/dev-index.md",
 ]
 Depth = 1
 ```
 
-The [Package Guide](@ref) provides a tutorial to the full usage of the package, while [Examples](@ref) gives sample workflows using a variety of ART modules.
+The [Package Guide](@ref) provides a tutorial to the full usage of the package, while [Examples](@ref examples) demonstrates some workflows using the `MetaICVI.jl` package.
 
-Instructions on how to contribute to the package are found in [Contributing](@ref), and docstrings for every element of the package is listed in the [Index](@ref main-index).
+Instructions on how to contribute to the package are found in [Contributing](@ref), and docstrings for every exported element of the package is listed in the [Index](@ref main-index).
+Internals are listed in the [Dev Index](@ref dev-main-index).
 
 ## Citation
 
@@ -36,11 +38,11 @@ Alternatively, you may use the following BibTeX entry for the JOSS paper associa
 
 ```bibtex
 @article{Melton2022,
-  author = "Niklas Melton and Sasha Petrenko and Donald Wunsch",
-  title = "{Meta-iCVIs: Ensemble Validity Metrics for Concise Labeling of Correct, Under- or Over-Partitioning in Streaming Clustering}",
-  year = "2022",
-  month = "12",
-  url = "https://doi.org/10.36227/techrxiv.21685214",
-  doi = "10.36227/techrxiv.21685214"
+    author = "Niklas Melton and Sasha Petrenko and Donald Wunsch",
+    title = "{Meta-iCVIs: Ensemble Validity Metrics for Concise Labeling of Correct, Under- or Over-Partitioning in Streaming Clustering}",
+    year = "2022",
+    month = "12",
+    url = "https://doi.org/10.36227/techrxiv.21685214",
+    doi = "10.36227/techrxiv.21685214"
 }
 ```