craceplot 0.1.0__py3-none-any.whl

craceplot/_scripts/__init__.py

@@ -0,0 +1,4 @@
+# _scripts/__init__.py
+
+from craceplot._scripts._main import start_cplot, run
+from craceplot._scripts._utils import cplot_run

craceplot/_scripts/_main.py

@@ -0,0 +1,132 @@
+import os
+import sys
+import re
+import inspect
+import traceback
+
+current_file = os.path.normpath(__file__)
+CPLOT_HOME = os.path.dirname(os.path.dirname(os.path.dirname(current_file)))
+if CPLOT_HOME not in map(os.path.abspath, sys.path):
+    sys.path.insert(0, os.path.abspath(CPLOT_HOME))
+
+from craceplot._containers._core import ParseOptions, Errors as CE
+from craceplot._containers._draw import DrawPlot, load_results
+
+def start_cmdline(arguments=None, console: bool=True):
+    """
+    Function that executes the configuration procedure with arguments from the command line
+    """
+
+    data = None
+    scenario = None
+    current_dir = os.getcwd()
+
+    try:
+        scenario = ParseOptions.from_input(arguments=arguments, console=console)
+
+        if scenario.logDir.value is not None:
+            data = load_results(options=scenario.options, data_home=scenario.logDir.value)
+
+        if data:
+            if console:
+                # check if there is any other options
+                any_arg = False
+                for o in scenario.options:
+                    if scenario._get_option(o).long in arguments or scenario._get_option(o).short in arguments:
+                        if scenario._get_option(o).name != 'logDir':
+                            any_arg = True
+                            break
+                # if there is only one option logDir, return
+                if not any_arg: return data, scenario
+            # other cases:
+            #   - not in console
+            #   - including other options
+            print(f"# Setting working directory: {scenario.logDir.value}\n#")
+            if os.path.exists(scenario.logDir.value):
+                os.chdir(scenario.logDir.value)
+            if scenario.drawMethod.value is not None: DrawPlot(reader=scenario, src_data=data)
+            os.chdir(current_dir)
+
+        if console: return data, scenario
+
+    except KeyboardInterrupt:
+        print()
+
+    except SystemExit:
+        pass
+
+    except Exception as e:
+        if any(isinstance(e, cls) for cls in [x[1] for x in inspect.getmembers(CE, inspect.isclass)]):
+            pass
+        else:
+            print("\nERROR: There was an error while executing craceplot:")
+            sys.tracebacklimit = 20
+            traceback.print_exc()
+            print(e)
+
+    if not console: sys.exit(1)
+
+    return
+
+
+def _parse_args(*args):
+    if len(args) == 1:
+        args = args[0]
+    if isinstance(args, list):
+        outs = args
+    elif isinstance(args, str):
+        outs = re.split(r"[ ,]+", args)
+    else:
+        outs = list(args)
+    return [str(x) for x in outs]
+
+
+def run(*inputs):
+    return start_cplot(*inputs)
+
+
+def start_cplot(*kargs, arguments: list=None, console: bool=True):
+    """
+    Allowed to be called: 1. by entry point, 
+                          2. by crace_mpi 
+                          3. in python console
+    """
+    if arguments is not None and kargs:
+        raise TypeError(
+            "load_options() accepts either positional arguments "
+            "or 'arguments=', not both")
+    if arguments is not None:
+        arguments = _parse_args(arguments)
+    elif len(kargs) > 0:
+        arguments = _parse_args(*kargs)
+
+    if not arguments:
+        # arguments may be [] (not None)
+        arguments = sys.argv[1:] # command line arguments as a list
+
+    if ('--crace' in arguments) or ('-c' in arguments):
+        index = arguments.index('--crace') if '--crace' in arguments else arguments.index('-c')
+        try:
+            from craceplot._utils._crace import get_crace
+            crace_main_file = arguments[index + 1]
+            crace = get_crace(crace_main_file)
+            print(f"# Loading crace from: {crace_main_file}")
+            print(f"# crace version: {crace.__version__}")
+            del arguments[index:index + 2]
+        except IndexError:
+            raise RuntimeError("Please provide the path to crace/scripts/main.py after --crace or -c")
+
+    if len(arguments) == 0: return
+
+    data = start_cmdline(arguments, console)
+
+    if data: return data
+
+
+
+if __name__ == '__main__':
+    """
+    Allowed to be called only by this file
+    """
+    from craceplot._scripts._utils import cplot_run
+    cplot_run()

craceplot/_scripts/_utils.py

@@ -0,0 +1,66 @@
+def cplot_guide():
+    import os, sys
+    import pathlib
+    import webbrowser
+    try:
+        import craceplot
+        dir_cplot = pathlib.Path(craceplot.__file__).resolve().parent
+    except:
+        dir_cplot = pathlib.Path(__file__).resolve().parent.parent
+
+    guide = pathlib.Path(os.path.join(dir_cplot, '_vignettes/guide.ipynb'))
+
+    # not support system without GUI
+    if guide.exists():
+        print(guide)
+        webbrowser.open(guide.as_uri())
+    else:
+        sys.exit(1)
+
+def cplot_examples(destname):
+    import sys
+    import pathlib
+    import platform
+    import subprocess
+
+    try:
+        import craceplot
+        dir_cplot = pathlib.Path(craceplot.__file__).resolve().parent
+    except:
+        dir_cplot = pathlib.Path(__file__).resolve().parent.parent
+
+    if destname in ("which", "where"):
+        destpath = pathlib.Path(dir_cplot)
+        print(destpath)
+    else:
+        destpath = pathlib.Path(dir_cplot / '_inst/' / destname)
+        print(destpath)
+
+    # not support system without GUI
+    system = platform.system()
+    if destpath.exists():
+        if system == "Darwin":  # macOS
+            subprocess.run(["open", destpath])
+        elif system == "Windows":
+            subprocess.run(["explorer", destpath])
+        else:  # Linux
+            subprocess.run(["xdg-open", destpath])
+    else:
+        sys.exit(1)
+
+def cplot_run():
+    import sys
+
+    from craceplot._scripts._main import start_cplot
+
+    if len(sys.argv) > 1:
+
+        if sys.argv[1] == "doc":
+            cplot_guide()
+            return
+
+        if sys.argv[1].lower() in ("examples", "templates", "which", "where"):
+            cplot_examples(sys.argv[1].lower())
+            return
+
+    start_cplot(arguments=sys.argv[1:], console=False)

craceplot/_scripts/main

@@ -0,0 +1,3 @@
+#!/bin/bash
+DIRCPLOT=$(pip3 show craceplot | grep Location | cut -d ' ' -f2)
+python3 "$DIRCPLOT/craceplot/_main.py" "$@"

craceplot/_scripts/open_guide

@@ -0,0 +1,12 @@
+#!/bin/bash
+if ! DIRCPLOT=$(python3 -c "import crace, pathlib; print(pathlib.Path(crace.__file__).resolve().parent)" 2>/dev/null); then
+    DIRCPLOT="$(cd "$(dirname "$0")/.." && pwd)"
+fi
+
+FILE="$DIRCPLOT/_vignettes/guide.ipynb"
+
+case "$OSTYPE" in
+  darwin*) open "$FILE" ;;
+  linux*)  xdg-open "$FILE" ;;
+  *)       start "$FILE" ;;
+esac

craceplot/_settings/_description.py

@@ -0,0 +1,168 @@
+# craceplot/_description.py
+
+from datetime import datetime
+
+package_name = "craceplot"
+authors = ['Yunshuang Xiao']
+maintainers = ['Yunshuang Xiao']
+maintainers_email = ['yunshuang.xiao@ulb.be']
+contact = 'crace developers'
+contact_email = 'race.autoconfig@gmail.com'
+
+description = "craceplot: Visualisation of Data from crace"
+long_description = """
+craceplot: Visualisation of Data from crace
+==========================================================================
+
+craceplot provides a set of functions to create plots to visualize the data from the crace package.
+
+The configuration process performed by crace will show at the end of the execution one or more configurations that are the best performing configurations found. This package provides a set of functions that allow to further assess the performance of these configurations and provides support to obtain insights about the details of the configuration process.
+"""
+
+url = "https://race-autoconfig.github.io/craceplot/"
+url_home = url
+url_source = "https://github.com/race-autoconfig/craceplot/"
+url_tracker = "https://github.com/race-autoconfig/craceplot/issues"
+urls = {
+    'Homepage': url_home,
+    'Source': url_source,
+    'Tracker': url_tracker,
+}
+
+_year = datetime.now().year
+copyright = (
+    f"Copyright (c) 2026-{_year} crace developers"
+    if _year > 2026
+    else "Copyright (c) 2026 crace developers"
+)
+
+license = f"""
+This is free software: you can redistribute it and/or modify it under the terms of the MIT License as published by the Free Software Foundation.
+
+This is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the MIT License for more details.
+
+craceplot builds as an additional tool for the crace package:
+  crace: Continuous Racing for Automatic Algorithm Configuration
+  {copyright}
+"""
+
+citiation = """
+To cite package 'craceplot' in publications, an appropriate citation is
+
+  Yunshuang Xiao, Leslie Pérez Cáceres, Manuel López-Ibáñez, and Thomas Stützle. 2023. Algorithm Configuration via Continuously Racing: Preliminary Results. In Proceedings of the Companion Conference on Genetic and Evolutionary Computation (GECCO '23 Companion). Association for Computing Machinery, New York, NY, USA, 1744-1752. https://doi.org/10.1145/3583133.3596408
+
+A BibTeX entry for LaTeX users is
+
+@inproceedings{10.1145/3583133.3596408,
+  title = {Algorithm Configuration via Continuously Racing: Preliminary Results},
+  author = {Xiao, Yunshuang and Pérez Cáceres, Leslie and López-Ibáñez, Manuel and Stützle, Thomas},
+  booktitle = {Proceedings of the Companion Conference on Genetic and Evolutionary Computation},
+  pages = {1744-1752},
+  year = {2023},
+}
+"""
+
+_VERSION = "0.1.0"
+update_logs = """
+
+The first release of craceplot, version 0.1.0.
+
+"""
+
+
+def __getattr__(name: str):
+    if name == "version":
+        ver = _get_version()
+        globals()["version"] = ver
+        return ver
+    raise AttributeError(f"module '{__name__}' has no attribute '{name}'")
+
+
+
+def _get_version():
+    """
+    read version information from
+        1. _version.py generated by setuptools_scm
+        2. _vergit.py formated using git archive
+           * must set .gitattributes (crace/_vergit.py export-subst) in advanve
+        3. .git/HEAD and .git/<ref> if src includes .git directory
+        4. check the latest modification date of all src files
+        0. fallback to _VERSION 
+    """
+    import os
+    import inspect
+    from pathlib import Path
+
+    try:
+        current_dir = Path(__file__).resolve().parent.parent
+    except NameError:
+        caller_file = inspect.stack()[1].filename
+        current_dir = Path(caller_file).resolve().parent.parent
+
+    dest_ver = current_dir / "_version.py"
+    dest_git = current_dir / "_vergit.py"
+    dest_git_dir = current_dir.parent / ".git"
+
+
+    try:
+        if os.path.exists(dest_ver):
+            d = {}
+            with open(dest_ver) as f:
+                exec(f.read(), d)
+            return d.get("version", d.get("__version__", _VERSION))
+    except Exception:
+        pass
+
+    try:
+        import re
+        if os.path.exists(dest_git):
+            d = {}
+            with open(dest_git) as f:
+                exec(f.read(), d)
+            ver = d.get("version", d.get("__version__", _VERSION))
+            match = re.search(r"tag:\s*([^,\)]+)", ver)
+            if match: return match.group(1)
+    except Exception:
+        pass
+
+    try:
+        commit = None
+        if os.path.exists(dest_git_dir):
+            head = (dest_git_dir / "HEAD").read_text().strip()
+            packed_tag = dest_git_dir / "packed-refs"
+
+            if head.startswith("ref:"): 
+                ref = head.split(" ", 1)[1]
+                try:
+                    commit = (dest_git_dir / ref).read_text().strip()[:7]
+                except Exception:
+                    for t in packed_tag.read_text().splitlines():
+                        if t.startswith("#"): continue
+                        s, r = t.split(" ", 1)
+                        if r.strip() == ref:
+                            commit = s[:7]
+            else:
+                commit = head[:7]
+
+            if commit: return commit
+
+    except Exception:
+        pass
+
+    ignore_files = {".git",
+                    "__pycache__",
+                    "build",
+                    "dist",
+    }
+    try:
+        latest = 0
+        for root, dirs, files in os.walk(current_dir.parent):
+            dirs[:] = [ d for d in dirs if d not in ignore_files]
+            for f in files:
+                p = Path(root) / f
+                latest = max(latest, os.path.getmtime(p))
+        return _VERSION + ' ' + datetime.fromtimestamp(latest).strftime("%b.%d.%Y")
+    except Exception:
+        pass
+
+    return _VERSION

craceplot/_settings/_options.json

@@ -0,0 +1,299 @@
+[
+    {
+        "name": ".help",
+        "type": "e",
+        "short": "-h",
+        "long": "--help",
+        "default": null,
+        "section": "Utility options",
+        "critical": 1,
+        "description": "Show this help.",
+        "vignettes": "Show the list of command-line options of \u001b[1mcraceplot\u001b[0m"
+    },
+    {
+        "name": ".man",
+        "type": "s",
+        "long": "--man",
+        "short": "-m",
+        "default": null,
+        "domain": null,
+        "section": "Utility options",
+        "critical": 1,
+        "description": "Show details of the selected option.",
+        "vignettes": "Show details of the selected option. call with \u001b[1m--man [option]\u001b[0m"
+    },
+    {
+        "name": ".version",
+        "type": "e",
+        "short": "-v",
+        "long": "--version",
+        "default": null,
+        "section": "Utility options",
+        "critical": 1,
+        "description": "Show the version of crace-plot.",
+        "vignettes": "Show the version of \u001b[1mcraceplot\u001b[0m."
+    },
+    {
+        "name": ".doc",
+        "type": "e",
+        "short": "",
+        "long": "doc",
+        "default": null,
+        "section": "Utility options",
+        "critical": -1,
+        "description": "Open the user guide. This command must be the first argument.",
+        "vignettes": "Open the user guide of crace. This command must be the first argument."
+    },
+    {
+        "name": ".examples",
+        "type": "e",
+        "short": "",
+        "long": "examples",
+        "default": null,
+        "section": "Utility options",
+        "critical": -1,
+        "description": "Open examples folder. This command must be the first argument.",
+        "vignettes": "Open examples folder. This command must be the first argument."
+    },
+    {
+        "name": ".templates",
+        "type": "e",
+        "short": "",
+        "long": "templates",
+        "default": null,
+        "section": "Utility options",
+        "critical": -1,
+        "description": "Open templates folder. This command must be the first argument.",
+        "vignettes": "Open templates folder. This command must be the first argument."
+    },
+    {
+        "name": ".which",
+        "type": "e",
+        "short": "",
+        "long": "which",
+        "default": null,
+        "section": "Utility options",
+        "critical": -1,
+        "description": "Open crace root folder. This command must be the first argument.",
+        "vignettes": "Open crace root folder. This command must be the first argument."
+    },
+    {
+        "name": ".where",
+        "type": "e",
+        "short": "",
+        "long": "where",
+        "default": null,
+        "section": "Utility options",
+        "critical": -1,
+        "description": "Open crace root folder. This command must be the first argument.",
+    "vignettes": "Open crace root folder. This command must be the first argument."
+    },
+    {
+        "name": "logDir",
+        "type": "p",
+        "short": "-l",
+        "long": "--log-dir",
+        "default": ".\/race_log",
+        "section": "General options",
+        "critical": 0,
+        "description": "Directory where the results are from.",
+        "vignettes": "Directory where the results are from. The default log directory is the current folder.\\begin{xwarningbox}The execution directory must exist before executing \u001b[1mcraceplot\u001b[0m, it will not be created automatically.\\end{xwarningbox}"
+    },
+    {
+        "name": "outDir",
+        "type": "p",
+        "short": "-o",
+        "long": "--out-dir",
+        "default": ".\/",
+        "section": "General options",
+        "critical": 0,
+        "description": "Directory where the output files will be storaged.",
+        "vignettes": "Directory where the craceplot outputs will be storaged. The default output directory is the current folder. \\begin{xwarningbox}This directory can be created automatically when executing \u001b[1mcraceplot\u001b[0m. \\end{xwarningbox}"
+    },
+    {
+        "name": "title",
+        "type": "s",
+        "short": "-t",
+        "long": "--title",
+        "default": null,
+        "section":"General options",
+        "critical": 0,
+        "description": "The title of the output plot which would be shown in plot.",
+        "vignettes": "The title of the output plot which would be shown in plot. The default value of this option depends on the \u001b[4mlogDir\u001b[0m and the \u001b[4mdrawMethod\u001b[0m. This option is only avaliable when \u001b[4mlogDir\u001b[0m and \u001b[4mdrawMethod\u001b[0m are not None."
+    },
+    {
+        "name": "fileName",
+        "type": "s",
+        "short": "-f",
+        "long": "--file-name",
+        "default": null,
+        "section":"General options",
+        "critical": 0,
+        "description": "The name of the output plot file.",
+        "vignettes": "The name of the output plot file. The default value of this option is \u001b[1mcurrent time\u001b[0m. This option is only avaliable when \u001b[4mlogDir\u001b[0m and \u001b[4mdrawMethod\u001b[0m are not None."
+    },
+    {
+        "name": "drawMethod",
+        "type": "s",
+        "short": "-dm",
+        "long": "--draw-method",
+        "default": null,
+        "domain": "(boxplot, violinplot, parallelcoord, parallelcat, sunburst, pairplot, histplot, jointplot, heatmap)",
+        "section": "Plot options",
+        "critical": 0,
+        "description": "The type of plot for the crace results.",
+        "vignettes": "The type of plot for the \u001b[1mCrace\u001b[0m results. If this option is not null, \u001b[4mlogDir\u001b[0m must to be provided. When one method is selected, the correspoding option must be True. "
+    },
+    {
+        "name": "dataType",
+        "type": "s",
+        "short": "-dt",
+        "long": "--data-type",
+        "default": null,
+        "domain": "(experiments, quality, time, configurations, parameters)",
+        "section": "Plot options",
+        "critical": 0,
+        "description": "The origin of data used for drawing plot(s).",
+        "vignettes": "The origin of the data used for drawing plot(s). \u001b[1mperformance\u001b[0m: the performance of configurations from experiment(s), the parameters of configuration(s) from one crace run and the performance of configurations from one crace run."
+    },
+    {
+        "name": "numConfigurations",
+        "type": "s",
+        "short": "-nc",
+        "long": "--num-configurations",
+        "default": null,
+        "domain": "(all, final, elites, else)",
+        "section": "Plot options",
+        "critical": 0,
+        "description": "The number of configurations used to draw plot.",
+        "vignettes": "The number of configurations used to draw plot: \n\telites: all elitist configurations selected in slice. \n\tfinal: the final best configurations returned by crace. \n\tall: all elite configurations selected in slice. "
+    },
+    {
+        "name": "selConfigurations",
+        "type": "l",
+        "short": "-sc",
+        "long": "--select-configurations",
+        "default": null,
+        "domain": null,
+        "section": "Plot options",
+        "critical": 0,
+        "description": "The seleceted configurations used to draw plot.",
+        "vignettes": "The selected of configurations used to draw plot, which is avaliable only when \u001b[1melse\u001b[0m is selected for \u001b[4mnumConfigurations\u001b[0m."
+    },
+    {
+        "name": "slice",
+        "type": "u",
+        "short": "-sl",
+        "long": "--slice",
+        "default": null,
+        "domain": "Union[Literal['budget','b','experiment','e','exp','time','t','T'], bool, None]",
+        "section": "Plot options",
+        "critical": 0,
+        "description": "Split slice based on the default or budgets.",
+        "vignettes": "Split \u001b[1mslice\u001b[0m based on the default that is related to model updating, or budget that could be the number of executions or runtime. \nBy default, it's None, which means not to split the information when plotting."
+    },
+    {
+        "name": "split",
+        "type": "u",
+        "short": "-sp",
+        "long": "--split",
+        "default": null,
+        "domain": "Union[list[int], list[float], None]",
+        "section": "Plot options",
+        "critical": 0,
+        "description": "Addtional option for \u001b[1mslice\u001b[0m.",
+        "vignettes": "Addtional option used for \u001b[1mslice\u001b[0m. Use a list of integer values to select specific slices splited based on model updating, which is the default split method in crace, and a list of numbers to select specific slices splited based on budget. For the latter case, this list is used to partition the budget on a logarithmic scale."
+    },
+    {
+        "name": "source",
+        "type": "s",
+        "short": "-so",
+        "long": "--source",
+        "default": null,
+        "domain": "(test, training)",
+        "section": "Plot options",
+        "critical": 0,
+        "description": "The type of results from provided Crace, training or testing.",
+        "vignettes": "The type of configurations from provided Crace results. \\begin{itemize}\\item[] \u001b[1mtest\u001b[0m: select configurations in the test part.\\item[] \u001b[1mtraining\u001b[0m: select configurations in the training part.\\end{itemize}"
+
+    },
+    {
+        "name": "keyParameter",
+        "type": "s",
+        "short": "-kp",
+        "long": "--key-parameter",
+        "default": null,
+        "section": "Plot options",
+        "critical": 0,
+        "description": "This parameter is selected to be the key variable when drawing parallelcoord, pairplot.",
+        "vignettes": "This parameter is selected to be the key variable shown in plot \u001b[1mparallelcoord\u001b[0m or \u001b[1mpairplot\u001b[0m. For example: if one parameter is provided as the key variable for \u001b[1mparallelplot\u001b[0m, the plot will be grouped by this parameter."
+    },
+    {
+        "name": "multiParameters",
+        "type": "l",
+        "short": "-mp",
+        "long": "--multi-parameters",
+        "domain":null,
+        "default": null,
+        "section": "Plot options",
+        "critical": 0,
+        "description": "Multiple parameters provided to draw plot like scatter matrix.",
+        "vignettes": "Multiple parameters provided to draw plot like scatter matrix for the provided Crace results."
+    },
+    {
+        "name": "dpi",
+        "type": "i",
+        "short": "-dpi",
+        "long": "--dpi",
+        "default": 800,
+        "domain": "(50,2000)",
+        "section": "Plot options",
+        "critical": 1,
+        "description": "The parameter dpi used for saving plot.",
+        "vignettes": "When method used to draw a plot will export a plot file, this parameter will be added to control the dpi quality of the exported plot."
+    },
+    {
+        "name": "showfliers",
+        "type": "b",
+        "short": "-sf",
+        "long": "--showfliers",
+        "default": 0,
+        "critical": 1,
+        "section": "Plot options",
+        "description": "The parameter showfliers used for saving plot.",
+        "vignettes": "Enable\/disable showfliers when drawing the plot."
+    },
+    {
+        "name": "showmeans",
+        "type": "b",
+        "short": "-sm",
+        "long": "--showmeans",
+        "default": 0,
+        "section": "Plot options",
+        "critical": 1,
+        "description": "The parameter showmeans used for saving plot.",
+        "vignettes": "Enable\/disable showmeans when drawing the plot."
+    },
+    {
+        "name": "showscale",
+        "type": "b",
+        "short": "-ss",
+        "long": "--showscale",
+        "default": 0,
+        "section": "Plot options",
+        "critical": 1,
+        "description": "The parameter showscale used for saving plot.",
+        "vignettes": "Enable\/disable showscale when drawing the plot especially for \u001b[1mparallelcoord\u001b[0m."
+    },
+    {
+        "name": "statisticalTest",
+        "type": "b",
+        "short": "-st",
+        "long": "--stest",
+        "default": 0,
+        "section": "Plot options",
+        "critical": 0,
+        "description": "Add p-values for plots or not.",
+        "vignettes": "Enable\/disable add p-values when drawing the plot."
+    }
+]