easyresearch 0.1.0__py3-none-any.whl

easyresearch/__init__.py

@@ -0,0 +1,28 @@
+"""EasyResearch - machine learning without programming.
+
+Analysis cores that share EasyClassifier's rules (leakage-free preparation,
+default parameters with fixed seeds, honest final scores, plain-language
+reports):
+
+* ``easyresearch.regression``  - predict a number from a table
+* ``easyresearch.timeseries``  - forecast a series; classify recordings
+  (ECG, EEG, sensor signals)
+* classification is provided by the EasyClassifier package (0.8.2)
+
+The cores have no user interaction: settings go in, results and files come
+out, so a terminal wizard, the desktop application or a web server can drive
+them in the same way.
+"""
+
+__version__ = "0.1.0"
+__author__ = "Ahmad Hassanat"
+
+CITATION = (
+    "Hassanat, A. B. A. (2026). EasyResearch: Machine Learning without "
+    "Programming (Version {version}) [Software]. "
+    "https://github.com/ahmadhassant/easyresearch".format(version=__version__)
+)
+EASYCLASSIFIER_CITATION = (
+    "Hassanat, A. B. A. (2026). EasyClassifier: Machine Learning without "
+    "Programming (Version 0.8.2) [Software]. Zenodo. "
+    "https://doi.org/10.5281/zenodo.23122901")

easyresearch/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

easyresearch/cli.py

@@ -0,0 +1,165 @@
+"""Command line for the EasyResearch cores (no programming needed beyond one
+command). Examples::
+
+    easyresearch forecast sales.csv --value Sales --horizon 12
+    easyresearch forecast --demo
+    easyresearch regress houses.xlsx --target Price
+    easyresearch signals ECG200_TRAIN.tsv --label label
+    easyresearch models forecast           # list the available models
+    easyresearch regress --demo --figures residuals,comparison --figure-format png+pdf
+
+Results are written to a new folder inside ./Results (or --out).
+A terminal wizard and the desktop/web interfaces will drive the same cores.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from pathlib import Path
+
+from . import __version__
+
+
+def _models(arg, registry):
+    if not arg:
+        return None
+    if arg == "all":
+        return [k for k, s in registry.items() if getattr(s, "available", True)]
+    return [m.strip() for m in arg.split(",") if m.strip()]
+
+
+def _figure_settings(st, a):
+    """Figure colours, file formats and the figures to draw (default: the
+    task's usual set)."""
+    st.figure_theme, st.figure_format = a.figure_theme, a.figure_format
+    if a.figures:
+        st.figure_keys = [k.strip() for k in a.figures.split(",") if k.strip()]
+    return st
+
+
+def main(argv=None) -> int:
+    from easyclassifier.figures import DEFAULT_THEME, FORMATS, THEMES
+    p = argparse.ArgumentParser(prog="easyresearch",
+                                description="Machine learning without "
+                                "programming - analysis cores.")
+    p.add_argument("--version", action="version",
+                   version=f"EasyResearch {__version__}")
+    sub = p.add_subparsers(dest="task", required=True)
+
+    for name, help_ in (("forecast", "forecast one time series"),
+                        ("regress", "predict a number from a table"),
+                        ("signals", "classify recordings (ECG, EEG, ...)")):
+        s = sub.add_parser(name, help=help_)
+        s.add_argument("data", nargs="?", help="CSV, Excel or UCR .tsv file")
+        s.add_argument("--demo", action="store_true",
+                       help="use the built-in example data")
+        s.add_argument("--models", help="comma-separated model ids, or 'all'"
+                       " (default: the fast set)")
+        s.add_argument("--out", default=".", help="folder for Results/")
+        s.add_argument("--no-figures", action="store_true")
+        s.add_argument("--figures", help="comma-separated figure names "
+                       "(default: the usual set; see the report's list)")
+        s.add_argument("--figure-theme", default=DEFAULT_THEME,
+                       choices=list(THEMES), help="figure colours")
+        s.add_argument("--figure-format", default="png", choices=list(FORMATS),
+                       help="figure files: png, png+pdf or png+svg")
+        if name == "forecast":
+            s.add_argument("--value", help="column to forecast")
+            s.add_argument("--time", help="date/time column (auto-detected)")
+            s.add_argument("--horizon", default="auto",
+                           help="steps ahead (default: automatic)")
+            s.add_argument("--metric", default="mase",
+                           choices=["mase", "rmse", "mae", "mhsp"],
+                           help="measure used to choose the model")
+        elif name == "regress":
+            s.add_argument("--target", help="numeric column to predict")
+        else:
+            s.add_argument("--label", help="column holding the class")
+    lm = sub.add_parser("models", help="list the models of a task")
+    lm.add_argument("which", choices=["forecast", "regress", "signals"])
+    a = p.parse_args(argv)
+
+    if a.task == "models":
+        if a.which == "forecast":
+            from .timeseries.models import build_registry
+        elif a.which == "regress":
+            from .regression.models import build_registry
+        else:
+            from .timeseries.signal_models import build_registry
+        for k, s in build_registry().items():
+            mark = "*" if getattr(s, "default_selected", False) else " "
+            print(f" {mark} {k:20s} {s.name}")
+        print("\n * = in the default (fast) set")
+        return 0
+
+    if not a.demo and not a.data:
+        p.error("give a data file or --demo")
+    out = os.path.abspath(a.out)
+    try:
+        if a.task == "forecast":
+            from .timeseries import ForecastSettings, run_forecast
+            from .timeseries import data as td
+            from .timeseries.models import build_registry
+            df = td.load_demo() if a.demo else _load(a.data)
+            value = a.value or ("CO2_ppm" if a.demo else td.suggest_value(df))
+            st = ForecastSettings(time_column=a.time, figures=not a.no_figures,
+                                  selection_metric=a.metric,
+                                  horizon=a.horizon if a.horizon == "auto"
+                                  else int(a.horizon))
+            st.models = _models(a.models, build_registry()) or st.models
+            _figure_settings(st, a)
+            r = run_forecast(df, value, st, out,
+                             td.DEMO_NAME if a.demo else Path(a.data).name,
+                             "demo_co2" if a.demo else Path(a.data).stem,
+                             td.DEMO_CITATION if a.demo else "")
+            head = f"Selected: {r['best'].name}"
+        elif a.task == "regress":
+            from .regression import Settings, run_analysis
+            from .regression import data as rd
+            from .regression.models import build_registry
+            df = rd.load_demo() if a.demo else _load(a.data)
+            target = a.target or rd.suggest_target(df)
+            reg = build_registry()
+            models = _models(a.models, reg) or [
+                k for k, s in reg.items() if s.default_selected]
+            st = _figure_settings(Settings(models=models,
+                                           figures=not a.no_figures), a)
+            r = run_analysis(df, target, st, out, rd.DEMO_NAME if a.demo else
+                             Path(a.data).name, "demo_diabetes" if a.demo
+                             else Path(a.data).stem,
+                             rd.DEMO_CITATION if a.demo else "")
+            head = f"Selected: {r['best'].name}"
+        else:
+            from .timeseries import signal_data as sd
+            from .timeseries.classify import (SignalSettings,
+                                              run_signal_classification)
+            from .timeseries.signal_models import build_registry
+            df = sd.load_demo() if a.demo else sd.load_table(a.data)
+            label = a.label or sd.suggest_label(df)
+            st = SignalSettings(figures=not a.no_figures)
+            st.models = _models(a.models, build_registry()) or st.models
+            _figure_settings(st, a)
+            r = run_signal_classification(
+                df, label, st, out, sd.DEMO_NAME if a.demo else
+                Path(a.data).name, "demo_heartbeats" if a.demo
+                else Path(a.data).stem)
+            head = f"Selected: {r['best'].classifier_name}"
+    except (ValueError, RuntimeError, FileNotFoundError) as exc:
+        print(f"\nCould not run the analysis: {exc}", file=sys.stderr)
+        return 1
+    print("\n" + head)
+    for line in r["summary"]:
+        print("  " + line)
+    print(f"\nAll results: {r['out']}")
+    return 0
+
+
+def _load(path):
+    from easyclassifier.dataset import clean_path, load_csv
+    return load_csv(clean_path(path))
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

easyresearch/common/__init__.py

@@ -0,0 +1 @@
+"""Pieces shared by all EasyResearch cores."""

easyresearch/common/hassanat.py

@@ -0,0 +1,70 @@
+"""Hassanat similarity and the MHSP measure.
+
+Hassanat similarity between two values a and b (per dimension of the
+Hassanat distance, which is 1 minus this similarity):
+
+    if min(a, b) >= 0:   S = (1 + min) / (1 + max)
+    if min(a, b) <  0:   S = (1 + min + |min|) / (1 + max + |min|)
+
+S is 1 when a == b and approaches 0 as they move apart, so a single large
+error cannot dominate an average of similarities.
+
+MHSP (mean Hassanat similarity percentage) of a set of predictions is
+
+    MHSP = 100 * mean_i S(actual_i, predicted_i)
+
+100% means every prediction equals its actual value; higher is better.
+It is computed on the values as they are (no scaling), as defined in
+Hassanat et al. (2024), Mathematics 12(22), 3623.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+# The paper that introduced MHSP as an outlier-robust accuracy measure for
+# regression; cited wherever MHSP is reported.
+MHSP_CITATION = (
+    "Hassanat, A. B., Alqaralleh, M. K., Tarawneh, A. S., Almohammadi, K., "
+    "Alamri, M., Alzahrani, A., Altarawneh, G. A., & Alhalaseh, R. (2024). "
+    "A novel outlier-robust accuracy measure for machine learning regression "
+    "using a non-convex distance metric. Mathematics, 12(22), 3623. "
+    "https://doi.org/10.3390/math12223623")
+
+# Cited for the Hassanat distance when KNN uses it: the IEEE conference paper
+# that reviews its applications, and the arXiv preprint that introduced it
+# (the same two as EasyClassifier).
+HASSANAT_CITATIONS = [
+    "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",
+]
+
+
+def hassanat_similarity(a, b) -> np.ndarray:
+    """Element-wise Hassanat similarity in [0, 1]."""
+    a = np.asarray(a, dtype=float)
+    b = np.asarray(b, dtype=float)
+    mn = np.minimum(a, b)
+    mx = np.maximum(a, b)
+    shift = np.where(mn < 0, -mn, 0.0)
+    return (1.0 + mn + shift) / (1.0 + mx + shift)
+
+
+def mhsp(actual, predicted) -> float:
+    """Mean Hassanat similarity percentage (0-100, higher is better)."""
+    return float(100.0 * np.mean(hassanat_similarity(actual, predicted)))
+
+
+MHSP_EXPLANATION = (
+    "MHSP (mean Hassanat similarity percentage): for each prediction, the "
+    "Hassanat similarity (1 + smaller value) / (1 + larger value) between "
+    "the actual and predicted value, averaged and shown as a percentage. "
+    "100% means perfect predictions. Each prediction contributes at most "
+    "its share, so one very large error cannot dominate it. It depends on "
+    "the units of the values: errors on large values count as relatively "
+    "small.")

easyresearch/common/output.py

@@ -0,0 +1,156 @@
+"""Small helpers shared by the cores: number formatting, output folders,
+LaTeX compilation, and the record of settings and software versions that
+every run folder contains."""
+
+from __future__ import annotations
+
+import dataclasses
+import datetime as _dt
+import json
+import os
+import platform
+import sys
+import subprocess
+from typing import Dict, Optional, Tuple
+
+from easyclassifier.latex_report import find_engine
+
+
+def fmt(v: float) -> str:
+    """A number with sensible precision for any unit."""
+    a = abs(v)
+    if a >= 1000:
+        return f"{v:,.0f}"
+    if a >= 1:
+        return f"{v:.2f}"
+    return f"{v:.3g}"
+
+
+def results_folder(out_root: str, source_stem: str) -> str:
+    """A new folder for every run: <out_root>/Results/<data>_<date>_<time>."""
+    stamp = _dt.datetime.now().strftime("%Y-%m-%d_%H-%M-%S")
+    safe = "".join(ch if ch.isalnum() or ch in "-_" else "_"
+                   for ch in source_stem)[:40] or "data"
+    out = os.path.join(out_root, "Results", f"{safe}_{stamp}")
+    os.makedirs(os.path.join(out, "figures"), exist_ok=True)
+    return out
+
+
+def compile_tex(tex_text: str, out_dir: str,
+                timeout: int = 180) -> Tuple[str, Optional[str], str]:
+    """Write report.tex and compile it to report.pdf when LaTeX is found."""
+    tex_path = os.path.join(out_dir, "report.tex")
+    with open(tex_path, "w", encoding="utf-8") as fh:
+        fh.write(tex_text)
+    engine = find_engine()
+    if engine is None:
+        return tex_path, None, (
+            "No LaTeX program was found, so only report.tex was written. "
+            "Upload it with the 'figures' folder to an online editor such as "
+            "Overleaf, or install MiKTeX to get report.pdf.")
+    pdf_path = os.path.join(out_dir, "report.pdf")
+    if os.path.exists(pdf_path):
+        os.remove(pdf_path)
+    runs = ([["tectonic", "report.tex"]] if engine == "tectonic" else
+            [[engine, "-interaction=nonstopmode", "-halt-on-error",
+              "report.tex"]] * 2)
+    proc = None
+    try:
+        for run in runs:
+            proc = subprocess.run(run, cwd=out_dir, capture_output=True,
+                                  timeout=timeout)
+            if proc.returncode != 0:
+                break
+    except (subprocess.TimeoutExpired, OSError) as exc:
+        return tex_path, None, f"LaTeX ({engine}) did not finish: {exc}."
+    finally:
+        for ext in (".aux", ".out", ".toc"):
+            p = os.path.join(out_dir, "report" + ext)
+            if os.path.exists(p):
+                os.remove(p)
+    log = os.path.join(out_dir, "report.log")
+    if proc is not None and proc.returncode == 0 and os.path.exists(pdf_path):
+        if os.path.exists(log):
+            os.remove(log)
+        return tex_path, pdf_path, f"PDF created with {engine}."
+    if os.path.exists(log):
+        os.replace(log, os.path.join(out_dir, "report_latex_errors.log"))
+    return tex_path, None, (f"LaTeX ({engine}) could not build the PDF; see "
+                            "report_latex_errors.log. report.tex can still be "
+                            "opened in Overleaf.")
+
+
+VERSION_PACKAGES = ("easyresearch", "easyclassifier", "numpy", "pandas",
+                    "scikit-learn", "scipy", "matplotlib", "joblib",
+                    "statsmodels", "torch", "openpyxl", "xgboost", "lightgbm")
+
+
+def software_versions() -> Dict[str, str]:
+    """Python, operating system and the installed analysis packages."""
+    from importlib.metadata import PackageNotFoundError, version
+    found = {"Python": platform.python_version(),
+             "Operating system": f"{platform.system()} {platform.release()} "
+                                 f"({platform.machine()})"}
+    for name in VERSION_PACKAGES:
+        try:
+            found[name] = version(name)
+        except PackageNotFoundError:
+            pass
+    return found
+
+
+def write_run_record(out_dir: str, task: str, data: str, column: str,
+                     settings, resolved: Dict) -> None:
+    """settings.json (what was asked and what was used) and versions.txt
+    (the software that produced the results), so a run can be repeated and
+    reported exactly."""
+    asked = (dataclasses.asdict(settings) if dataclasses.is_dataclass(settings)
+             else dict(settings))
+    record = {"task": task, "data": data, "column": column,
+              "settings": asked, "used": resolved,
+              "created": _dt.datetime.now().isoformat(timespec="seconds")}
+    with open(os.path.join(out_dir, "settings.json"), "w",
+              encoding="utf-8") as fh:
+        json.dump(record, fh, ensure_ascii=False, indent=2, default=str)
+    lines = [f"{k}: {v}" for k, v in software_versions().items()]
+    with open(os.path.join(out_dir, "versions.txt"), "w",
+              encoding="utf-8") as fh:
+        fh.write("Software used for these results\n\n" + "\n".join(lines)
+                 + f"\n\nPython executable: {sys.executable}\n")
+
+
+def figure_style(settings, known) -> Tuple[dict, Optional[list]]:
+    """The figure theme and file formats chosen in the settings (as keyword
+    arguments for the figure maker), and the figures to draw (None = the
+    task's usual set). Unknown choices are refused in plain words."""
+    from easyclassifier.figures import FORMATS, THEMES
+    theme = getattr(settings, "figure_theme", "colorblind")
+    formats = getattr(settings, "figure_format", "png")
+    keys = getattr(settings, "figure_keys", None)
+    if theme not in THEMES:
+        raise ValueError(f"Unknown figure theme '{theme}'; choose one of: "
+                         + ", ".join(THEMES) + ".")
+    if formats not in FORMATS:
+        raise ValueError(f"Unknown figure format '{formats}'; choose one of: "
+                         + ", ".join(FORMATS) + ".")
+    if keys is not None:
+        unknown = [k for k in keys if k not in known]
+        if unknown:
+            raise ValueError("Unknown figure(s): " + ", ".join(unknown) + ".")
+        keys = [k for k in known if k in keys]          # report order
+    return dict(theme=theme, formats=formats), keys
+
+
+def save_model(obj, path: str) -> Optional[str]:
+    """Save the trained model; on failure, remove the partial file and return
+    a plain message instead of stopping the analysis (all other results are
+    still saved)."""
+    import joblib
+    try:
+        joblib.dump(obj, path)
+        return None
+    except Exception as exc:  # noqa: BLE001
+        if os.path.exists(path):
+            os.remove(path)
+        return (f"The trained model could not be saved ({type(exc).__name__}: "
+                f"{exc}); all other results were saved.")

easyresearch/common/references.py

@@ -0,0 +1,235 @@
+"""References for every method the EasyResearch cores can use.
+
+Extends EasyClassifier's reference list (classifiers, distances, evaluation,
+measures, software) with the models and methods of regression, forecasting
+and signal classification. Each report cites the methods it used; the
+bibliography and ``citations.txt`` are generated from those citations (see
+``easyclassifier.references``), so a reference is listed exactly when it is
+cited.
+"""
+
+from __future__ import annotations
+
+from typing import Dict, List, Optional
+
+from easyclassifier.references import (
+    CLASSIFIER_REFERENCES,
+    FIGURE_REFERENCES,
+    HASSANAT_SIGNED_REFERENCES,
+    METRIC_REFERENCES,
+    REFERENCES as _CLASSIFICATION_REFERENCES,
+    SELECTION_REFERENCES,
+    TOPICS as _CLASSIFICATION_TOPICS,
+    VALIDATION_REFERENCES,
+    cite,
+    cited_keys,
+)
+from easyclassifier import references as _base
+
+from .hassanat import MHSP_CITATION
+
+__all__ = ["REFERENCES", "TOPICS", "CLASSIFIER_REFERENCES", "FIGURE_REFERENCES",
+           "HASSANAT_SIGNED_REFERENCES",
+           "METRIC_REFERENCES", "SELECTION_REFERENCES",
+           "VALIDATION_REFERENCES", "REGRESSION_MODEL_REFERENCES",
+           "FORECAST_MODEL_REFERENCES", "SIGNAL_MODEL_REFERENCES",
+           "bibliography", "citation_lines", "cite", "cited_keys",
+           "model_cites"]
+
+REFERENCES: Dict[str, str] = dict(_CLASSIFICATION_REFERENCES)
+REFERENCES.update({
+    "mhsp": MHSP_CITATION,
+    # Software
+    "statsmodels": "Seabold, S., & Perktold, J. (2010). Statsmodels: "
+                   "Econometric and statistical modeling with Python. "
+                   "Proceedings of the 9th Python in Science Conference, "
+                   "92-96.",
+    "pytorch": "Paszke, A., et al. (2019). PyTorch: An imperative style, "
+               "high-performance deep learning library. NeurIPS 2019, "
+               "8024-8035.",
+    # Regression models
+    "hastie2009": "Hastie, T., Tibshirani, R., & Friedman, J. (2009). The "
+                  "Elements of Statistical Learning: Data Mining, Inference, "
+                  "and Prediction (2nd ed.). Springer. "
+                  "https://doi.org/10.1007/978-0-387-84858-7",
+    "hoerl1970": "Hoerl, A. E., & Kennard, R. W. (1970). Ridge regression: "
+                 "Biased estimation for nonorthogonal problems. "
+                 "Technometrics, 12(1), 55-67. "
+                 "https://doi.org/10.1080/00401706.1970.10488634",
+    "friedman2001": "Friedman, J. H. (2001). Greedy function approximation: "
+                    "A gradient boosting machine. The Annals of Statistics, "
+                    "29(5), 1189-1232. "
+                    "https://doi.org/10.1214/aos/1013203451",
+    "drucker1997": "Drucker, H., Burges, C. J. C., Kaufman, L., Smola, A., & "
+                   "Vapnik, V. (1997). Support vector regression machines. "
+                   "In Advances in Neural Information Processing Systems 9 "
+                   "(pp. 155-161). MIT Press.",
+    "altman1992": "Altman, N. S. (1992). An introduction to kernel and "
+                  "nearest-neighbor nonparametric regression. The American "
+                  "Statistician, 46(3), 175-185. "
+                  "https://doi.org/10.1080/00031305.1992.10475879",
+    # Forecasting
+    "hyndman2021": "Hyndman, R. J., & Athanasopoulos, G. (2021). "
+                   "Forecasting: Principles and Practice (3rd ed.). OTexts. "
+                   "https://otexts.com/fpp3/",
+    "hyndman2002": "Hyndman, R. J., Koehler, A. B., Snyder, R. D., & Grose, "
+                   "S. (2002). A state space framework for automatic "
+                   "forecasting using exponential smoothing methods. "
+                   "International Journal of Forecasting, 18(3), 439-454.",
+    "assimakopoulos2000": "Assimakopoulos, V., & Nikolopoulos, K. (2000). "
+                          "The theta model: a decomposition approach to "
+                          "forecasting. International Journal of "
+                          "Forecasting, 16(4), 521-530.",
+    "bontempi2013": "Bontempi, G., Ben Taieb, S., & Le Borgne, Y.-A. (2013). "
+                    "Machine learning strategies for time series "
+                    "forecasting. In M.-A. Aufaure & E. Zimányi (Eds.), "
+                    "Business Intelligence (eBISS 2012), Lecture Notes in "
+                    "Business Information Processing 138 (pp. 62-77). "
+                    "Springer. https://doi.org/10.1007/978-3-642-36318-4_3",
+    "tashman2000": "Tashman, L. J. (2000). Out-of-sample tests of "
+                   "forecasting accuracy: an analysis and review. "
+                   "International Journal of Forecasting, 16(4), 437-450.",
+    "hyndman2006": "Hyndman, R. J., & Koehler, A. B. (2006). Another look at "
+                   "measures of forecast accuracy. International Journal of "
+                   "Forecasting, 22(4), 679-688.",
+    "makridakis1993": "Makridakis, S. (1993). Accuracy measures: theoretical "
+                      "and practical concerns. International Journal of "
+                      "Forecasting, 9(4), 527-529. "
+                      "https://doi.org/10.1016/0169-2070(93)90079-3",
+    "cleveland1990": "Cleveland, R. B., Cleveland, W. S., McRae, J. E., & "
+                     "Terpenning, I. (1990). STL: A seasonal-trend "
+                     "decomposition procedure based on loess. Journal of "
+                     "Official Statistics, 6(1), 3-73.",
+    # Deep networks
+    "hochreiter1997": "Hochreiter, S., & Schmidhuber, J. (1997). Long "
+                      "short-term memory. Neural Computation, 9(8), "
+                      "1735-1780.",
+    "cho2014": "Cho, K., et al. (2014). Learning phrase representations "
+               "using RNN encoder-decoder for statistical machine "
+               "translation. EMNLP 2014, 1724-1734.",
+    "bai2018": "Bai, S., Kolter, J. Z., & Koltun, V. (2018). An empirical "
+               "evaluation of generic convolutional and recurrent networks "
+               "for sequence modeling. arXiv:1803.01271.",
+    "oreshkin2020": "Oreshkin, B. N., Carpov, D., Chapados, N., & Bengio, Y. "
+                    "(2020). N-BEATS: Neural basis expansion analysis for "
+                    "interpretable time series forecasting. ICLR 2020.",
+    "vaswani2017": "Vaswani, A., et al. (2017). Attention is all you need. "
+                   "NeurIPS 2017, 5998-6008.",
+    # Signal classification
+    "dempster2020": "Dempster, A., Petitjean, F., & Webb, G. I. (2020). "
+                    "ROCKET: exceptionally fast and accurate time series "
+                    "classification using random convolutional kernels. "
+                    "Data Mining and Knowledge Discovery, 34(5), 1454-1495.",
+    "fulcher2014": "Fulcher, B. D., & Jones, N. S. (2014). Highly "
+                   "comparative feature-based time-series classification. "
+                   "IEEE Transactions on Knowledge and Data Engineering, "
+                   "26(12), 3026-3037. "
+                   "https://doi.org/10.1109/TKDE.2014.2316504",
+    "wang2017": "Wang, Z., Yan, W., & Oates, T. (2017). Time series "
+                "classification from scratch with deep neural networks: a "
+                "strong baseline. IJCNN 2017, 1578-1585.",
+    "he2016": "He, K., Zhang, X., Ren, S., & Sun, J. (2016). Deep residual "
+              "learning for image recognition. In Proceedings of the IEEE "
+              "Conference on Computer Vision and Pattern Recognition (CVPR) "
+              "(pp. 770-778). https://doi.org/10.1109/CVPR.2016.90",
+    "ismailfawaz2020": "Ismail Fawaz, H., et al. (2020). InceptionTime: "
+                       "finding AlexNet for time series classification. "
+                       "Data Mining and Knowledge Discovery, 34(6), "
+                       "1936-1962.",
+})
+
+TOPICS: Dict[str, str] = dict(_CLASSIFICATION_TOPICS)
+TOPICS.update({
+    "software": "EasyResearch (this software)",
+    "easyclassifier": "EasyClassifier (data preparation and evaluation)",
+    "dataset": "The example dataset",
+    "mhsp": "Mean Hassanat similarity percentage (MHSP)",
+    "statsmodels": "statsmodels (statistical forecasting models)",
+    "pytorch": "PyTorch (deep networks)",
+    "hastie2009": "Linear regression (least squares)",
+    "hoerl1970": "Ridge regression",
+    "friedman2001": "Gradient boosting",
+    "drucker1997": "Support vector regression",
+    "altman1992": "K-nearest-neighbour regression",
+    "hyndman2021": "Naive and seasonal naive forecasts; prediction intervals",
+    "hyndman2002": "Exponential smoothing (ETS)",
+    "assimakopoulos2000": "Theta method",
+    "bontempi2013": "Machine-learning forecasting from past values "
+                    "(direct multi-step strategy)",
+    "tashman2000": "Rolling-origin evaluation",
+    "hyndman2006": "MASE",
+    "makridakis1993": "sMAPE",
+    "cleveland1990": "STL decomposition",
+    "hochreiter1997": "LSTM",
+    "cho2014": "GRU",
+    "bai2018": "Temporal convolutional network (TCN)",
+    "oreshkin2020": "N-BEATS",
+    "vaswani2017": "Transformer",
+    "dempster2020": "ROCKET",
+    "fulcher2014": "Feature-based time-series classification",
+    "wang2017": "FCN and ResNet for time-series classification",
+    "he2016": "Residual networks (ResNet)",
+    "ismailfawaz2020": "InceptionTime",
+})
+
+HASSANAT = ["hassanat2022", "hassanat2014"]
+
+REGRESSION_MODEL_REFERENCES: Dict[str, List[str]] = {
+    "linear_regression": ["hastie2009"],
+    "ridge": ["hoerl1970"],
+    "decision_tree": ["breiman1984"],
+    "random_forest": ["breiman2001"],
+    # scikit-learn's histogram-based gradient boosting follows LightGBM.
+    "gradient_boosting": ["friedman2001", "ke2017"],
+    "svr": ["drucker1997"],
+    "knn": ["altman1992"] + HASSANAT,
+    "neural_network": ["rumelhart1986", "kingma2015"],
+    "xgboost": ["chen2016"],
+    "lightgbm": ["ke2017"],
+}
+
+FORECAST_MODEL_REFERENCES: Dict[str, List[str]] = {
+    "naive": ["hyndman2021"],
+    "seasonal_naive": ["hyndman2021"],
+    "ets": ["hyndman2002"],
+    "theta": ["assimakopoulos2000"],
+    "ridge": ["hoerl1970"],
+    "random_forest": ["breiman2001"],
+    "gradient_boosting": ["friedman2001", "ke2017"],
+    "knn": ["altman1992"] + HASSANAT,
+    "mlp": ["rumelhart1986"],
+    "lstm": ["hochreiter1997"],
+    "gru": ["cho2014"],
+    "tcn": ["bai2018"],
+    "nbeats": ["oreshkin2020"],
+    "transformer": ["vaswani2017"],
+}
+
+SIGNAL_MODEL_REFERENCES: Dict[str, List[str]] = {
+    "majority": [],
+    "knn": ["cover1967"] + HASSANAT,
+    "rocket": ["dempster2020"],
+    "features_rf": ["fulcher2014", "breiman2001"],
+    "fcn": ["wang2017"],
+    "resnet": ["wang2017", "he2016"],
+    "inception": ["ismailfawaz2020"],
+    "lstm": ["hochreiter1997"],
+}
+
+
+def model_cites(keys, table: Dict[str, List[str]]) -> List[str]:
+    """All references of the given models, in order, without repeats."""
+    return list(dict.fromkeys(r for k in keys for r in table.get(k, [])))
+
+
+def bibliography(text: str, extra: Optional[Dict[str, str]] = None,
+                 escape=lambda s: s) -> str:
+    """As in EasyClassifier, with the references of all EasyResearch cores
+    (``extra`` holds the report's own entries: software, dataset)."""
+    return _base.bibliography(text, dict(REFERENCES, **(extra or {})), escape)
+
+
+def citation_lines(text: str, extra: Optional[Dict[str, str]] = None,
+                   topics: Optional[Dict[str, str]] = None) -> List[str]:
+    return _base.citation_lines(text, dict(REFERENCES, **(extra or {})),
+                                dict(TOPICS, **(topics or {})))