easyclassifier 0.8.1__tar.gz → 0.8.2__tar.gz

{easyclassifier-0.8.1/src/easyclassifier.egg-info → easyclassifier-0.8.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: easyclassifier
-Version: 0.8.1
+Version: 0.8.2
 Summary: Machine learning classification without programming - a guided, menu-driven wizard.
 Author-email: Ahmad Hassanat <ahmad.hassanat@gmail.com>
 License-Expression: MIT
@@ -40,6 +40,7 @@ Dynamic: license-file
 [![PyPI](https://img.shields.io/pypi/v/easyclassifier.svg)](https://pypi.org/project/easyclassifier/)
 [![Python](https://img.shields.io/badge/python-3.10%E2%80%933.14-blue.svg)](https://www.python.org/)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/ahmadhassant/easyclassifier/blob/main/LICENSE)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.23122901.svg)](https://doi.org/10.5281/zenodo.23122901)
 
 **Machine Learning without Programming.**
 
@@ -48,6 +49,11 @@ evaluate machine learning classification models from a CSV or Excel file —
 no Python code, no scripting, and no machine learning jargon required
 (unless you want it).
 
+Regression, time-series forecasting, signal classification and a Windows
+desktop application that runs all four tasks are in
+[EasyResearch](https://github.com/ahmadhassant/easyresearch), which is built
+on EasyClassifier and follows the same rules.
+
 **New to Python or the terminal? Read the step-by-step
 [User Guide](https://github.com/ahmadhassant/easyclassifier/blob/main/docs/USER_GUIDE.md).** It covers installing Python, installing
 EasyClassifier, running it, what each question means, and what the results
@@ -222,8 +228,14 @@ The report says whether the normal form (all values >= 0) or the signed form
 (negative values present) of the formula was applied, and the citation is
 shown on screen and saved to `citations.txt`:
 
-> Hassanat, A. B. (2014). Dimensionality Invariant Similarity Measure.
-> Journal of American Science, 10(8). arXiv:1409.0923.
+> Hassanat, A. B., Alkafaween, E., Tarawneh, A. S., & Elmougy, S. (2022).
+> Applications review of Hassanat distance metric. In *2022 International
+> Conference on Emerging Trends in Computing and Engineering Applications
+> (ETCEA)*, Karak, Jordan (pp. 1–6). IEEE.
+> https://doi.org/10.1109/ETCEA57049.2022.10009844
+>
+> Hassanat, A. B. (2014). Dimensionality invariant similarity measure.
+> arXiv preprint arXiv:1409.0923. https://arxiv.org/abs/1409.0923
 
 ## Benchmarks
 
@@ -254,7 +266,7 @@ can see the whole workflow immediately.
 ## Citing
 
 If you use EasyClassifier in published work, please cite it (GitHub's
-"Cite this repository" button uses [`CITATION.cff`](CITATION.cff)); each
+"Cite this repository" button uses [`CITATION.cff`](https://github.com/ahmadhassant/easyclassifier/blob/main/CITATION.cff)); each
 run also writes the exact references to `citations.txt`.
 
 ## Contributing

{easyclassifier-0.8.1 → easyclassifier-0.8.2}/README.md

@@ -4,6 +4,7 @@
 [![PyPI](https://img.shields.io/pypi/v/easyclassifier.svg)](https://pypi.org/project/easyclassifier/)
 [![Python](https://img.shields.io/badge/python-3.10%E2%80%933.14-blue.svg)](https://www.python.org/)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/ahmadhassant/easyclassifier/blob/main/LICENSE)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.23122901.svg)](https://doi.org/10.5281/zenodo.23122901)
 
 **Machine Learning without Programming.**
 
@@ -12,6 +13,11 @@ evaluate machine learning classification models from a CSV or Excel file —
 no Python code, no scripting, and no machine learning jargon required
 (unless you want it).
 
+Regression, time-series forecasting, signal classification and a Windows
+desktop application that runs all four tasks are in
+[EasyResearch](https://github.com/ahmadhassant/easyresearch), which is built
+on EasyClassifier and follows the same rules.
+
 **New to Python or the terminal? Read the step-by-step
 [User Guide](https://github.com/ahmadhassant/easyclassifier/blob/main/docs/USER_GUIDE.md).** It covers installing Python, installing
 EasyClassifier, running it, what each question means, and what the results
@@ -186,8 +192,14 @@ The report says whether the normal form (all values >= 0) or the signed form
 (negative values present) of the formula was applied, and the citation is
 shown on screen and saved to `citations.txt`:
 
-> Hassanat, A. B. (2014). Dimensionality Invariant Similarity Measure.
-> Journal of American Science, 10(8). arXiv:1409.0923.
+> Hassanat, A. B., Alkafaween, E., Tarawneh, A. S., & Elmougy, S. (2022).
+> Applications review of Hassanat distance metric. In *2022 International
+> Conference on Emerging Trends in Computing and Engineering Applications
+> (ETCEA)*, Karak, Jordan (pp. 1–6). IEEE.
+> https://doi.org/10.1109/ETCEA57049.2022.10009844
+>
+> Hassanat, A. B. (2014). Dimensionality invariant similarity measure.
+> arXiv preprint arXiv:1409.0923. https://arxiv.org/abs/1409.0923
 
 ## Benchmarks
 
@@ -218,7 +230,7 @@ can see the whole workflow immediately.
 ## Citing
 
 If you use EasyClassifier in published work, please cite it (GitHub's
-"Cite this repository" button uses [`CITATION.cff`](CITATION.cff)); each
+"Cite this repository" button uses [`CITATION.cff`](https://github.com/ahmadhassant/easyclassifier/blob/main/CITATION.cff)); each
 run also writes the exact references to `citations.txt`.
 
 ## Contributing

{easyclassifier-0.8.1 → easyclassifier-0.8.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "easyclassifier"
-version = "0.8.1"
+version = "0.8.2"
 description = "Machine learning classification without programming - a guided, menu-driven wizard."
 readme = "README.md"
 requires-python = ">=3.10"

{easyclassifier-0.8.1 → easyclassifier-0.8.2}/src/easyclassifier/__init__.py

@@ -4,12 +4,14 @@ A guided, menu-driven wizard that lets non-programmers build and evaluate
 classification models from a CSV file.
 """
 
-__version__ = "0.8.1"
+__version__ = "0.8.2"
 __author__ = "Ahmad Hassanat"
 
+# As in CITATION.cff and the user guide (Zenodo DOI).
 CITATION = (
-    "Hassanat, A. (2026). EasyClassifier: Machine Learning without "
-    "Programming (Version {version}) [Software].".format(version=__version__)
+    "Hassanat, A. B. A. (2026). EasyClassifier: Machine Learning without "
+    "Programming (Version {version}) [Software]. Zenodo. "
+    "https://doi.org/10.5281/zenodo.23122901".format(version=__version__)
 )
 
 from .wizard import Wizard  # noqa: E402

{easyclassifier-0.8.1 → easyclassifier-0.8.2}/src/easyclassifier/distances.py

@@ -23,12 +23,21 @@ from sklearn.base import BaseEstimator, ClassifierMixin
 from sklearn.neighbors import KNeighborsClassifier
 
 
+# The Hassanat distance is cited with the IEEE conference paper that reviews
+# its applications, and the arXiv preprint that introduced it.
 HASSANAT_CITATION = (
-    "Hassanat, A. B. (2014). Dimensionality Invariant Similarity Measure. "
-    "Journal of American Science, 10(8). arXiv:1409.0923."
+    "Hassanat, A. B., Alkafaween, E., Tarawneh, A. S., & Elmougy, S. (2022). "
+    "Applications review of Hassanat distance metric. In 2022 International "
+    "Conference on Emerging Trends in Computing and Engineering Applications "
+    "(ETCEA), Karak, Jordan (pp. 1-6). IEEE. "
+    "https://doi.org/10.1109/ETCEA57049.2022.10009844"
+)
+HASSANAT_ARXIV_CITATION = (
+    "Hassanat, A. B. (2014). Dimensionality invariant similarity measure. "
+    "arXiv preprint arXiv:1409.0923. https://arxiv.org/abs/1409.0923"
 )
 
-HASSANAT_CITATIONS: List[str] = [HASSANAT_CITATION]
+HASSANAT_CITATIONS: List[str] = [HASSANAT_CITATION, HASSANAT_ARXIV_CITATION]
 
 # key -> (menu label, sklearn metric name or None for custom)
 DISTANCES: Dict[str, tuple] = {

{easyclassifier-0.8.1 → easyclassifier-0.8.2}/src/easyclassifier/evaluation.py

@@ -32,7 +32,7 @@ METRICS = {
     "precision": "Precision",
     "recall": "Recall",
     "f1": "F1",
-    "specificity": "Specificity",
+    "specificity": "Macro specificity",
     "balanced_accuracy": "Balanced Accuracy",
     "mcc": "MCC",
     "cohen_kappa": "Cohen Kappa",

{easyclassifier-0.8.1 → easyclassifier-0.8.2}/src/easyclassifier/help_texts.py

@@ -14,8 +14,10 @@ GLOSSARY = {
               "items the model successfully found.",
     "f1": "F1 is a single score that balances precision and recall. It is "
           "high only when both are high.",
-    "specificity": "Specificity measures how many of the real negative items "
-                   "the model correctly labeled negative.",
+    "specificity": "Macro specificity: for each class, the share of items "
+                   "from the other classes that the model correctly did not "
+                   "put in that class, averaged over all classes. With two "
+                   "classes it equals balanced accuracy.",
     "sensitivity": "Sensitivity is another name for recall: how many real "
                    "positives the model found.",
     "mcc": "Matthews Correlation Coefficient summarises the whole confusion "

{easyclassifier-0.8.1 → easyclassifier-0.8.2}/src/easyclassifier/latex_report.py

@@ -25,15 +25,14 @@ from typing import Dict, List, Optional, Tuple
 
 import pandas as pd
 
-from .distances import HASSANAT_CITATION
+from . import references as refs
 from .evaluation import METRICS, SELECTION_LABEL, VALIDATION
 from .help_texts import explain
+from .references import cite
 
-SKLEARN_CITATION = ("Pedregosa, F., et al. (2011). Scikit-learn: Machine "
-                    "Learning in Python. Journal of Machine Learning "
-                    "Research, 12, 2825-2830.")
-BREIMAN_CITATION = ("Breiman, L. (2001). Random Forests. Machine Learning, "
-                    "45, 5-32.")
+# Kept for the EasyResearch cores, which import them from here.
+SKLEARN_CITATION = refs.REFERENCES["sklearn"]
+BREIMAN_CITATION = refs.REFERENCES["breiman2001"]
 
 PERCENT_METRICS = {"accuracy", "precision", "recall", "f1",
                    "balanced_accuracy", "specificity"}
@@ -76,6 +75,11 @@ class ReportContext:
     importance: Optional[pd.DataFrame] = None
     comparison_text: str = ""
     learning_text: str = ""
+    # Registry keys of the classifiers (same order as ``classifiers``) and the
+    # KNN distance, so that each method is cited.
+    classifier_keys: List[str] = field(default_factory=list)
+    knn_distance: Optional[str] = None
+    hassanat_signed: bool = False   # signed form applied (negative values)
 
 
 # --------------------------------------------------------------------------- #
@@ -195,7 +199,8 @@ def _methods_paragraph(c: ReportContext) -> str:
     parts = [
         f"Classification was carried out with EasyClassifier version "
         f"{tex(c.version)} \\cite{{easyclassifier}}, which is built on "
-        f"scikit-learn \\cite{{sklearn}}.",
+        f"scikit-learn \\cite{{sklearn}}, NumPy \\cite{{numpy}} and pandas "
+        f"\\cite{{pandas}}.",
         f"The dataset ({tex(c.dataset)}) contained {c.rows_loaded} rows and "
         f"{c.cols_loaded} columns. The outcome to predict was "
         f"\\emph{{{tex(c.target)}}} with {k} classes.",
@@ -243,14 +248,23 @@ def _methods_paragraph(c: ReportContext) -> str:
                      "separately within every validation split, so that no "
                      "information from test data entered model training.")
 
+    if len(c.classifier_keys) == len(c.classifiers):
+        named = [tex(n) + cite(refs.CLASSIFIER_REFERENCES.get(k, []))
+                 for n, k in zip(c.classifiers, c.classifier_keys)]
+    else:
+        named = [tex(n) for n in c.classifiers]
     parts.append(
         "The following classifiers were used with their default parameters, "
-        "without hyperparameter tuning: " + tex(_join(c.classifiers)) + ".")
+        "without hyperparameter tuning: " + _join(named) + ".")
     if c.knn_text:
-        cite = " \\cite{hassanat2014}" if c.hassanat_used else ""
-        parts.append(tex(c.knn_text) + cite + ".")
+        keys = refs.DISTANCE_REFERENCES.get(c.knn_distance or "", [])
+        if c.hassanat_used:
+            keys = refs.DISTANCE_REFERENCES["hassanat"] + (
+                refs.HASSANAT_SIGNED_REFERENCES if c.hassanat_signed else [])
+        parts.append(tex(c.knn_text) + cite(keys) + ".")
     parts.append(f"Performance was estimated with "
-                 f"{tex(VALIDATION[c.validation].lower())}.")
+                 f"{tex(VALIDATION[c.validation].lower())}"
+                 f"{cite(refs.VALIDATION_REFERENCES.get(c.validation, []))}.")
 
     if c.final is not None and c.selection == "final_test":
         parts.append(
@@ -259,7 +273,8 @@ def _methods_paragraph(c: ReportContext) -> str:
             f"{c.n_test} rows (20\\%, stratified by class) were set aside "
             f"before any analysis; classifiers were compared on the "
             f"remaining {c.n_dev} rows only, and the selected classifier was "
-            f"evaluated once on the untouched test rows.")
+            f"evaluated once on the untouched test rows"
+            f"{cite(refs.SELECTION_REFERENCES['final_test'])}.")
     elif c.final is not None and c.selection == "nested":
         parts.append(
             f"The classifier with the highest {SELECTION_LABEL.lower()} was "
@@ -267,7 +282,7 @@ def _methods_paragraph(c: ReportContext) -> str:
             f"performance was estimated with nested 5-fold cross-validation, "
             f"in which the complete comparison was repeated within each "
             f"outer training fold and the winner was evaluated on the outer "
-            f"test fold.")
+            f"test fold{cite(refs.SELECTION_REFERENCES['nested'])}.")
     if c.importance is not None:
         parts.append(
             "The contribution of each predictor was estimated by permutation "
@@ -275,6 +290,21 @@ def _methods_paragraph(c: ReportContext) -> str:
             f"{SELECTION_LABEL.lower()} when that column's values were "
             "randomly shuffled, measured on the "
             f"{tex(c.importance.attrs.get('measured_on', 'held-out rows'))}.")
+    measures = [tex(METRICS[m]) + cite(refs.METRIC_REFERENCES.get(m, []))
+                for m in c.metrics if m in METRICS]
+    parts.append(
+        f"Classifiers were ranked by {SELECTION_LABEL.lower()}"
+        f"{cite(refs.METRIC_REFERENCES['balanced_accuracy'])}"
+        + (f"; the measures reported were {_join(measures)}" if measures
+           else "") + ".")
+    if c.figures:
+        curves = [f"{label}{cite(refs.FIGURE_REFERENCES[k])}"
+                  for k, label in (("roc_curve", "ROC curves"),
+                                   ("pr_curve", "precision-recall curves"))
+                  if k in c.figures]
+        parts.append("Figures were drawn with Matplotlib \\cite{matplotlib}"
+                     + (", including " + _join(curves) if curves else "")
+                     + ".")
     return " ".join(parts)
 
 
@@ -471,16 +501,15 @@ def build_tex(c: ReportContext) -> str:
              "\\texttt{log.txt} in the Results folder.\n"
              "\\end{itemize}\n")
 
-    # 6. References --------------------------------------------------------- #
-    L.append("\\begin{thebibliography}{9}\n")
-    L.append(f"\\bibitem{{easyclassifier}} {tex(c.software_citation)}\n")
-    L.append(f"\\bibitem{{sklearn}} {tex(SKLEARN_CITATION)}\n")
-    if c.hassanat_used:
-        L.append(f"\\bibitem{{hassanat2014}} {tex(HASSANAT_CITATION)}\n")
-    if c.importance is not None:
-        L.append(f"\\bibitem{{breiman2001}} {tex(BREIMAN_CITATION)}\n")
-    L.append("\\end{thebibliography}\n\\end{document}\n")
-    return "".join(L)
+    # 6. References: every reference cited above, in order of citation ----- #
+    body = "".join(L)
+    return (body + refs.bibliography(body, report_entries(c), escape=tex)
+            + "\\end{document}\n")
+
+
+def report_entries(c: ReportContext) -> Dict[str, str]:
+    """Report-specific bibliography entries (the software itself)."""
+    return {"easyclassifier": c.software_citation}
 
 
 # --------------------------------------------------------------------------- #

easyclassifier-0.8.2/src/easyclassifier/references.py

@@ -0,0 +1,284 @@
+"""References for every method a report can mention.
+
+Each report cites, in its Methods paragraph, the software and every method
+that was actually used: the classifiers (or other models), the KNN distance,
+the evaluation design, the measures and the figures that need a source. The
+bibliography and ``citations.txt`` are generated from the ``\\cite{...}``
+commands in the finished report, so a reference is listed exactly when it is
+cited, and nothing that is cited can be missing.
+
+The EasyResearch cores (regression, forecasting, signal classification)
+extend this list with the references of their own models.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Dict, Iterable, List, Optional
+
+from .distances import HASSANAT_ARXIV_CITATION, HASSANAT_CITATION
+
+# --------------------------------------------------------------------------- #
+# Reference texts
+# --------------------------------------------------------------------------- #
+
+REFERENCES: Dict[str, str] = {
+    # Software
+    "sklearn": "Pedregosa, F., et al. (2011). Scikit-learn: Machine "
+               "Learning in Python. Journal of Machine Learning Research, "
+               "12, 2825-2830.",
+    "numpy": "Harris, C. R., Millman, K. J., van der Walt, S. J., et al. "
+             "(2020). Array programming with NumPy. Nature, 585(7825), "
+             "357-362. https://doi.org/10.1038/s41586-020-2649-2",
+    "pandas": "McKinney, W. (2010). Data structures for statistical "
+              "computing in Python. In Proceedings of the 9th Python in "
+              "Science Conference (pp. 56-61). "
+              "https://doi.org/10.25080/Majora-92bf1922-00a",
+    "matplotlib": "Hunter, J. D. (2007). Matplotlib: A 2D graphics "
+                  "environment. Computing in Science & Engineering, 9(3), "
+                  "90-95. https://doi.org/10.1109/MCSE.2007.55",
+    # Classifiers
+    "breiman1984": "Breiman, L., Friedman, J. H., Olshen, R. A., & Stone, "
+                   "C. J. (1984). Classification and Regression Trees. "
+                   "Wadsworth.",
+    "breiman2001": "Breiman, L. (2001). Random Forests. Machine Learning, "
+                   "45, 5-32. https://doi.org/10.1023/A:1010933404324",
+    "cortes1995": "Cortes, C., & Vapnik, V. (1995). Support-vector "
+                  "networks. Machine Learning, 20(3), 273-297. "
+                  "https://doi.org/10.1007/BF00994018",
+    "platt1999": "Platt, J. C. (1999). Probabilistic outputs for support "
+                 "vector machines and comparisons to regularized likelihood "
+                 "methods. In A. J. Smola, P. Bartlett, B. Schölkopf, & "
+                 "D. Schuurmans (Eds.), Advances in Large Margin Classifiers "
+                 "(pp. 61-74). MIT Press.",
+    "cox1958": "Cox, D. R. (1958). The regression analysis of binary "
+               "sequences. Journal of the Royal Statistical Society: Series "
+               "B, 20(2), 215-242. "
+               "https://doi.org/10.1111/j.2517-6161.1958.tb00292.x",
+    "cover1967": "Cover, T., & Hart, P. (1967). Nearest neighbor pattern "
+                 "classification. IEEE Transactions on Information Theory, "
+                 "13(1), 21-27. https://doi.org/10.1109/TIT.1967.1053964",
+    "hand2001": "Hand, D. J., & Yu, K. (2001). Idiot's Bayes - not so "
+                "stupid after all? International Statistical Review, 69(3), "
+                "385-398. "
+                "https://doi.org/10.1111/j.1751-5823.2001.tb00465.x",
+    "chen2016": "Chen, T., & Guestrin, C. (2016). XGBoost: A scalable tree "
+                "boosting system. In Proceedings of the 22nd ACM SIGKDD "
+                "International Conference on Knowledge Discovery and Data "
+                "Mining (pp. 785-794). "
+                "https://doi.org/10.1145/2939672.2939785",
+    "ke2017": "Ke, G., Meng, Q., Finley, T., Wang, T., Chen, W., Ma, W., "
+              "Ye, Q., & Liu, T.-Y. (2017). LightGBM: A highly efficient "
+              "gradient boosting decision tree. In Advances in Neural "
+              "Information Processing Systems 30 (pp. 3146-3154).",
+    "rumelhart1986": "Rumelhart, D. E., Hinton, G. E., & Williams, R. J. "
+                     "(1986). Learning representations by back-propagating "
+                     "errors. Nature, 323(6088), 533-536. "
+                     "https://doi.org/10.1038/323533a0",
+    "kingma2015": "Kingma, D. P., & Ba, J. (2015). Adam: A method for "
+                  "stochastic optimization. In International Conference on "
+                  "Learning Representations (ICLR). arXiv:1412.6980.",
+    # Distances
+    "hassanat2022": HASSANAT_CITATION,
+    "hassanat2014": HASSANAT_ARXIV_CITATION,
+    "alaydaa2026": "Alaydaa, M. S., Alotibi, G. N., Tarawneh, A. S., & "
+                   "Hassanat, A. B. (2026). A sign-symmetric reformulation "
+                   "of the Hassanat distance for data with negative feature "
+                   "values. Symmetry, 18(7), 1225. "
+                   "https://doi.org/10.3390/sym18071225",
+    "lance1966": "Lance, G. N., & Williams, W. T. (1966). Computer programs "
+                 "for hierarchical polythetic classification (\"similarity "
+                 "analyses\"). The Computer Journal, 9(1), 60-64. "
+                 "https://doi.org/10.1093/comjnl/9.1.60",
+    "deza2009": "Deza, M. M., & Deza, E. (2009). Encyclopedia of Distances. "
+                "Springer. https://doi.org/10.1007/978-3-642-00234-2",
+    # Evaluation
+    "kohavi1995": "Kohavi, R. (1995). A study of cross-validation and "
+                  "bootstrap for accuracy estimation and model selection. In "
+                  "Proceedings of the 14th International Joint Conference on "
+                  "Artificial Intelligence (IJCAI) (pp. 1137-1143).",
+    "lachenbruch1968": "Lachenbruch, P. A., & Mickey, M. R. (1968). "
+                       "Estimation of error rates in discriminant analysis. "
+                       "Technometrics, 10(1), 1-11. "
+                       "https://doi.org/10.1080/00401706.1968.10490530",
+    "varma2006": "Varma, S., & Simon, R. (2006). Bias in error estimation "
+                 "when using cross-validation for model selection. BMC "
+                 "Bioinformatics, 7, 91. "
+                 "https://doi.org/10.1186/1471-2105-7-91",
+    "cawley2010": "Cawley, G. C., & Talbot, N. L. C. (2010). On over-fitting "
+                  "in model selection and subsequent selection bias in "
+                  "performance evaluation. Journal of Machine Learning "
+                  "Research, 11, 2079-2107.",
+    # Measures
+    "brodersen2010": "Brodersen, K. H., Ong, C. S., Stephan, K. E., & "
+                     "Buhmann, J. M. (2010). The balanced accuracy and its "
+                     "posterior distribution. In 20th International "
+                     "Conference on Pattern Recognition (pp. 3121-3124). "
+                     "IEEE. https://doi.org/10.1109/ICPR.2010.764",
+    "matthews1975": "Matthews, B. W. (1975). Comparison of the predicted and "
+                    "observed secondary structure of T4 phage lysozyme. "
+                    "Biochimica et Biophysica Acta - Protein Structure, "
+                    "405(2), 442-451. "
+                    "https://doi.org/10.1016/0005-2795(75)90109-9",
+    "cohen1960": "Cohen, J. (1960). A coefficient of agreement for nominal "
+                 "scales. Educational and Psychological Measurement, 20(1), "
+                 "37-46. https://doi.org/10.1177/001316446002000104",
+    "fawcett2006": "Fawcett, T. (2006). An introduction to ROC analysis. "
+                   "Pattern Recognition Letters, 27(8), 861-874. "
+                   "https://doi.org/10.1016/j.patrec.2005.10.010",
+    "davis2006": "Davis, J., & Goadrich, M. (2006). The relationship between "
+                 "precision-recall and ROC curves. In Proceedings of the "
+                 "23rd International Conference on Machine Learning "
+                 "(pp. 233-240). https://doi.org/10.1145/1143844.1143874",
+}
+
+# What each reference is cited for (shown in citations.txt).
+TOPICS: Dict[str, str] = {
+    "sklearn": "scikit-learn (models, preprocessing and evaluation)",
+    "numpy": "NumPy (numerical computing)",
+    "pandas": "pandas (data handling)",
+    "matplotlib": "Matplotlib (figures)",
+    "breiman1984": "Decision tree (CART)",
+    "breiman2001": "Random Forest; permutation importance",
+    "cortes1995": "Support vector machine",
+    "platt1999": "SVM probability estimates (Platt scaling)",
+    "cox1958": "Logistic regression",
+    "cover1967": "K-nearest neighbours",
+    "hand2001": "Naive Bayes",
+    "chen2016": "XGBoost",
+    "ke2017": "LightGBM; histogram-based gradient boosting",
+    "rumelhart1986": "Neural network (multilayer perceptron, backpropagation)",
+    "kingma2015": "Adam optimiser (neural network training)",
+    "hassanat2022": "Hassanat distance",
+    "hassanat2014": "Hassanat distance (original preprint)",
+    "alaydaa2026": "Signed form of the Hassanat distance (negative values)",
+    "lance1966": "Canberra distance",
+    "deza2009": "Distance measures (Euclidean, Manhattan, Chebyshev, cosine)",
+    "kohavi1995": "Stratified k-fold cross-validation",
+    "lachenbruch1968": "Leave-one-out validation",
+    "varma2006": "Nested cross-validation",
+    "cawley2010": "Selection bias and separate final evaluation",
+    "brodersen2010": "Balanced accuracy",
+    "matthews1975": "Matthews correlation coefficient (MCC)",
+    "cohen1960": "Cohen's kappa",
+    "fawcett2006": "ROC curves and ROC AUC",
+    "davis2006": "Precision-recall curves",
+}
+
+# --------------------------------------------------------------------------- #
+# Which references go with which choice
+# --------------------------------------------------------------------------- #
+
+SOFTWARE = ["sklearn", "numpy", "pandas"]
+
+CLASSIFIER_REFERENCES: Dict[str, List[str]] = {
+    "decision_tree": ["breiman1984"],
+    "random_forest": ["breiman2001"],
+    "svm": ["cortes1995", "platt1999"],
+    "logistic_regression": ["cox1958"],
+    "knn": ["cover1967"],
+    "naive_bayes": ["hand2001"],
+    "xgboost": ["chen2016"],
+    "lightgbm": ["ke2017"],
+    "neural_network": ["rumelhart1986", "kingma2015"],
+}
+
+DISTANCE_REFERENCES: Dict[str, List[str]] = {
+    "hassanat": ["hassanat2022", "hassanat2014"],
+    "euclidean": ["deza2009"],
+    "manhattan": ["deza2009"],
+    "chebyshev": ["deza2009"],
+    "canberra": ["lance1966"],
+    "cosine": ["deza2009"],
+}
+
+# Cited in addition when the signed form of the Hassanat formula was applied
+# (some values negative).
+HASSANAT_SIGNED_REFERENCES = ["alaydaa2026"]
+
+VALIDATION_REFERENCES: Dict[str, List[str]] = {
+    "holdout": [],
+    "kfold5": ["kohavi1995"],
+    "kfold10": ["kohavi1995"],
+    "stratified": ["kohavi1995"],
+    "loo": ["lachenbruch1968"],
+}
+
+SELECTION_REFERENCES: Dict[str, List[str]] = {
+    "nested": ["varma2006", "cawley2010"],
+    "final_test": ["cawley2010"],
+}
+
+# Measures that need a source (accuracy, precision, recall, F1, specificity
+# and log loss are standard definitions).
+METRIC_REFERENCES: Dict[str, List[str]] = {
+    "balanced_accuracy": ["brodersen2010"],
+    "mcc": ["matthews1975"],
+    "cohen_kappa": ["cohen1960"],
+    "roc_auc": ["fawcett2006"],
+}
+
+FIGURE_REFERENCES: Dict[str, List[str]] = {
+    "roc_curve": ["fawcett2006"],
+    "pr_curve": ["davis2006"],
+}
+
+# --------------------------------------------------------------------------- #
+# Helpers
+# --------------------------------------------------------------------------- #
+
+_CITE = re.compile(r"\\cite\{([^}]*)\}")
+
+
+def cite(keys: Iterable[str]) -> str:
+    """`` \\cite{a,b}`` for the given keys (in order, without repeats), or an
+    empty string when there are none."""
+    keys = list(dict.fromkeys(k for k in keys if k))
+    return f" \\cite{{{','.join(keys)}}}" if keys else ""
+
+
+def cited_keys(text: str) -> List[str]:
+    """Every key cited in a LaTeX text, in order of first citation."""
+    keys: List[str] = []
+    for group in _CITE.findall(text):
+        for k in group.split(","):
+            k = k.strip()
+            if k and k not in keys:
+                keys.append(k)
+    return keys
+
+
+def lookup(key: str, extra: Optional[Dict[str, str]] = None) -> str:
+    if extra and key in extra:
+        return extra[key]
+    if key in REFERENCES:
+        return REFERENCES[key]
+    raise KeyError(f"no reference text for \\cite{{{key}}}")
+
+
+def bibliography(text: str, extra: Optional[Dict[str, str]] = None,
+                 escape=lambda s: s) -> str:
+    """The ``thebibliography`` block for every key cited in ``text``, in
+    order of first citation. ``extra`` holds report-specific entries (the
+    software itself, the dataset). A cited key without a text raises an
+    error, so a report can never cite a reference it does not list."""
+    keys = cited_keys(text)
+    lines = ["\\begin{thebibliography}{99}\n"]
+    lines += [f"\\bibitem{{{k}}} {escape(lookup(k, extra))}\n" for k in keys]
+    lines.append("\\end{thebibliography}\n")
+    return "".join(lines)
+
+
+def citation_lines(text: str, extra: Optional[Dict[str, str]] = None,
+                   topics: Optional[Dict[str, str]] = None) -> List[str]:
+    """``citations.txt``: every reference cited in the report, with what it
+    is cited for."""
+    topics = dict(TOPICS, **(topics or {}))
+    lines = ["Please cite the following if you publish these results.",
+             "They are the references of the report (report.tex), in the "
+             "order they are cited there.", ""]
+    for i, k in enumerate(cited_keys(text), 1):
+        what = topics.get(k)
+        lines.append(f"[{i}] " + (f"{what}:" if what else ""))
+        lines.append("    " + lookup(k, extra))
+    return lines

{easyclassifier-0.8.1 → easyclassifier-0.8.2}/src/easyclassifier/wizard.py

@@ -29,7 +29,9 @@ from .diagnostics import (
     learning_curve_data,
 )
 from .importance import honest_importance
-from .latex_report import ReportContext, write_and_compile
+from .latex_report import (ReportContext, build_tex, report_entries,
+                           write_and_compile)
+from .references import citation_lines
 from .help_texts import explain
 from .logbook import LogBook
 from .models import build_registry
@@ -1076,14 +1078,22 @@ class Wizard:
         saved.append(rep.save_model(
             model, os.path.join(out_dir, "trained_model.pkl")))
 
+        # citations.txt lists exactly the references cited in the report.
+        try:
+            ctx = self._report_context(best, results, final, X, y,
+                                       fig_files, importance)
+        except Exception as exc:  # noqa: BLE001
+            ctx = None
+            self.log.add(f"Report context FAILED: {exc}")
         saved.append(self.save_citations(os.path.join(out_dir,
-                                                      "citations.txt")))
+                                                      "citations.txt"), ctx))
 
         # Report: report.tex, compiled to report.pdf if LaTeX is installed.
         ui.info("Writing the report ...")
         try:
-            ctx = self._report_context(best, results, final, X, y,
-                                       fig_files, importance)
+            if ctx is None:
+                raise RuntimeError("the report information could not be "
+                                   "collected (see the log)")
             tex_path, pdf_path, msg = write_and_compile(ctx, out_dir)
             saved.append(tex_path)
             if pdf_path:
@@ -1212,6 +1222,10 @@ class Wizard:
             comparison_text=self.comparison_text,
             learning_text=self.learning_text,
             importance=importance,
+            classifier_keys=list(self._classifiers),
+            knn_distance=self.knn_distance,
+            hassanat_signed=bool(self.hassanat_form
+                                 and self.hassanat_form["form"] == "signed"),
         )
 
     def _pipeline_spec(self, key: str, X):
@@ -1223,13 +1237,20 @@ class Wizard:
             factory=lambda: pp.build_pipeline(X, cfg, spec.factory(), scale),
         )
 
-    def save_citations(self, path: str) -> str:
-        lines = ["Please cite the following if you publish these results:",
-                 "", "Software:", "  " + CITATION]
+    def save_citations(self, path: str, ctx=None) -> str:
+        if ctx is not None:
+            lines = citation_lines(build_tex(ctx), report_entries(ctx),
+                                   {"easyclassifier": "EasyClassifier "
+                                                      "(this software)"})
+        else:
+            lines = ["Please cite the following if you publish these "
+                     "results:", "", "Software:", "  " + CITATION]
         if self.hassanat_form:
-            lines += ["", "Hassanat distance (used by KNN):"]
-            lines += ["  " + c for c in HASSANAT_CITATIONS]
-            lines += ["", "Formula form applied: " + self.hassanat_form["text"]]
+            if ctx is None:
+                lines += ["", "Hassanat distance (used by KNN):"]
+                lines += ["  " + c for c in HASSANAT_CITATIONS]
+            lines += ["", "Hassanat distance, formula form applied: "
+                      + self.hassanat_form["text"]]
         with open(path, "w", encoding="utf-8") as fh:
             fh.write("\n".join(lines) + "\n")
         return path

{easyclassifier-0.8.1 → easyclassifier-0.8.2/src/easyclassifier.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: easyclassifier
-Version: 0.8.1
+Version: 0.8.2
 Summary: Machine learning classification without programming - a guided, menu-driven wizard.
 Author-email: Ahmad Hassanat <ahmad.hassanat@gmail.com>
 License-Expression: MIT
@@ -40,6 +40,7 @@ Dynamic: license-file
 [![PyPI](https://img.shields.io/pypi/v/easyclassifier.svg)](https://pypi.org/project/easyclassifier/)
 [![Python](https://img.shields.io/badge/python-3.10%E2%80%933.14-blue.svg)](https://www.python.org/)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/ahmadhassant/easyclassifier/blob/main/LICENSE)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.23122901.svg)](https://doi.org/10.5281/zenodo.23122901)
 
 **Machine Learning without Programming.**
 
@@ -48,6 +49,11 @@ evaluate machine learning classification models from a CSV or Excel file —
 no Python code, no scripting, and no machine learning jargon required
 (unless you want it).
 
+Regression, time-series forecasting, signal classification and a Windows
+desktop application that runs all four tasks are in
+[EasyResearch](https://github.com/ahmadhassant/easyresearch), which is built
+on EasyClassifier and follows the same rules.
+
 **New to Python or the terminal? Read the step-by-step
 [User Guide](https://github.com/ahmadhassant/easyclassifier/blob/main/docs/USER_GUIDE.md).** It covers installing Python, installing
 EasyClassifier, running it, what each question means, and what the results
@@ -222,8 +228,14 @@ The report says whether the normal form (all values >= 0) or the signed form
 (negative values present) of the formula was applied, and the citation is
 shown on screen and saved to `citations.txt`:
 
-> Hassanat, A. B. (2014). Dimensionality Invariant Similarity Measure.
-> Journal of American Science, 10(8). arXiv:1409.0923.
+> Hassanat, A. B., Alkafaween, E., Tarawneh, A. S., & Elmougy, S. (2022).
+> Applications review of Hassanat distance metric. In *2022 International
+> Conference on Emerging Trends in Computing and Engineering Applications
+> (ETCEA)*, Karak, Jordan (pp. 1–6). IEEE.
+> https://doi.org/10.1109/ETCEA57049.2022.10009844
+>
+> Hassanat, A. B. (2014). Dimensionality invariant similarity measure.
+> arXiv preprint arXiv:1409.0923. https://arxiv.org/abs/1409.0923
 
 ## Benchmarks
 
@@ -254,7 +266,7 @@ can see the whole workflow immediately.
 ## Citing
 
 If you use EasyClassifier in published work, please cite it (GitHub's
-"Cite this repository" button uses [`CITATION.cff`](CITATION.cff)); each
+"Cite this repository" button uses [`CITATION.cff`](https://github.com/ahmadhassant/easyclassifier/blob/main/CITATION.cff)); each
 run also writes the exact references to `citations.txt`.
 
 ## Contributing

{easyclassifier-0.8.1 → easyclassifier-0.8.2}/src/easyclassifier.egg-info/SOURCES.txt

@@ -16,6 +16,7 @@ src/easyclassifier/logbook.py
 src/easyclassifier/models.py
 src/easyclassifier/preprocessing.py
 src/easyclassifier/recommend.py
+src/easyclassifier/references.py
 src/easyclassifier/reporting.py
 src/easyclassifier/target.py
 src/easyclassifier/ui.py
@@ -29,6 +30,7 @@ src/easyclassifier.egg-info/top_level.txt
 tests/test_figures.py
 tests/test_first_run.py
 tests/test_leakage.py
+tests/test_references.py
 tests/test_report.py
 tests/test_selection.py
 tests/test_target.py

easyclassifier-0.8.2/tests/test_references.py

@@ -0,0 +1,77 @@
+"""Every method the tool can use is cited in the report, and the
+bibliography lists exactly the cited references."""
+
+import re
+
+from easyclassifier import references as refs
+from easyclassifier.distances import DISTANCES
+from easyclassifier.evaluation import METRICS, SELECTION, VALIDATION
+from easyclassifier.latex_report import build_tex
+from easyclassifier.models import build_registry
+
+# Measures with a standard definition that need no source.
+STANDARD_MEASURES = {"accuracy", "precision", "recall", "f1", "specificity",
+                     "log_loss"}
+
+
+def test_every_choice_has_its_references():
+    assert set(build_registry()) <= set(refs.CLASSIFIER_REFERENCES)
+    assert all(refs.CLASSIFIER_REFERENCES[k] for k in build_registry())
+    assert set(DISTANCES) == set(refs.DISTANCE_REFERENCES)
+    assert set(VALIDATION) == set(refs.VALIDATION_REFERENCES)
+    assert set(SELECTION) - {"auto"} == set(refs.SELECTION_REFERENCES)
+    assert set(METRICS) == set(refs.METRIC_REFERENCES) | STANDARD_MEASURES
+    tables = [refs.CLASSIFIER_REFERENCES, refs.DISTANCE_REFERENCES,
+              refs.VALIDATION_REFERENCES, refs.SELECTION_REFERENCES,
+              refs.METRIC_REFERENCES, refs.FIGURE_REFERENCES]
+    keys = {k for t in tables for v in t.values() for k in v} | set(refs.SOFTWARE)
+    assert keys <= set(refs.REFERENCES)
+    assert set(refs.REFERENCES) <= set(refs.TOPICS)
+    assert not any("Journal of American Science" in r
+                   for r in refs.REFERENCES.values())
+
+
+def test_bibliography_lists_exactly_the_cited_references():
+    text = r"A \cite{sklearn,breiman2001} B \cite{own} C \cite{breiman2001}."
+    bib = refs.bibliography(text, {"own": "Own, A. (2026). Data."})
+    assert re.findall(r"\\bibitem\{([^}]*)\}", bib) == \
+        ["sklearn", "breiman2001", "own"]
+    try:
+        refs.bibliography(r"\cite{nowhere}")
+    except KeyError as exc:
+        assert "nowhere" in str(exc)
+    else:
+        raise AssertionError("an unknown citation must not pass silently")
+    lines = refs.citation_lines(text, {"own": "Own, A. (2026). Data."})
+    assert sum(line.startswith("[") for line in lines) == 3
+
+
+def test_report_cites_each_classifier_measure_and_evaluation():
+    from test_report import _context
+    c = _context()
+    c.classifiers = ["Decision Tree", "XGBoost", "LightGBM",
+                     "KNN (Canberra, k=5)"]
+    c.classifier_keys = ["decision_tree", "xgboost", "lightgbm", "knn"]
+    c.knn_text, c.knn_distance = "K-nearest neighbours used k = 5", "canberra"
+    c.metrics = ["accuracy", "balanced_accuracy", "mcc", "cohen_kappa"]
+    c.selection = "nested"
+    c.final = c.results[0]
+    doc = build_tex(c)
+    cited = refs.cited_keys(doc.split(r"\begin{thebibliography}")[0])
+    for key in ("breiman1984", "chen2016", "ke2017", "cover1967", "lance1966",
+                "kohavi1995", "varma2006", "brodersen2010", "matthews1975",
+                "cohen1960", "sklearn", "numpy", "pandas"):
+        assert key in cited, key
+    assert re.findall(r"\\bibitem\{([^}]*)\}", doc) == cited
+
+
+def test_signed_hassanat_form_cites_the_sign_symmetric_paper():
+    from test_report import _context
+    for signed in (False, True):
+        c = _context()
+        c.classifiers, c.classifier_keys = ["KNN (Hassanat, k=5)"], ["knn"]
+        c.knn_text, c.knn_distance = "K-nearest neighbours used k = 5", "hassanat"
+        c.hassanat_used, c.hassanat_signed = True, signed
+        cited = refs.cited_keys(build_tex(c))
+        assert {"hassanat2022", "hassanat2014"} <= set(cited)
+        assert ("alaydaa2026" in cited) == signed

{easyclassifier-0.8.1 → easyclassifier-0.8.2}/tests/test_report.py

@@ -108,3 +108,24 @@ def test_report_compiles_to_pdf(tmp_path):
     assert pdf_path is not None, msg
     assert (tmp_path / "report.pdf").stat().st_size > 10_000
     assert not (tmp_path / "report.aux").exists()      # cleaned up
+
+
+def test_specificity_is_macro_average():
+    """Reported specificity is one-versus-rest specificity averaged over
+    classes; with two classes it equals balanced accuracy."""
+    import numpy as np
+    from sklearn.metrics import balanced_accuracy_score
+    from easyclassifier.evaluation import METRICS, _specificity
+    from easyclassifier.help_texts import GLOSSARY
+
+    y_true = np.array([0, 0, 0, 0, 1, 1, 1, 1, 1, 1])
+    y_pred = np.array([0, 0, 1, 1, 1, 1, 1, 1, 1, 0])
+    assert np.isclose(_specificity(y_true, y_pred, [0, 1]),
+                      balanced_accuracy_score(y_true, y_pred))
+
+    y3 = np.array([0, 0, 1, 1, 2, 2])
+    p3 = np.array([0, 1, 1, 1, 2, 0])
+    # one-vs-rest specificities: class 0: 3/4, class 1: 3/4, class 2: 4/4
+    assert np.isclose(_specificity(y3, p3, [0, 1, 2]), (0.75 + 0.75 + 1) / 3)
+    assert METRICS["specificity"] == "Macro specificity"
+    assert "averaged over all classes" in GLOSSARY["specificity"]