对surprise一些解释 以及用法.md

0. 参考

文章来源
其他用法
其他用法2
记录使用时候遇到的坑
surprise原始库

1. 1解释一下什么是raw_id和inner_id？

    i. 用户和项目有自己的raw_id和inner_id，原生id是评分文件或者pandas数据集中定义的id，重点在于要知道你使用predict()或者其他方法时候接收原生的id
    ii. 在训练集创建时，每一个原生的id映射到inner id（这是一个唯一的整数，方便surprise操作），原生id和内部id之间的转换可以用训练集中的to_inner_uid(), to_inner_iid(), to_raw_uid(), 以及to_raw_iid()方法

1.2 默认数据集下载到了哪里？怎么修改这个位置

    i. 默认数据集下载到了——“~/.surprise_data”中
    ii. 如果需要修改，可以通过设置“SURPRISE_DATA_FOLDER”环境变量来修改位置

2API合集

2.1推荐算法包

    random_pred.NormalPredictor Algorithm predicting a random rating based on the distribution of the training set, which is assumed to be normal.
    baseline_only. BaselineOnly Algorithm predicting the baseline estimate for given user and item.
    knns.KNNBasic A basic collaborative filtering algorithm.
    knns.KNNWithMeans A basic collaborative filtering algorithm, taking into account the mean ratings of each user.
    knns.KNNWithZScore A basic collaborative filtering algorithm, taking into account the z-score normalization of each user.
    knns.KNNBaseline A basic collaborative filtering algorithm taking into account a baseline rating.
    matrix_factorization.SVD The famous SVD algorithm, as popularized by Simon Funk during the Netflix Prize.
    matrix_factorization.SVDpp The SVD++ algorithm, an extension of SVD taking into account implicit ratings.
    matrix_factorization.NMF A collaborative filtering algorithm based on Non-negative Matrix Factorization.
    slope_one.SlopeOne A simple yet accurate collaborative filtering algorithm.
    co_clustering.CoClustering A collaborative filtering algorithm based on co-clustering.

2.2 推荐算法基类

2.2.1 class surprise.prediction_algorithms.algo_base.AlgoBase(**kwargs)

2.2.2如果算法需要计算相似度，那么baseline_options参数可以用来配置

2.2.3方法介绍：

2.2.3.1compute_baselines() 计算用户和项目的基线，这个方法只能适用于Pearson相似度或者BaselineOnly算法，返回一个包含用户相似度和用户相似度的元组

2.2.3.2 compute_similarities() 相似度矩阵，计算相似度矩阵的方式取决于sim_options算法创建时候所传递的参数，返回相似度矩阵

2.2.3.3default_preditction() 默认的预测值，如果计算期间发生了异常，那么预测值则使用这个值。默认情况下时所有评分的均值（可以在子类中重写，以改变这个值），返回一个浮点类型

2.2.3.4fit(trainset) 在给定的训练集上训练算法，每个派生类都会调用这个方法作为训练算法的第一个基本步骤，它负责初始化一些内部结构和设置self.trainset属性，返回self指针

2.2.3.5 get_neighbors(iid, k) 返回inner id所对应的k个最近邻居的，取决于这个iid所对应的是用户还是项目（由sim_options里面的user_based是True还是False决定），返回K个最近邻居的内部id列表

2.2.3.6 predict(uid, iid, r_ui=None, clip=True, verbose=False) 计算给定的用户和项目的评分预测，该方法将原生id转换为内部id，然后调用estimate每个派生类中定义的方法。如果结果是一个不可能的预测结果，那么会根据default_prediction()来计算预测值

            另外解释一下clip，这个参数决定是否对预测结果进行近似。举个例子来说，如果预测结果是5.5，而评分的区间是[1,5]，那么将预测结果修改为5；如果预测结果小于1，那么修改为1。默认为True
            verbose参数决定了是否打印每个预测的详细信息。默认值为False
            返回值，一个rediction对象，包含了：
                a) 原生用户id
                b) 原生项目id
                c) 真实评分
                d) 预测评分
                e) 可能对后面预测有用的一些其他的详细信息

2.2.3.7 test(testset, verbose=False) 在给定的测试集上测试算法，即估计给定测试集中的所有评分。返回值是prediction对象的列表

2.2.3.8

2.3 预测模块

2.3.1 surprise.prediction_algorithms.predictions模块定义了Prediction命名元组和PredictionImpossible异常

2.3.2Prediction

2.3.2.1用于储存预测结果的命名元组

2.3.2.2仅用于文档和打印等目的

2.3.2.3 参数：

            uid 原生用户id
            iid 原生项目id
            r_ui 浮点型的真实评分
            est 浮点型的预测评分
            details 预测相关的其他详细信息

2.3.3 surprise.prediction_algorithms.predictions.PredictionImpossible

2.3.3.1当预测不可能时候，出现这个异常

2.3.3.2 这个异常会设置当前的预测评分变为默认值（全局平均值）

2.4 model_selection包

2.4.1 交叉验证迭代器

2.4.1.1 该模块中包含各种交叉验证迭代器：

            KFold 基础交叉验证迭代器
            RepeatedKFold 重复KFold交叉验证迭代器
            ShuffleSplit 具有随机训练集和测试集的基本交叉验证迭代器
            LeaveOneOut 交叉验证迭代器，其中每个用户再测试集中只有一个评级
            PredefinedKFold 使用load_from_folds方法加载数据集时的交叉验证迭代器

2.4.1.2 该模块中还包含了将数据集分为训练集和测试集的功能

            train_test_split(data, test_size=0,2, train_size=None, random_state=None, shuffle=True)
                 data，要拆分的数据集
                 test_size，如果是浮点数，表示要包含在测试集中的评分比例；如果是整数，则表示测试集中固定的评分数；如果是None，则设置为训练集大小的补码；默认为0.2
                 train_size，如果是浮点数，表示要包含在训练集中的评分比例；如果是整数，则表示训练集中固定的评分数；如果是None，则设置为训练集大小的补码；默认为None
                 random_state，整形，一个随机种子，如果多次拆分后获得的训练集和测试集没有多大分别，可以用这个参数来定义随机种子
                 shuffle，布尔值，是否在数据集中改变评分，默认为True

2.4.2 交叉验证

        surprise.model_selection.validation.cross_validate(algo, data, measures=[u'rmse'，u'mae'], cv=None, return_train_measures=False, n_jobs=1, pre_dispatch=u'2 * n_jobs', verbose=False)
            ® algo，算法
            ® data，数据集
            ® measures，字符串列表，指定评估方案
            ® cv，交叉迭代器或者整形或者None，如果是迭代器那么按照指定的参数；如果是int，则使用KFold交叉验证迭代器，以参数为折叠次数；如果是None，那么使用默认的KFold，默认折叠次数5
            ® return_train_measures，是否计算训练集的性能指标，默认为False
            ® n_jobs，整形，并行进行评估的最大折叠数。如果为-1，那么使用所有的CPU；如果为1，那么没有并行计算（有利于调试）；如果小于-1，那么使用（CPU数目 + n_jobs + 1）个CPU计算；默认值为1
            ® pre_dispatch，整形或者字符串，控制在并行执行期间调度的作业数。（减少这个数量可有助于避免在分配过多的作业多于CPU可处理内容时候的内存消耗）这个参数可以是：
                 None，所有作业会立即创建并生成
                 int，给出生成的总作业数确切数量
                 string，给出一个表达式作为函数n_jobs，例如“2*n_jobs”
            默认为2*n_jobs
        返回值是一个字典：
            ® test_*，*对应评估方案，例如“test_rmse”
            ® train_*，*对应评估方案，例如“train_rmse”。当return_train_measures为True时候生效
            ® fit_time，数组，每个分割出来的训练数据评估时间，以秒为单位
            ® test_time，数组，每个分割出来的测试数据评估时间，以秒为单位

2.4.3 参数搜索

2.4.3.1 class surprise.model_selection.search.GridSearchCV(algo_class, param_grid, measures=[u’rmse’, u’mae’], cv=None, refit=False, return_train_measures=False, n_jobs=1, pre_dispatch=u’2 * n_jobs’, joblib_verbose=0)

            ® 参数类似于上文中交叉验证
            ® refit，布尔或者整形。如果为True，使用第一个评估方案中最佳平均性能的参数，在整个数据集上重新构造算法measures；通过传递字符串可以指定其他的评估方案；默认为False
            ® joblib_verbose，控制joblib的详细程度，整形数字越高，消息越多

2.4.3.2 内部方法：

            a) best_estimator，字典，使用measures方案的最佳评估值，对所有的分片计算平均
            b) best_score，浮点数，计算平均得分
            c) best_params，字典，获得measure中最佳的参数组合
            d) best_index，整数，获取用于该指标cv_results的最高精度（平均下来的）的指数
            e) cv_results，数组字典，measures中所有的参数组合的训练和测试的时间
            f) fit，通过cv参数给出不同的分割方案，对所有的参数组合计算
            g) predit，当refit为False时候生效，传入数组，见上文
            h) test，当refit为False时候生效，传入数组，见上文

2.4.3.3 class surprise.model_selection.search.RandomizedSearchCV（algo_class，param_distributions，n_iter = 10，measures = [u’rmse’，u’mae’]，cv = None，refit = False，return_train_measures = False，n_jobs = 1，pre_dispatch = u’2 * n_jobs’，random_state =无，joblib_verbose = 0 ）

        随机抽样进行计算而非像上面的进行琼剧

2.5 相似度模块

2.5.1 similarities模块中包含了用于计算用户或者项目之间相似度的工具：

1) cosine

2) msd

3) pearson

4) pearson_baseline

2.6 精度模块

2.6.1surprise.accuracy模块提供了用于计算一组预测的精度指标的工具：

2.6.1.1) rmse（均方根误差）

2.6.1.2) mae（平均绝对误差）

2.6.1.3) fcp

2.7 数据集模块

2.7.1dataset模块定义了用于管理数据集的Dataset类和其他子类

2.7.2 class surprise.dataset.Dataset（reader）

2.7.3内部方法：

2.7.3.1) load_builtin(name=u’ml-100k’)，加载内置数据集，返回一个Dataset对象

2.7.3. 2) load_from_df(df, reader)，df（dataframe），数据框架，要求必须具有三列（要求顺序），用户原生id，项目原生id，评分；reader，指定字段内容

2.7.3. 3) load_from_file(file_path, reader)，从文件中加载数据，参数为路径和读取器

2.7.3.4) load_from_folds(folds_files, reader)，处理一种特殊情况，movielens-100k数据集中已经定义好了训练集和测试集，可以通过这个方法导入

2.8 训练集类

2.8.1class surprise.Trainset(ur, ir, n_users, n_items, n_ratings, rating_scale, offset, raw2inner_id_users, raw2inner_id_items)

2.8.2属性分析：

2.8.2.1) ur，用户评分列表（item_inner_id，rating）的字典，键是用户的inner_id

2.8.2. 2) ir，项目评分列表（user_inner_id，rating）的字典，键是项目的inner_id

2.8.2.3) n_users，用户数量

2.8.2.4) n_items，项目数量

2.8.2.5) n_ratings，总评分数

2.8.2.6) rating_scale，评分的最高以及最低的元组

2.8.2. 7) global_mean，所有评级的平均值

2.8.3 方法分析：

2.8.3.1) all_items()，生成函数，迭代所有项目，返回所有项目的内部id

2.8.3.2) all_ratings(),生成函数，迭代所有评分，返回一个(uid, iid, rating)的元组

2.8.3. 3) all_users()，生成函数，迭代所有的用户，然会用户的内部id

2.8.3. 4) build_anti_testset(fill=None)，返回可以在test()方法中用作测试集的评分列表，参数决定填充未知评级的值，如果使用None则使用global_mean

2.8.3.5) knows_item(iid)，标志物品是否属于训练集

2.8.3. 6) knows_user(uid)，标志用户是否属于训练集

2.8.3. 7) to_inner_iid(riid)，将项目原始id转换为内部id

2.8.3.8) to_innser_uid(ruid)，将用户原始id转换为内部id

2.8.3. 9) to_raw_iid(iiid)，将项目的内部id转换为原始id

2.8.3.10) to_raw_uid(iuid)，将用户的内部id转换为原始id

2.9读取器类

2.9.1class surprise.reader.Reader(name=None, line_format=u’user item rating’, sep=None, rating_scale=(1, 5), skip_lines=0)

    Reader类用于解析包含评分的文件，要求这样的文件每行只指定一个评分，并且需要每行遵守这个接口：用户；项目；评分；[时间戳]，不要求顺序，但是需要指定

2.9.2参数分析：

2.9.2.1) name，如果指定，则返回一个内置的数据集Reader，并忽略其他参数，可接受的值是"ml-100k"，“m1l-1m”和“jester”。默认为None

2.9.2.2) line_format，string类型，字段名称，指定时需要用空格分割，默认是“user item rating”

2.9.2. 3) sep，char类型，指定字段之间的分隔符

2.9.2.4) rating_scale，元组类型，评分区间，默认为(1,5)

2.9.2.5) skip_lines，int类型，要在文件开头跳过的行数，默认为0

2.10 转储模块

2.10.1surprise.dump.dump(file_name, predictions=None, algo=None, verbose=0)

2.10.1.1一个pickle的基本包装器，用来序列化预测或者算法的列表

2.10.1.2参数分析：

            a) file_name，str，指定转储的位置
            b) predictions，Prediction列表，用来转储的预测
            c) algo，Algorithm，用来转储的算法
            d) verbose，详细程度，0或者1

2.10.2 surprise.dump.load(file_name)

2.10.2.1用于读取转储文件

2.10.2.2返回一个元组（predictions, algo），其中可能为None