Metadata-Version: 2.4
Name: craceplot
Version: 0.1.1
Summary: craceplot: Visualisation of Data from crace
Author: Yunshuang Xiao
Maintainer-email: crace developers <race.autoconfig@gmail.com>, Yunshuang Xiao <yunshuang.xiao@ulb.be>
License-Expression: GPL-3.0-or-later
Project-URL: Homepage, https://race-autoconfig.github.io/craceplot/
Project-URL: Source, https://github.com/race-autoconfig/craceplot/
Project-URL: Tracker, https://github.com/race-autoconfig/craceplot/issues
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: crace>=0.1.0
Requires-Dist: matplotlib>=3.3.4
Requires-Dist: numpy>=1.19.5
Requires-Dist: pandas>=1.0.5
Requires-Dist: plotly>=5.0.0
Requires-Dist: scikit-learn>=0.24.2
Requires-Dist: scikit_posthocs>=0.6.7
Requires-Dist: scipy>=1.5.4
Requires-Dist: seaborn>=0.11.0
Requires-Dist: statannotations>=0.5.0
Requires-Dist: statsmodels>=0.12.2
Dynamic: license-file

**craceplot**: Visualisation of Data from crace
===========================================

<!-- badge start -->
[![PyPI](https://img.shields.io/pypi/v/craceplot?cacheSeconds=3600)][craceplot-pycode]
[![Python](https://img.shields.io/pypi/pyversions/craceplot?cacheSeconds=3600)][craceplot-pycode]
[![Docs](https://img.shields.io/badge/docs-online-blue?cacheSeconds=3600)][craceplot-homepage]
[![License](https://img.shields.io/github/license/race-autoconfig/craceplot?cacheSeconds=3600)](docs/references/license.md)
<!-- badge end -->

<!-- link start -->
[ [**Homepage**][craceplot-homepage] ] [
[**Source Code**][craceplot-src] ] [
[**User Guide**][craceplot-guide] ] [
[**Report A Bug**](https://github.com/race-autoconfig/craceplot/issues) ] [
[**Discussions**](https://github.com/race-autoconfig/craceplot/discussions) ]
<!-- link end -->

<!-- authors start -->
**Authors:** Yunshuang Xiao [![ORCID][orcid-icon]](https://orcid.org/0009-0003-6752-8627).

**Contact**: crace developers [race.autoconfig@gmail.com](mailto:race.autoconfig@gmail.com)
<!-- authors end -->

<!-- literature start-->
**Relevant literature:**

-  Yunshuang Xiao, Leslie Pérez Cáceres, Manuel López-Ibáñez, and Thomas Stützle. 
   [**Algorithm Configuration via Continuously Racing: Preliminary Results**](
    https://doi.org/10.1145/3583133.3596408). *In Proceedings 
   of the Companion Conference on Genetic and Evolutionary Computation (GECCO '23 Companion
   )*. Association for Computing Machinery, New York, NY, USA, 1744–1752. 
   doi: 10.1145/3583133.3596408
<!-- literature end -->

---
<!-- introduction start-->
# Introduction

The craceplot package provides a set of functions to create plots to visualize the 
data generated by the crace software for automatic algorithm configuration 
(hyper-parameter optimization).

This package provides visualizations for:

- Parameter configurations using parallel coordinates with `param_parallelcoord`. 
  <!-- or `param_parallelcat`. -->

- Configurations performance (training and testing) with `qual_boxplot`, 
  `qual_heatmap` and `qual_scatter`.

- Sampling distributions with `param_boxplot`, `param_histplot`, `param_pairplot`, 
  `param_heatmap`, `param_jointplot` and `param_sunburst`.

For more details about these functions, please check the user guide of the package 
and the documentation of the functions implemented in the package.

The aim of this package is to provide support for the analysis of the single crace 
run and its best parameter settings found, the assessment of the parameter space 
explored by crace and the overall performance of the configuration process. 

**Keywords**: automatic configuration, offline tuning, parameter tuning, parameter 
visualization, crace.


---
## Requisites

Python ($\text{version} \geq 3.8.0$) is required for running craceplot, but you don't need to 
know the Python language to use it. Python is freely available and you can download it 
from the [Python project website](https://www.python.org/). See [Quick Start](#quick-start) 
for a quick installation guide of Python.
<!-- introduction end -->

---
## User guide

A complete user guide comes with a IPython Notebook file.
You can access it online [guide][craceplot-guide] or, after installing the craceplot package,
invoking from the terminal console using the following command:
``` bash
craceplot doc
```

The following is a quick-start guide. The user guide gives more detailed instructions.


---
<!-- quick user guide start -->
# Quick Start

-  Install Python (with your favorite package manager, and see more details below).
  
-  Install crace. The crace package can be installed automatically with conda, with pip 
    or from the source code. We advise to use the automatic installation unless particular 
    circumstances do not allow it. 

-  You can open the user guide with the following command. This command
    works on Bash shell (Linux and MacOS) and Powershell (Windows)
    with the active environment added to PATH (see detailed instructions below).


---
<!-- install python start -->
## Installing Python

This section gives a quick Python installation guide that will work in most cases. 
The official instructions are available at [official python site](
    https://www.python.org/about/gettingstarted/). 

### GNU/Linux

You should install Python from your package manager. On a Debian/Ubuntu system 
it will be something like:
```bash
sudo apt-get install python3 python3-dev
```

Once Python is installed, you can use conda, pip or the source code to install 
the crace package. See instructions below.

### macOS

For macOS 10.9 (Jaguar) up until 12.3 (Catalina) the operating system includes 
Python 2, which is no longer supported and is not a good choice for development. 
You should go to do the [official downloads page](https://www.python.org/downloads/) 
and download the installer.

For newer versions of macOS, Python is no longer included by default and you 
will have to download and install it. You can refer to the [Python documentation]
(https://docs.python.org/3/using/mac.html) for more details on the installation 
process and getting started.

Alternatively, you can just brew the Python formula from the science 
tap (unfortunately it does not come already bottled so you need to have Xcode 
(https://developer.apple.com/xcode/download/) installed to compile it):
```bash
# install homebrew if you don’t have it
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# install python 3
brew tap homebrew/science
brew install python
```

Once Python is installed, you can use conda, pip or the source code to
install the craceplot package (see section [Quick Start](#quick-start)).

### Windows

You can install Python from the [official website](https://www.python.org/downloads/windows).
We recommend that you install Python on a filesystem path without spaces, special characters 
or long names, such as `C:\Python`.

Note that Python 3.5 - 3.8 cannot be used on Windows XP or earlier and Python 3.9 - 3.13 
cannot be used on Windows 7 or earlier.  


<!-- venv start -->
### Virtual environment of Python 3

Once Python is installed, you can use conda, pip or the source code to
install the craceplot package (see section [Quick Start](#quick-start)).

Python 3 allows you to manage separate package installations for different 
projects using environment. It creates a “virtual” isolated Python installation. 
When you switch projects, you can create a new virtual environment which is isolated from 
other virtual environments. You benefit from the virtual environment since packages can be 
installed confidently and will not interfere with another project’s environment.

####  Create a new virtual environment.
To create a virtual environment, go to your project’s directory and run the following command. 
This will create a new virtual environment in a local folder named .venv:

```bash
# Unix/macOS
python3 -m venv .venv
```

```powershell
# Windows
py -m venv .venv
```

The second argument is the location to create the virtual environment. Generally, you can 
just create this in your project and call it $.venv$.

venv will create a virtual Python installation in the .venv folder.

#### Activate a virtual environment.

Before you can start installing or using packages in your virtual environment you’ll need 
to activate it. Activating a virtual environment will put the virtual environment-specific 
python and pip executables into your shell’s PATH.

```bash
# Unix/macOS
source .venv/bin/activate
```

```powershell
# Windows
.venv\Scripts\Activate.PS1
```

To confirm the virtual environment is activated, check the location of your Python interpreter:

```bash
# Unix/macOS
which python
```
```powershell
# Windows
where python
```

While the virtual environment is active, the above command will output a filepath that includes 
the .venv directory, by ending with the following:

```bash
# Unix/macOS
.venv/bin/python
```
```powershell
# Windows
.venv\Scripts\python
```

While a virtual environment is activated, pip will install packages into that specific environment. 
This enables you to import and use packages in your Python application.

#### Deactivate a virtual environment.

If you want to switch projects or leave your virtual environment, deactivate the environment:

```bash
deactivate
```

#### Reactivate a virtual environment.

If you want to reactivate an existing virtual environment, follow the same instructions about 
activating a virtual environment. There’s no need to create a new virtual environment.
<!-- venv end -->
<!-- install python end -->


---
<!-- install craceplot start -->
## Installing the craceplot package

### Requirements
- Python (>= 3.6.0) is required for running craceplot package. 
- crace is required for running craceplot package, and you must have
  completed log files from one crace run in advance. See
  [crace user guide (pdf)](https://race-autoconfig.github.io/crace/crace-package.pdf) 
  or its [quick start](https://race-autoconfig.github.io/crace) for installing crace and
  obtaining log files.

The craceplot package can be installed automatically with conda, with pip or from the source.
We advise to use the automatic installation unless particular circumstances do not allow it. 
The instructions to install craceplot with the three mentioned methods are the following:

### Install automatically with conda

If you use Conda, execute the following line at the shell to install the package:

```bash
# Use the environment where you install crace
conda create -n my-env
conda activate my-env
# If you want to install from conda-forge
conda config --env --add channels conda-forge
# The actual install command
conda install craceplot
```

Alternatively, within the Conda graphical interface (Anaconda Navigator), you may search and 
install craceplot.

### Install automatically with pip

If you use pip, execute the following line at the shell to install the package:
```bash
pip3 install craceplot
```

Also when using pip, it's good practice to use a virtual environment and here is the 
[guide](https://dev.to/bowmanjd/python-tools-for-managing-virtual-environments-3bko#howto)
for using the virtual environment.


### Manual download and installation from source

If the previous installation instructions fail because of insufficient
permissions and you do not have sufficient admin rights to install ©****
system-wide, then you need to force a local installation. 
From the craceplot package [PyPI website][craceplot-pycode], search and download one of the 
two available versions depending on your operating system:

- `craceplot-xxx.tar.gz` (Unix/Linux/BSD/macOS)
- `craceplot-xxx-py3-none-any.whl` (python3, any platform)


Alternatively, you can use wget or curl from the command line to download the file: 
```bash
# PyPI
wget https://files.pythonhosted.org/packages/source/c/craceplot/craceplot-xxx.tar.gz
# Github
wget https://github.com/race-autoconfig/craceplot/
```

To install the package on GNU/Linux, macOS or Windows using the formats .tar.gz,
you should first extract the source files and then navigate to the directory 
containing the extracted files and run the following command to install the package: 

```bash
python3 install .
```

To install the package on any platform using the Wheel format, you should run the following command to install the package:

```bash
pip3 install /path/to/craceplot-xxx-py3-none-any.whl
```

---
## Testing the installation and invoking craceplot

Once crace has been installed, it can be listed by using command line at the shell:
```bash
# List installed packages at the shell
pip3 list
# Show the information of craceplot at the shell
pip3 show craceplot
```

or load the package and test that the installation
was successful by opening a Python console and executing:
```python
# Load and test at the Python console
import craceplot
print(craceplot.__version__)
```


### Checking the installation path of craceplot
Once craceplot is installed, the executable command will be added to the environment. 
To check the installation path of craceplot using command line at the shell:
```bash
which craceplot
```

The output of this line must be `$PYTHON_HOME/bin/craceplot`, which means
the path before `/bin/craceplot` is `$PYTHON_HOME`. Here, `$CRACEPLOT_HOME` should be:
```bash
CRACEPLOT_HOME=$PYTHON_HOME/lib/python3.X/site-packages/craceplot
```

Also, you can check the installation path of craceplot opening a Python console 
and executing:
```python
print(craceplot.where().path)
# or
print(craceplot.which().path)
```

This command must print out the filesystem path where craceplot is installed. 
In the remainder of this guide, the variable `$CRACEPLOT_HOME` is used to
denote this path. When executing any provided command that includes the 
`$CRACEPLOT_HOME` variable, do not forget to replace it with the true
installation path of craceplot.

On GNU/Linux or macOS, you can let the operating system know where to find 
craceplot by defining the `$PYTHON_HOME` variable and adding it to the system
`PATH`. Append the following commands to `~/.bash_profile`, 
`~/.bashrc` or `~/.profile`:
```bash
# Replace <CRACEPLOT_HOME> with the craceplot installation path
export CRACEPLOT_HOME=<CRACEPLOT_HOME>
# Tell operating system where to find craceplot
export PATH=${PYTHON_HOME}/bin/:$PATH
```

Then, open a new terminal and launch craceplot as follows:

```bash
craceplot --help
```

Alternatively, you may directly invoke craceplot within the Python
console by executing:
```python
import craceplot
craceplot.run("--help")
```


---
# License

The craceplot package is Copyright © 2026 and distributed under the [GNU 
General Public License version 3.0](http://www.gnu.org/licenses/gpl-3.0.en.html).

This program is free software (software libre): you can redistribute it and/or 
modify it under the terms of the GNU General Public License as published by the 
Free Software Foundation, either version 3 of the License, or (at your option) 
any later version.

This program 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. 

**IMPORTANT NOTE:** Please be aware that the fact that this program is released as Free Software 
does not excuse you from scientific propriety, which obligates you to give 
appropriate credit! If you write a scientific paper describing research that 
made substantive use of this program, it is your obligation as a scientist to 
(a) mention the fashion in which this software was used in the Methods section; 
(b) mention the algorithm in the References section. 
The 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. 
  doi: [10.1145/3583133.3596408](https://doi.org/10.1145/3583133.3596408)


craceplot is built as an additional tool for the crace package:
  crace: Continuous Racing for Automatic Algorithm Configuration
  Copyright (c) 2026 crace developers



<!-- [craceplot-guide]: https://race-autoconfig.github.io/craceplot/guide.html -->
[craceplot-guide]: https://race-autoconfig.github.io/craceplot/user%20guide/index.html
[craceplot-homepage]: https://race-autoconfig.github.io/craceplot/
[craceplot-src]: https://github.com/race-autoconfig/craceplot/
[craceplot-pycode]: https://pypi.org/project/craceplot/
[orcid-icon]: https://orcid.org/sites/default/files/images/orcid_16x16.png
