# MK8D

Python package for "Mario Kart 8 Deluxe" livesplit data analysis.  It processes Livesplit *LSS* files (*XML* format) to provide a cleaner way to analyze the data by re-shaping it to a dataframe. Pypi: https://pypi.org/project/MK8D/ 


This [pip](https://pypi.org/project/MK8D/) package is an improvement upon the [mk8dLivesplit](https://github.com/Chipdelmal/mk8dLivesplit) implementation. The main change is that it handles runs in a dataframe for easier parsing and filtering (sacrificing a bit of processing speed).
 
## Features

* Streamlined conversion from *LSS* to *CSV* dataframe
* Combine different *LSS* files into one dataframe automatically
* Plot and compare runs 
  * Full run
  * Individual Tracks

## Basic Usage

Install the package with:

```bash
pip install MK8D
```

To convert an LSS file into a CSV dataframe, run:

```bash
MK8D_lss2csv INPUT_FOLDER OUTPUT_FOLDER OUTPUT_FILENAME
```

where **INPUT_FOLDER** is the path to the directory where the *LSS* files are stored, **OUTPUT_FOLDER** is the location in which we want our files to be exported to, and **OUTPUT_FILENAME** is the name of the *CSV* file to be exported.

For example, if run from the repository directory:

```bash
MK8D_trk2csv ./MK8D/dev/data ./MK8D/dev/data MK8D_trks.csv
K8D_run2csv ./MK8D/dev/data/MK8D_trks.csv ./MK8D/dev/data MK8D_runs.csv max
```

would take every *LSS* file found in the `./MK8D/dev/data` and compile a dataframe to a *CSV* file, which would be exported to the same folder.

## Dataframe Head

There are two dataframe types generated by the package: **Tracks (trks)**, and **Runs (runs)**.
### Tracks

* ID: yy/mm/dd (file:rid)
* Track: MK8D track name
* Time: Time elapsed in the track/split (seconds)
* Version: Digital/Cartridge
* Items: Items/No Items
* Speed: 50cc, 100cc, 150cc, 200cc
* Category: Speedrun category (32 tracks, 48 tracks, etc)

### Runs

* ID: yy/mm/dd (file:rid)
* Track: MK8D track name
* Time: Time elapsed in the track/split (seconds)
* Version: Digital/Cartridge
* Items: Items/No Items
* Speed: 50cc, 100cc, 150cc, 200cc
* Category: Speedrun category (32 tracks, 48 tracks, etc)
* Split: Human-readable split time
* Center *metric*: Statistic calculated for each track across runs (mean, median, min, max)
* Center offset: Time as compared to the "center" statistic of the track (mean, median, min, max)

## Dependencies

[Pandas](https://pandas.pydata.org/), [Numpy](https://numpy.org/), [Plotly](https://plotly.com/), [Plotly Express](https://plotly.com/python/plotly-express/), [Matplotlib](https://matplotlib.org/), [Colour](https://pypi.org/project/colour/), [XMLToDict](https://pypi.org/project/xmltodict/)

## To do

- [x] Fix bug with tracks sorting
- [x] Add attempt date support
- [x] Create command line tool
- [ ] Auto-export plots
- [x] Export violin plots
- [ ] Add tracks filter to violin plots
- [x] Highlight PB
- [x] Add stats to plots
- [x] Create progress plot
- [x] Make timings readable
- [x] Fix the milliseconds formatting
- [ ] Create non-interactive versions of the plots
- [ ] Add stats to violins
- [ ] Add tracks order master file support

##  Author

<img src="https://raw.githubusercontent.com/Chipdelmal/WaveArt/master/media/pusheen.jpg" height="130px" align="middle"><br>

[Héctor M. Sánchez C.](https://chipdelmal.github.io/blog)

