Muốn người khác chạy lại được, phần phương pháp cần ghi: tên phần mềm, số phiên bản đầy đủ, các gói hay mô-đun kèm phiên bản, mọi tuỳ chọn đã đổi khỏi mặc định, cách trích dẫn đúng của phần mềm, và nộp kèm tệp cú pháp hoặc mã đã chạy ra từng bảng.
Câu “số liệu được xử lý bằng phần mềm SPSS” xuất hiện trong rất nhiều bản thảo, và gần như không giúp được ai. Hai phiên bản của cùng một phần mềm có thể cho kết quả khác nhau vì thuật toán mặc định thay đổi; hai gói R cùng làm hồi quy hỗn hợp có thể dùng hai cách tính bậc tự do. Phản biện kỹ tính và hội đồng thẩm định ngày càng hỏi đúng chỗ này. Phần dưới đây đi từ việc lấy thông tin phiên bản tới cách viết câu trong bài và gói hồ sơ nộp kèm.
Ghi những gì để người khác chạy lại được?
Mỗi thông tin dưới đây trả lời một câu hỏi mà người chạy lại sẽ gặp. Thiếu dòng nào, họ phải đoán, và đoán sai là ra số khác.
| Thông tin | Vì sao cần | Ví dụ cách ghi |
|---|---|---|
| Tên phần mềm và nhà phát triển | Phân biệt các phần mềm trùng tên hoặc nhiều bản phân phối | IBM SPSS Statistics; R (R Core Team); Stata (StataCorp) |
| Phiên bản đầy đủ | Thuật toán và mặc định thay đổi giữa các bản | Ghi đủ ba số nếu phần mềm đánh ba số, không viết “bản mới nhất” |
| Gói hay mô-đun và phiên bản | Phân tích thật sự nằm trong gói, không phải trong R hay Python lõi | gói lavaan, gói lme4, mô-đun SEM của jamovi |
| Tuỳ chọn đã đổi khỏi mặc định | Người chạy lại sẽ để mặc định nếu bạn không nói | phương pháp ước lượng, cách xử lý dữ liệu thiếu, số mẫu bootstrap |
| Hạt giống ngẫu nhiên | Bootstrap, mô phỏng, chia mẫu cho ra số khác mỗi lần chạy | set.seed() trong R, set seed trong Stata |
| Hệ điều hành, khi liên quan | Một số phép tính số học và mã hoá ký tự khác giữa hệ điều hành | chỉ cần ghi trong tệp đi kèm, không cần đưa vào thân bài |
Lấy số phiên bản ở đâu trong từng phần mềm?
R và gói R
Lệnh sessionInfo() in ra phiên bản R, hệ điều hành và phiên bản mọi gói đang nạp. Muốn một gói cụ thể thì dùng packageVersion('lme4'). Chạy lệnh này ở cuối tệp mã, sau khi đã nạp đủ gói, rồi lưu kết quả vào một tệp văn bản đặt cạnh mã. Nếu dự án dùng renv, tệp renv.lock đã ghi sẵn phiên bản từng gói và là thứ tốt nhất để nộp kèm.
Python
Mỗi thư viện có thuộc tính __version__, ví dụ pandas.__version__. Cách gọn hơn là xuất danh sách môi trường bằng pip freeze hoặc tệp môi trường của conda, rồi nộp kèm tệp đó.
SPSS, Stata, jamovi, JASP
SPSS ghi số phiên bản trong mục Help > About. Stata có lệnh about; lệnh which kèm tên lệnh cho biết tệp ado đang dùng và ngày của nó, hữu ích với lệnh do người dùng viết tải từ SSC. jamovi và JASP hiện số phiên bản trong mục giới thiệu ở menu chính; mô-đun cài thêm có phiên bản riêng trong trình quản lý mô-đun.
Viết câu trong mục phương pháp thế nào cho đủ mà không dài?
Một câu tốt gom tên, phiên bản, gói và tuỳ chọn chính vào một chỗ, rồi đặt trích dẫn ngay sau. Khung câu có thể là: “Mô hình phương trình cấu trúc được ước lượng trong R phiên bản [số] với gói lavaan phiên bản [số], dùng ước lượng hợp lý cực đại có sai số chuẩn vững (MLR) và xử lý dữ liệu thiếu bằng FIML.” Người đọc biết ngay phải cài gì và chọn gì.
Với phần mềm bấm chuột, hãy ghi đường dẫn tới thủ tục khi tên thủ tục dễ nhầm, và ghi rõ lựa chọn khác mặc định: kiểu xoay nhân tố, cách tính tổng bình phương, phương pháp hiệu chỉnh so sánh bội. Lựa chọn nào giữ nguyên mặc định thì không cần kể từng cái, chỉ cần một câu “các tuỳ chọn khác để mặc định của phiên bản trên”.
Nếu tạp chí giới hạn số chữ, đưa phần chi tiết vào tài liệu bổ sung và để trong thân bài một câu trỏ tới đó. Điều quan trọng là thông tin tồn tại ở đâu đó trong hồ sơ công bố.
Trích dẫn phần mềm và gói R như một tài liệu tham khảo
Dùng đúng câu trích dẫn tác giả đề nghị
Lệnh citation() trong R in ra cách trích dẫn chính R; citation('lavaan') in ra cách trích dẫn gói, thường là bài báo gốc mô tả gói. Nhiều kho mã trên GitHub có tệp CITATION.cff nêu cách trích dẫn. Phần mềm thương mại thường có câu trích dẫn đề nghị trong tài liệu của nhà sản xuất.
Nguyên tắc chung
Bộ nguyên tắc trích dẫn phần mềm của FORCE11 (Software Citation Principles) coi phần mềm là sản phẩm nghiên cứu cần được ghi công như bài báo. Khi một phiên bản phần mềm có DOI riêng (nhiều gói lưu bản phát hành trên Zenodo), hãy trích DOI của đúng phiên bản đã dùng. Cách này giúp người viết gói được ghi nhận và giúp người đọc lấy đúng bản.
Gói hồ sơ nộp kèm: cú pháp, dữ liệu, hướng dẫn chạy
Bộ hồ sơ để chạy lại không cần cầu kỳ, nhưng phải chạy được từ đầu đến cuối trên máy người khác. Thứ tự chuẩn bị:
- Gom toàn bộ mã hoặc cú pháp vào một thư mục, đặt tên tệp theo thứ tự chạy:
01_lam_sach,02_phan_tich,03_bang_hinh. - Bỏ mọi đường dẫn tuyệt đối kiểu ổ đĩa riêng của bạn; dùng đường dẫn tương đối tính từ thư mục dự án.
- Kèm dữ liệu nếu được phép chia sẻ; nếu không, kèm mô tả biến và cách xin dữ liệu, hoặc bộ dữ liệu giả có cùng cấu trúc.
- Viết tệp README ngắn: phần mềm và phiên bản, thứ tự chạy, tệp nào sinh ra bảng nào trong bài.
- Xuất danh sách phiên bản (
sessionInfo(),renv.lock,pip freeze) và đặt vào thư mục. - Nhờ một đồng nghiệp chạy lại trên máy của họ trước khi nộp; lỗi đường dẫn gần như luôn lộ ra ở bước này.
Kho lưu trữ như OSF hoặc Zenodo cho phép gửi cả thư mục và nhận DOI, nên bạn có thể dẫn DOI đó trong mục tuyên bố dữ liệu của bài.
Lỗi hay gặp khi ghi phần mềm và cách sửa
Các lỗi dưới đây gặp thường xuyên trong bản thảo gửi tạp chí trong nước lẫn quốc tế.
| Lỗi | Hậu quả | Cách sửa |
|---|---|---|
| Chỉ ghi tên, không ghi phiên bản | Không biết thuật toán mặc định nào đã chạy | Thêm số phiên bản lấy từ mục About hoặc sessionInfo() |
| Ghi R nhưng không ghi gói | Người đọc không biết phân tích thật nằm ở đâu | Liệt kê gói thực hiện phép tính chính kèm phiên bản |
| Không ghi hạt giống ngẫu nhiên | Khoảng tin cậy bootstrap lệch nhẹ mỗi lần chạy | Đặt hạt giống ở đầu mã và ghi số đó trong tệp đi kèm |
| Ghi phiên bản trên máy hiện tại, không phải bản đã chạy | Số trong bài không khớp khi chạy lại | Lưu thông tin phiên bản ngay lúc chạy phân tích cuối cùng |
| Trích dẫn trang chủ thay vì tài liệu tác giả đề nghị | Người viết gói không được ghi công | Dùng citation() hoặc tệp CITATION.cff |
Việc làm ngay với bản thảo đang viết
Mở lại mục phương pháp, gạch chân mọi chỗ nhắc tới phần mềm và tự hỏi: người khác đọc câu này có cài đúng bản và chọn đúng tuỳ chọn được không. Chạy lệnh lấy phiên bản trên máy đã chạy phân tích cuối, lưu thành tệp. Thêm các trích dẫn phần mềm vào danh mục tài liệu tham khảo. Cuối cùng gom cú pháp thành một thư mục chạy được và nhờ người khác thử.
Không cần ghi phiên bản trình duyệt, bộ gõ hay phần mềm soạn thảo văn bản; những thứ đó không ảnh hưởng tới con số. Cũng không cần chép toàn bộ đầu ra của sessionInfo() vào thân bài, để nó trong tệp đi kèm là đủ.
Câu hỏi thường gặp
Có bắt buộc trích dẫn R trong danh mục tài liệu tham khảo không?
Nhiều tạp chí yêu cầu, và R Core Team đề nghị trích dẫn khi dùng R cho phân tích công bố. Lệnh citation() in sẵn câu trích dẫn đúng, chỉ cần chép theo định dạng của tạp chí.
Dùng SPSS bản có bản quyền của trường thì ghi thế nào?
Ghi tên đầy đủ IBM SPSS Statistics kèm số phiên bản lấy ở mục About. Việc bản quyền thuộc trường không cần nêu trong bài, trừ khi tạp chí hỏi riêng.
Gói R cập nhật sau khi nộp bài thì có sao không?
Không sao nếu bạn đã ghi phiên bản đã dùng. Người chạy lại có thể cài đúng bản cũ từ kho lưu trữ CRAN hoặc khôi phục môi trường bằng tệp renv.lock.
Có cần nộp cú pháp khi tạp chí không yêu cầu không?
Không bắt buộc, nhưng nộp kèm giúp phản biện kiểm tra nhanh và giảm vòng hỏi lại. Nếu chưa muốn công khai, có thể gửi riêng cho biên tập viên dưới dạng tài liệu bổ sung.
Ghi phiên bản cho công cụ trực tuyến không có số phiên bản thì sao?
Ghi tên công cụ, đơn vị phát triển, ngày truy cập và các thiết lập đã chọn. Nếu công cụ có tài liệu mô tả thuật toán, trích dẫn tài liệu đó.
