# angels

数据分析过程工具整合包，包含数据获取、数据清洗、逻辑加工、分析算法、可视化等五个核心模块。

## 安装

```bash
pip install angels
```

## 打包说明

本项目使用现代的 `pyproject.toml` 打包方式，替代了传统的 `setup.py`。

## 核心模块

### 1. 数据获取 (data_acquisition)

- `load_csv(file_path)`: 加载CSV文件并返回DataFrame
  - `file_path` (str): CSV文件的路径
  - 返回: `pd.DataFrame` - 从CSV文件加载的数据

- `load_excel(file_path, sheet_name=0)`: 加载Excel文件并返回DataFrame
  - `file_path` (str): Excel文件的路径
  - `sheet_name` (int, str, optional): 要加载的工作表名称或索引，默认为0
  - 返回: `pd.DataFrame` - 从Excel文件加载的数据

- `load_json(file_path)`: 加载JSON文件并返回DataFrame
  - `file_path` (str): JSON文件的路径
  - 返回: `pd.DataFrame` - 从JSON文件加载的数据

- `load_from_api(url, params=None)`: 从API获取数据并返回DataFrame
  - `url` (str): API的URL地址
  - `params` (dict, optional): 发送到API的参数，默认为None
  - 返回: `pd.DataFrame` - 从API获取的数据
  - 异常: `requests.exceptions.HTTPError` - 如果API请求失败

- `load_from_web(url, table_selector)`: 从网页表格获取数据并返回DataFrame
  - `url` (str): 网页的URL地址
  - `table_selector` (str): 用于选择表格的CSS选择器
  - 返回: `pd.DataFrame` - 从网页表格获取的数据
  - 异常: `requests.exceptions.HTTPError` - 如果网页请求失败

- `fetch_dataframe(sql, db_name='rpt')`: 从数据库执行SQL查询并返回DataFrame
  - `sql` (str): 要执行的SQL查询语句
  - `db_name` (str, optional): 数据库标识，默认为'rpt'
  - 返回: `pd.DataFrame` - 查询结果的DataFrame，如果没有数据则返回空DataFrame
  - 异常: `ValueError` - 如果指定的数据库标识不存在
  - 异常: `Exception` - 如果执行SQL查询时发生错误

- `fetch_data_from_db(tbl_name, order_sql, db_name, batch_size=20000, batch_no=0)`: 从数据库批量获取数据并保存为Parquet文件
  - `tbl_name` (str): 表名
  - `order_sql` (str): 排序字段
  - `db_name` (str): 数据库标识
  - `batch_size` (int, optional): 每批获取的记录数，默认为20000
  - `batch_no` (int, optional): 起始批次号，默认为0
  - 返回: `int` - 实际执行的批次数
  - 异常: `ValueError` - 如果指定的数据库标识不存在
  - 异常: `Exception` - 如果执行SQL查询时发生错误

- `concat_tbl_data(tbl_name)`: 合并多个Parquet文件为一个文件
  - `tbl_name` (str): 表名，用于搜索和命名文件
  - 返回: `None`
  - 功能: 自动搜索当前目录中以 `tbl_name_` 开头并以 `.pqt` 结尾的文件，将它们合并为一个名为 `tbl_name.pqt` 的文件

### 2. 数据清洗 (data_cleaning)

- `remove_duplicates(df)`: 移除重复行
- `handle_missing_values(df, strategy='drop', fill_value=None)`: 处理缺失值
- `convert_data_types(df, dtypes=None)`: 转换数据类型
- `remove_outliers(df, columns=None, method='iqr', threshold=1.5)`: 移除异常值
- `standardize_columns(df)`: 标准化列名

### 3. 逻辑加工 (logic_processing)

- `group_by_aggregate(df, group_by, aggregations)`: 按列分组并聚合
- `pivot_table(df, index, columns, values, aggfunc='mean')`: 创建透视表
- `calculate_rolling_stats(df, column, window, stats=['mean', 'std'])`: 计算滚动统计量
- `calculate_diff(df, column, periods=1)`: 计算差值
- `merge_dataframes(df1, df2, on=None, how='inner')`: 合并数据框
- `create_features(df)`: 创建特征

### 4. 分析算法 (analysis_algorithms)

- `descriptive_statistics(df)`: 计算描述性统计量
- `correlation_analysis(df, method='pearson')`: 计算相关性矩阵
- `kmeans_clustering(df, n_clusters=3, random_state=42)`: K均值聚类
- `linear_regression(X, y)`: 线性回归
- `time_series_analysis(df, time_column, value_column)`: 时间序列分析
- `hypothesis_testing(sample1, sample2)`: 假设检验

### 5. 可视化 (visualization)

- `plot_histogram(df, column, bins=30, title=None)`: 绘制直方图
- `plot_scatter(df, x, y, hue=None, title=None)`: 绘制散点图
- `plot_bar(df, x, y, title=None)`: 绘制柱状图
- `plot_box(df, x, y=None, title=None)`: 绘制箱线图
- `plot_correlation_heatmap(df, title=None)`: 绘制相关性热图
- `plot_time_series(df, x, y, title=None)`: 绘制时间序列图

## 使用示例

```python
from angels import *

# 1. 数据获取
df = load_csv('data.csv')

# 2. 数据清洗
df = remove_duplicates(df)
df = handle_missing_values(df, strategy='mean')
df = standardize_columns(df)

# 3. 逻辑加工
df = group_by_aggregate(df, 'category', {'value': 'sum'})

# 4. 分析算法
stats = descriptive_statistics(df)
corr = correlation_analysis(df)

# 5. 可视化
plt = plot_histogram(df, 'value')
plt.show()

plt = plot_correlation_heatmap(df)
plt.show()
```

## 依赖

- pandas
- numpy
- matplotlib
- seaborn
- scikit-learn
- requests
- beautifulsoup4
