dpkits — Package xử lý dữ liệu khảo sát

Phiên bản 2.0.0

Package Python chuyên dụng cho xử lý, biến đổi, phân tích và xuất bảng crosstab (có kiểm định sig) cho dữ liệu khảo sát từ nền tảng QMe.

Yêu cầu

• Python ≥ 3.12 (code dùng cú pháp f-string của Python 3.12)
• Các thư viện phụ thuộc (pandas, numpy, scipy, openpyxl, pyreadstat, scikit-learn, pingouin, xlwings, …) được cài tự động theo requirements.txt
• TableFormatter điều khiển Microsoft Excel qua xlwings → máy phải cài Excel (Windows / macOS)

Cài đặt

pip install --upgrade dpkits

Có gì mới trong 2.0.0

Thay đổi phá tương thích (cần sửa script cũ)

Thay đổi làm số liệu / ký hiệu sig khác bản 1.6.x

Chạy lại dự án cũ bằng 2.0.0 có thể cho kết quả khác ở các trường hợp sau — đây là các lỗi đã được sửa:

Tính năng mới

• is_sig_total (trong sig_test_info): chọn có sig cột Total hay không.
• Dòng Standard Error (sem): câu NUM có mặc định; câu SA khai báo mean ra 3 dòng Mean, Std, Standard Error.
• decimal: số chữ số thập phân của ô % (generator ghi, TableFormatter đọc và định dạng).
• is_validate_data=False: bỏ qua bước kiểm tra mã ngoài codelist & trùng giá trị MA.
• run_tables(lst_group_tables=...): tên khác của run_tables_by_js_files (giống API bản V2 cũ).
• tables_to_run: [] = chạy tất cả bảng; tên bảng (key) khác tbl_name không còn lỗi.
• Đang debug (PyCharm / VS Code) → bảng chạy trong tiến trình hiện tại, đặt breakpoint được.
• TableFormatter: định dạng dòng sem, xóa cột sig rỗng ở bảng có trọng số, mở file ở sheet Content, tùy chọn is_visible.
• Thông báo mã ngoài codelist hiện đúng ID gốc của respondent.

Hiệu năng

Đo trên một bộ dữ liệu thật (1.016 respondent × 3.155 biến, máy 12 core); thời gian thực tế phụ thuộc dữ liệu và máy:

Import

from dpkits import (
    APDataConverter,
    DataProcessing,
    DataTranspose,
    CodeframeReader,
    LSMCalculation,
    DataAnalysis,
    DataTableGenerator,
    TableFormatter,
)

Tổng quan luồng xử lý

Bước 1 — APDataConverter: Đọc và chuyển đổi dữ liệu

str_file_name     = 'APDataTest'
str_tbl_file_name = f'{str_file_name}_Topline.xlsx'

converter = APDataConverter(file_name='APDataTesting.xlsx')

# Chuyển sang dạng MC (thường dùng nhất)
df_data, df_info = converter.convert_df_mc()

# Chuyển sang dạng MD (binary columns cho câu MA)
df_data, df_info = converter.convert_df_md()

Câu MA ở dạng MC được đánh lại mã theo vị trí cột (cột thứ 4 → mã 4, kể cả khi mã gốc là 97). Recode lại nếu cần giữ mã gốc.

Cấu trúc df_info:

Bước 2 — DataProcessing: Xử lý và biến đổi dữ liệu

dp = DataProcessing(df_data=df_data, df_info=df_info)

Thêm câu hỏi — add_qres()

import numpy as np

# Cấu trúc: { 'TênBiến': ['Nhãn', 'LoạiBiến', {mã: nhãn}, giá_trị_mặc_định] }
# Câu MA: dùng 'TênBiến|N' với N = số cột
df_data, df_info = dp.add_qres({
    'AgeGroup':  ['Nhóm tuổi', 'SA', {1: '18-24', 2: '25-34', 3: '35-44', 4: '45+'}, np.nan],
    'Channel|4': ['Kênh mua hàng', 'MA', {1: 'Siêu thị', 2: 'Online', 3: 'Chợ', 4: 'Khác'}, np.nan],
    'Score':     ['Điểm đánh giá', 'NUM', {}, np.nan],
})

Không trộn giá trị mặc định chuỗi ('') với np.nan trong cùng một lần gọi: các cột mới sẽ thành kiểu chuỗi.

Xóa câu hỏi — remove_qres()

df_data, df_info = dp.remove_qres(lst_col=['Q_Old', 'Q_Temp'])

Cập nhật giá trị — update_qres_data()

df_data = dp.update_qres_data(query_fil='Age >= 18 and Age <= 24', qre_name='AgeGroup', lst_val_update=[1], method='o')

Các phương thức khác

# Đếm số lựa chọn câu MA (cột Q_Channel_1, Q_Channel_2, ...) → thêm cột Q_Channel_Count
df_data, df_info = dp.count_ma_choice(lst_ma_qre=['Q_Channel'])

# Dồn giá trị MA về trái, loại bỏ NaN giữa ('Tên|N' với N = số cột)
df_data = dp.align_ma_values_to_left(qre_name='Q_Channel|5')

# Gộp nhiều câu thành 1 câu MA
# lst_merge = cột OUTPUT (phải có sẵn trong df_info, tạo trước bằng add_qres); lst_to_merge = cột INPUT
# dk_code bị loại nếu respondent có chọn mã khác
df_data = dp.merge_qres(
    lst_merge=['Q_Combined_1', 'Q_Combined_2', 'Q_Combined_3', 'Q_Combined_4'],
    lst_to_merge=['Q1_1', 'Q1_2', 'Q2_1', 'Q2_2'],
    dk_code=99,
)

# Chuyển cột % dạng chuỗi sang số (Price_1_1, Price_1_2, Price_1_3)
df_data, df_info = dp.convert_percentage(lst_qres=['Price_1|3'], is_check_sum=True)

# Điểm xếp hạng: prefix của các cột Q_Rank_1, Q_Rank_2, ... → thêm Q_ScoreOfAtt_<mã>
# Chỉ truyền 1 câu mỗi lần gọi (xem Hạn chế đã biết)
df_data, df_info = dp.calculate_ranking_score(lst_ranking_qre=['Q'])

# One-hot encoding: {prefix cột mới: regex các cột nguồn} → thêm Q_Usage_BIN_<mã>
df_data, df_info = dp.one_hot_encoding(dict_one_hot_regex={'Q_Usage_BIN': '^Q_Usage_[0-9]{1,2}$'})

Bước 3 — DataTranspose: Stack / Unstack dữ liệu

Dùng cho nghiên cứu nhiều sản phẩm (Product Testing, Brand Tracking...).

Wide → Long (to_stack)

dict_stack_structure = {
    'id_col':  'ResID',
    'sp_col':  'Ma_SP',
    'lst_scr': ['Gender', 'Age', 'City', 'HHI'],   # Cột screener (copy sang tất cả hàng)
    'dict_sp': {
        1: {'Ma_SP1': 'Ma_SP', 'Q1_SP1': 'Q1', 'Q2_SP1': 'Q2', 'Q3_SP1': 'Q3'},
        2: {'Ma_SP2': 'Ma_SP', 'Q1_SP2': 'Q1', 'Q2_SP2': 'Q2', 'Q3_SP2': 'Q3'},
    },
    'lst_fc': ['Awareness1', 'Frequency', 'Awareness2', 'Perception']  # Cột chung
}

df_data_stack, df_info_stack = DataTranspose.to_stack(df_data, df_info, dict_stack_structure)

Long → Wide (to_unstack)

dict_unstack_structure = {
    'id_col':            'ResID',
    'sp_col':            'Ma_SP',
    'lst_col_part_head': ['Gender', 'Age', 'City', 'HHI'],
    'lst_col_part_body': ['Q1', 'Q2', 'Q3'],
    'lst_col_part_tail': ['Awareness1', 'Frequency', 'Awareness2', 'Perception']
}

df_data_unstack, df_info_unstack = DataTranspose.to_unstack(df_data_stack, df_info_stack, dict_unstack_structure)

Bước 4 — CodeframeReader: Đọc bảng codeframe câu hỏi mở

cf = CodeframeReader(cf_file_name='codeframe_Q15.xlsx')
cf.to_dataframe_file()
cf.read_dataframe_output_file()

# Tích hợp kết quả vào DataProcessing
df_data, df_info = dp.add_qres(cf.dict_add_new_qres_oe)

Yêu cầu file input: Sheet có hậu tố -CODE chứa cột RESPONDENTID, COLUMN_NAME, VERBATIM, CODING.

Bước 5 — LSMCalculation: Tính điểm LSM

df_data, df_info = LSMCalculation.cal_lsm_6(df_data, df_info)
# Thêm vào df_data: CC1_Score → CC6_Score, LSM_Score, LSM (0–19)

Yêu cầu: df_data phải có sẵn các cột CC1, CC2_1...CC2_10, CC3_1...CC3_7, v.v. theo cấu trúc bảng hỏi LSM chuẩn.

Bước 6 — DataAnalysis: Phân tích thống kê nâng cao

da = DataAnalysis(df_data=df_data, df_info=df_info)

Penalty Analysis (JAR)

dict_pen = {
    'HCM': {
        'query':    'City == 1',
        'prod_pre': 'Brand',
        'ol_qre':   'Q_OverallLiking',
        'jar_qres': {
            'Sweetness': {
                'label': 'Độ ngọt',
                'jar':   {'code': [3]},
                'b2b':   {'code': [1, 2], 'label': 'Quá nhạt'},
                't2b':   {'code': [4, 5], 'label': 'Quá ngọt'},
            }
        }
    }
}

da.penalty_analysis(dict_define_pen=dict_pen, output_name='penalty')  # tự thêm đuôi .xlsx

Hồi quy tuyến tính

result = da.linear_regression(
    dict_define_linear={
        'All': {
            'str_query':        'City > 0',               # '' = không lọc
            'dependent_vars':   ['Q_Purchase'],           # nhiều biến → lấy trung bình
            'explanatory_vars': ['Q1', 'Q2', 'Q3', 'Q4'],
        }
    },
    output_name='regression'  # tự thêm đuôi .xlsx; None = không xuất file
)
# result['All']['df_linear'] — DataFrame hệ số hồi quy (đã chuẩn hóa)

Tương quan

da.correlation(
    dict_define_corr={
        'All': {
            'str_query':        'City > 0',
            'dependent_vars':   ['Q_Overall'],
            'explanatory_vars': ['Q1', 'Q2', 'Q3', 'Q4', 'Q5'],
        }
    },
    output_name='corr.xlsx'  # hàm này KHÔNG tự thêm đuôi, phải ghi .xlsx
)

Key Driver Analysis

da.key_driver_analysis(
    dict_kda={
        'All': {
            'str_query':               'City > 0',
            'axis_y_dependent_vars':   ['Q_Overall'],
            'axis_x_dependent_vars':   None,   # hoặc list biến cho trục x
            'axis_x_explanatory_vars': None,   # None = trục x là mean của explanatory_vars
            'explanatory_vars':        ['Q_Att1', 'Q_Att2', 'Q_Att3'],
        }
    },
    output_name='kda'  # tự thêm đuôi .xlsx
)

Ngoài ra: correspondence_analysis (cần thư viện prince), price_sensitive_metric (Van Westendorp), k_mean_segmentation.

Bước 7 — Export dữ liệu (.sav / .xlsx)

dict_dfs = {
    1: {'data': df_data,       'info': df_info,       'tail_name': 'ByCode',  'sheet_name': 'ByCode',  'is_recode_to_lbl': False},
    2: {'data': df_data,       'info': df_info,       'tail_name': 'ByLabel', 'sheet_name': 'ByLabel', 'is_recode_to_lbl': True},
    3: {'data': df_data_stack, 'info': df_info_stack, 'tail_name': 'Stack',   'sheet_name': 'Stack',   'is_recode_to_lbl': False},
}

converter.generate_multiple_data_files(
    dict_dfs=dict_dfs,
    is_export_sav=True,
    is_export_xlsx=True,
    is_zip=True   # Lưu ý: sau khi nén, các file .sav/.xlsx gốc bị xóa, chỉ còn file .zip
)

Bước 8 — DataTableGenerator + TableFormatter: Tạo và format bảng

Cấu hình lst_side_qres (câu hỏi hàng / stub)

lst_side_qres = [
    # Câu SA
    {"qre_name": "Gender"},
    {"qre_name": "Age", "qre_lbl": "{lbl} (Nam)", "qre_filter": "Gender == 1"},   # đổi nhãn + lọc riêng câu này

    # Câu MA: thêm $ trước tên biến
    {"qre_name": "$CC3"},

    # Câu MA với net / combine
    {"qre_name": "$Q15", "cats": {
        'net_code': {
            '900001|combine|Group 1 + 2': {'1': 'Yellow/dull teeth', '3': 'Dental plaque', '2': 'Sensitive teeth', '4': 'Caries'},
            '900002|net|Group 1':         {'1': 'Yellow/dull teeth', '3': 'Dental plaque'},
            '900003|net|Group 2':         {'2': 'Sensitive teeth', '4': 'Caries'},
        },
        '8': 'Other (specify)',
        '9': 'No problem',
    }},

    # Câu scale: net + mean + dòng tính toán
    {
        "qre_name": "Perception",
        "cats": {
            '1': 'Totally disagree', '2': 'Disagree', '3': 'Neutral', '4': 'Agree', '5': 'Totally agree',
            'net_code': {
                '900001|combine|B2B': {'1': 'Totally disagree', '2': 'Disagree'},
                '900003|combine|T2B': {'4': 'Agree', '5': 'Totally agree'},
            }
        },
        "mean": {1: 1, 2: 2, 3: 3, 4: 4, 5: 5},          # thêm 3 dòng: Mean, Std, Standard Error
        "calculate": {"T2B - B2B": "[T2B] - [B2B]"},      # {nhãn dòng mới: công thức}, [..] = cat_lbl của dòng
    },

    # Câu NUM: mặc định Mean, Std, Min, Max, Quantile 25/50/75%, Standard Error
    {"qre_name": "Income"},
]

Tùy chọn của mỗi câu trong stub:

Ký hiệu net_code:

Cấu hình dict_header_qres (câu hỏi cột / banner)

dict_header_qres là dict các nhóm header: mỗi key là một nhóm, value là list các cấp (tối đa 5 cấp), mỗi cấp là list câu hỏi. Các nhóm phải có cùng số cấp. Trong mỗi nhóm, các cột được đánh ký tự A, B, C… để đọc kết quả sig.

dict_header_qres = {
    # Nhóm header 1: 1 cấp
    'hd_1': [
        [
            {
                "qre_name": "Age",
                "qre_lbl":  "Age",
                "cats": {
                    'TOTAL': 'Total',   # cột Total (xem is_sig_total)
                    '2': '18 - 24',
                    '3': '25 - 30',
                    '4': '31 - 39',
                },
            },
            # Custom query dùng ký hiệu @
            {
                "qre_name": "@City2",
                "qre_lbl":  "Location",
                "cats": {
                    'City.isin([1, 5, 10, 11, 12])': 'All South',
                    'City.isin([2, 4, 16, 17, 18])': 'All North',
                },
            },
        ],
    ],

    # Nhóm header 2: câu MA dùng $, cats rỗng = lấy codelist trong df_info
    'hd_2': [
        [
            {"qre_name": "$Q_Channel", "qre_lbl": "Channel", "cats": {}},
        ],
    ],
}

Chạy bảng

lst_func_to_run = [
    {
        'tables_to_run': ['Tbl_1_Pct', 'Tbl_1_Count'],   # [] = chạy tất cả bảng
        'tables_format': {

            "Tbl_1_Pct": {
                "tbl_name":             "Table 1 - Pct",   # tên sheet
                "tbl_filter":           "City > 0",
                "is_count":             0,       # 0 = %, 1 = count
                "is_pct_sign":          1,       # Hiển thị dấu %
                "decimal":              0,       # Số chữ số thập phân của ô % (mặc định 0)
                "is_hide_oe_zero_cats": 1,
                "is_hide_zero_cols":    0,       # Giữ 0 (xem Hạn chế đã biết)
                "weight_var":           '',      # Biến trọng số (để trống nếu không dùng; không dùng cùng sig)
                "sig_test_info": {
                    "sig_type":     "ind",       # 'ind' = độc lập, 'rel' = phụ thuộc, '' = không sig
                    "sig_cols":     [],          # [] = tất cả cặp cột; hoặc [["A", "B"], ["B", "C"]] (xem Lưu ý)
                    "lst_sig_lvl":  [90, 95],    # Mức tin cậy, bắt buộc tăng dần (tối đa 2 mức)
                    "is_sig_total": True,        # True (mặc định): Total = A, có sig; False: Total không sig, cột đầu tiên còn lại = A
                },
                "lst_side_qres":    lst_side_qres,
                "dict_header_qres": dict_header_qres,
            },

            "Tbl_1_Count": {
                "tbl_name":             "Table 1 - Count",
                "tbl_filter":           "City > 0",
                "is_count":             1,
                "is_pct_sign":          0,
                "is_hide_oe_zero_cats": 1,
                "is_hide_zero_cols":    0,
                "weight_var":           '',
                "sig_test_info": {"sig_type": "", "sig_cols": [], "lst_sig_lvl": []},
                "lst_side_qres":    lst_side_qres,
                "dict_header_qres": dict_header_qres,
            },
        },
    },
]

# Toàn bộ script phải nằm trong `if __name__ == '__main__':` (có thể chạy nhiều tiến trình)
if __name__ == '__main__':

    dtg = DataTableGenerator(
        df_data=df_data,
        df_info=df_info,
        xlsx_name=str_tbl_file_name,
        is_validate_data=True,   # False = bỏ qua kiểm tra mã ngoài codelist & trùng giá trị MA
    )
    dtg.run_tables_by_js_files(lst_func_to_run)   # hoặc dtg.run_tables(lst_group_tables=lst_func_to_run)

    # Gộp bảng từ data khác (ví dụ data stack) vào CÙNG file: generator mới, cùng xlsx_name, is_append=True
    # dtg_stack = DataTableGenerator(df_data=df_data_stack, df_info=df_info_stack, xlsx_name=str_tbl_file_name)
    # dtg_stack.run_tables_by_js_files(lst_func_to_run_stack, is_append=True)

    # Format bảng (cần Excel) → lưu thành '<tên file> - <Mon dd>.xlsx'
    dtf = TableFormatter(xlsx_name=str_tbl_file_name)
    dtf.format_workbook()   # is_visible=True để xem Excel khi đang format

Lưu ý quan trọng

Hạn chế đã biết (2.0.0)