Metadata-Version: 2.4
Name: doloris
Version: 0.3.0
Summary: Detection Of Learning Obstacles via Risk-aware Interaction Signals
Author-email: 许睿林 <xurlin5@mail2.sysu.edu.cn>, 傅小桐 <fuxt5@mail2.sysu.edu.cn>
License-Expression: MIT
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: gradio
Requires-Dist: pandas
Requires-Dist: tqdm
Requires-Dist: scikit-learn
Requires-Dist: seaborn
Dynamic: license-file

# Doloris

[![PyPI Version](https://img.shields.io/pypi/v/doloris)](https://pypi.org/project/doloris/)

中山大学 2025 年《模式识别》课程大作业项目

组员：许睿林、傅小桐

**Doloris**（**D**etection **O**f **L**earning **O**bstacles via **R**isk-aware **I**nteraction **S**ignals）是一款用于基于交互信号分析学习障碍的检测系统。它支持用户友好的命令行界面、可视化面板以及灵活的机器学习模型配置，适用于教育行为数据分析与预测任务。

![img](./assets/panel.png)

## 🔧 安装方式

### 用户安装（推荐）

使用 pip 一键安装：

```bash
pip install doloris
```

### 开发者模式安装

若你正在开发或调试本项目，建议使用源码安装：

```bash
pip install .
```

安装完成后可通过下列命令验证版本：

```bash
doloris version
```

## 🚀 快速开始

### 启动可视化面板

运行以下命令以启动 Doloris 的交互式面板（默认缓存路径为 `.doloris/`）：

```bash
doloris panel --cache-path <缓存目录路径>
```

可选参数：

* `--cache-path`：指定缓存数据的目录路径（默认 `.doloris/`）
* `--share`：是否开启公网访问链接（默认 False）

### 运行模型算法

Doloris 提供命令行方式运行学习障碍检测算法，算法运行可视化结果保存在缓存路径下的 `algorithm_output` 文件夹：

```bash
doloris algorithm --cache-path <缓存目录路径> \
                  --label-type <binary|multiclass> \
                  --feature-cols <特征列1,特征列2,...> \
                  --model-name <模型名称>
```

可用参数说明：

* `--cache-path`：指定缓存数据的目录路径（默认 `.doloris/`）
* `--label-type`：指定标签类型（默认：`binary`），可选值：`binary`, `multiclass`
* `--feature-cols`：用逗号分隔的特征列名（默认为预设特征）
* `--model-name`：选择的模型名称，支持如下几种：

  * `logistic_regression`
  * `random_forest`
  * `knn`
  * `svm`
  * `sgd`
  * `mlp`

示例命令：

```bash
doloris algorithm --label-type binary --model-name random_forest
```

## 🧠 默认特征说明

默认使用以下交互特征进行建模：

* age\_band
* highest\_education
* imd\_band
* num\_of\_prev\_attempts
* studied\_credits
* total\_n\_days
* avg\_total\_sum\_clicks
* n\_days\_oucontent
* avg\_sum\_clicks\_quiz
* avg\_sum\_clicks\_forumng
* avg\_sum\_clicks\_homepage

你也可以通过 `--feature-cols` 参数自定义特征列表。
