실증 연구 데이터 파이프라인

"여러 잡다한 자료"를 "검증 가능한 샘플 흐름 + 추적 가능한 코딩/필드 데이터 + 재현 가능한 모델 + 제출 가능한 차트 및 원고"로 변환합니다. 본 스킬은 학문, 언어 또는 파일 형식에 제한되지 않습니다. 법률 판결문은 단지 "텍스트 코딩"의 한 예시일 뿐이며, 설문지, 인터뷰, 뉴스, 정책 문서, 실험 기록, 공개 데이터, 웹 페이지 및 데이터베이스 내보내기에도 동일하게 적용됩니다.

이 저장소/패키지 내의 예시 숫자, 파일 이름, 경로 및 변수 값은 모두 가상의 자리 표시자이며, 실제 자료, 코딩 데이터, SPSS 데이터 또는 논문 원고를 포함하지 않습니다.

사용 시기

사용자가 PDF, Word, Excel, CSV, 텍스트, 웹 페이지, 인터뷰 기록, 이미지 또는 스캔 파일이 혼합된 폴더를 제공하고, 정리, 코딩, 통계, 차트 작성 또는 논문 작성을 요청하는 경우.
기존 CSV/SPSS 데이터가 있고, 이를 정제, 병합, 새 자료 추가, 샘플 기준 수정 또는 모델 재실행해야 하는 경우.
설문지, 인터뷰, 실험, 관찰, 공개 데이터 등에 대해 기술 통계, 그룹 간 비교, 회귀 분석, 이질성, 강건성 또는 예측 평가가 필요한 경우.
실증 부분을 Word/PDF로 만들어야 하며, 차트, 표 및 본문의 숫자가 일치해야 하는 경우.
사용자가 "비슷한 자료를 다시 처리해야 한다"고 말하며, 동일한 워크플로를 재사용하려는 경우.

자료 유형 및 처리 경계

자료	기본 처리	설명
PDF	텍스트 레이어, 페이지 수, 문자 수, 이미지 수, 암호화 상태	스캔 파일은 먼저 OCR; 이미지 전용 PDF는 `image_only`로 표시
DOCX / ODT / PPTX	문단, 표, 슬라이드 텍스트	`.doc`/`.ppt` 구형식은 먼저 변환
XLSX / XLSM	워크시트, 셀 텍스트; 읽기 전용으로 열기	`.xls`는 먼저 변환; `openpyxl` 설치 권장
CSV / TSV / JSON / JSONL	필드, 행 수, 인코딩, 결측; 테이블 데이터 품질 감사	코딩 워크시트는 테이블을 건너뛰고 `auto_stats`로 바로 진행
TXT / MD / HTML / XML / YAML / RTF	텍스트 추출; HTML 태그 제거	웹 페이지 본문 사용 가능, 스크립트/스타일은 제거됨
이미지 (PNG/JPG/TIFF 등)	파일 목록; 크기/페이지 수	먼저 OCR, 그 다음 코딩; 본 스킬은 OCR을 자체적으로 포함하지 않음
오디오/비디오	파일 목록	먼저 전사/프레임 추출, 그 다음 코딩; 본 스킬은 ASR을 자체적으로 포함하지 않음
압축 파일	파일 목록	먼저 압축 해제; 감사는 `unsupported`로 표시
알 수 없음/전용 형식	파일 목록	먼저 위 형식으로 변환 또는 내보내기

"모든 자료"가 "모든 바이너리를 직접 구문 분석할 수 있음"을 의미하지는 않습니다. 본 스킬은 먼저 모든 파일을 감사 및 샘플 대조에 포함시킵니다. 직접 읽을 수 없는 형식은 명확하게 표시되고 변환 경로가 제공되며, 조용히 누락되지 않습니다.

여섯 가지 엄격한 규칙

감사 먼저, 코딩/모델링은 그 다음. 파일 수, 읽을 수 있는 텍스트 수, 중복 수, 필드 결측 및 제외 이유를 파악하기 전에 통계를 시작하지 마십시오.
내용 기반 중복 제거, 파일 이름 기반 아님. 동일한 이름에 다른 내용, 동일한 내용에 다른 이름은 매우 일반적입니다. 최소 MD5를 사용하고, 제목/키 필드/본문 샘플링을 통해 재확인하십시오.
한 행 = 하나의 분석 단위. 문서, 응답자, 사건, 기관, 지역-연도 또는 설문지 응답은 프로젝트 시작 시 고정되어야 합니다. 여러 단위가 혼합된 경우 제한 사항에 설명하십시오.
각 코딩/추출 값에는 증거가 있어야 함. 원문에 기록되지 않은 경우 NA/미기재로 기록하고, 기본값 0으로 기록하지 마십시오. 부정 표현, 타인 제안, 인용은 최종 사실로 간주될 수 없습니다.
설명 샘플 N ≠ 모델 샘플 N. 각 모델은 별도로 N과 필터 조건을 보고합니다. 본문, 표, 그림, 초록은 동일한 기준을 사용해야 합니다.
연관 ≠ 인과. "연관/대응/더 가능성이 높음"으로 작성하고, "초래함/효과적으로 만듦/입증함"으로 작성하지 마십시오.

워크플로 개요

0 범위 및 질문 → 1 자료/데이터 감사 → 2 코딩 또는 추출 프로토콜 → 3 데이터셋
                                      ↓
                         7 최종 검사 ← 6 원고 조립 ← 5 출판급 차트 ← 4 통계 분석

각 단계에는 "게이트"가 있습니다. 게이트를 통과하지 않으면 다음 단계로 넘어가지 않습니다.

단계 0: 범위 및 질문

먼저 scope.md 페이지를 작성합니다. 최소한 다음을 포함해야 합니다.

연구 질문, 이론적 메커니즘, 예상 기여.
자료 유형 및 출처: 데이터베이스, 검색식/샘플링 프레임, 시간 범위, 언어, 지역.
분석 단위: 하나의 문서/한 명의 응답자/하나의 사건/하나의 기관/하나의 설문지.
포함/제외 기준: 시간, 유형, 언어, 단어 수, 중복, 읽을 수 없음, 키 필드 결측.
예상 변수 목록 및 역할: 종속 변수, 핵심 독립 변수, 메커니즘/조절 변수, 통제 변수.
데이터 형태: 텍스트, 표, 혼합; 수동 코딩, 설문지 척도, 실험 그룹 또는 2차 데이터가 필요한지 여부.

게이트: "원시 자료 → 읽을 수 있는 자료 → 범위 내 샘플 → 분석 샘플"의 각 단계에서 얼마나 많은 자료가 손실되고 그 이유가 무엇인지 한 문장으로 설명할 수 있어야 합니다.

단계 1: 자료 및 데이터 감사 (먼저 실행해야 함)

1A 파일 수준 감사

scripts/audit_corpus.py 실행:

python scripts/audit_corpus.py --root "자료 디렉터리" --out-dir "output/audit" --min-chars 100

기본적으로 지원되는 모든 유형을 스캔하며, --ext를 하나씩 지정할 필요가 없습니다. --list-ext를 사용하여 전체 목록을 볼 수 있습니다. 다음을 출력합니다.

파일	용도
`corpus_audit.csv`	각 파일의 확장자, 유형, 바이트 수, 페이지 수/표 수, 문자 수, 이미지 수, MD5, 상태, 오류
`corpus_summary.json`	기계 판독 가능한 요약
`corpus_duplicates.csv`	중복 그룹, 보관/제거 제안
`corpus_report.md`	프로젝트 로그에 직접 붙여넣을 수 있는 중국어 보고서

상태 머신 (각 파일은 한 범주에 속해야 함):

상태	의미	분석에 포함되는가
`valid`	열 수 있고, 충분한 텍스트/데이터 있음	예
`metadata`	`._*`, `.DS_Store` 등 시스템 파일	아니요
`hidden`	숨김 파일/숨김 디렉터리	아니요 (사용자 확인 제외)
`unsupported`	알 수 없는 형식, 압축 파일, 구형 Office, 파서 부족	아니요 (먼저 변환/압축 해제)
`quarantined`	`_duplicates` 등 건너뛰기 디렉터리에 있음	아니요 (격리된 복사본)
`zero_byte`	0 바이트	아니요
`corrupt`	열 수 없음, 파일 손상	아니요
`encrypted`	암호/권한 제한 있음	아니요 (해독 가능한 경우 제외)
`textless`	페이지/셀은 있지만 텍스트 부족	아니요 (빈 파일인지 또는 재내보내기가 필요한지 확인)
`image_only`	이미지/스캔 파일, 텍스트 레이어 없음	OCR 후 사용 가능
`media`	오디오/비디오	먼저 전사/프레임 추출

중복은 별도의 status가 아닙니다. 내용이 동일한 파일은 여전히 valid이며, dup_group/dup_role을 사용하여 keeper/duplicate를 표시합니다. 보고서의 unique_valid_files는 이미 복사본을 제외했습니다.

다음을 항목별로 처리해야 합니다.

._*, .DS_Store: macOS 메타데이터, 연구 자료 아님. "비자료 파일"로 계산하며 샘플에 포함하지 마십시오. 읽을 수 있는 ._*는 error 열에 표시되며 수동 확인이 필요합니다.
숨김 파일/디렉터리는 hidden으로 기록합니다. 확장자가 지원 목록에 없으면 unsupported로 기록합니다. _duplicates 등 건너뛰기 디렉터리는 quarantined로 기록합니다. 세 가지 모두 샘플에 포함되지 않지만 총계와 보고서에 나타나야 합니다.
0 바이트, 열 수 없음, 암호화됨, 텍스트 부족: 각각 zero_byte/corrupt/encrypted/textless로 기록합니다. 이미지 전용 PDF는 image_only로 기록합니다.
최상위/연도 분포는 고유 샘플(valid이고 복사본이 아닌)에 대해서만 통계를 냅니다. 메타데이터, 손상된 파일 또는 중복 복사본을 샘플 구조에 포함하지 마십시오.
중복 복사본: MD5별로 그룹화합니다. "식별자/연도 포함, 경로가 더 짧고, 텍스트가 완전한" 파일을 보관하고 나머지는 _duplicates/로 이동합니다. 직접 삭제하지 마십시오.
파일 이름 잘림, 후행 점, 매우 긴 경로: Windows에서 일반적입니다. Python으로 읽고 보고서에 기록합니다. 탐색기로 수동으로 세지 마십시오.
이름은 같지만 내용이 다른 파일, 본문은 동일하지만 메타데이터/내보내기 설정이 다른 파일(MD5 다름): 제목/키 필드/본문 샘플링을 통해 수동으로 재확인해야 합니다. MD5만으로 자동 중복 제거해서는 안 됩니다.

그런 다음 scripts/dedupe_corpus.py를 실행하여 중복 제거 계획을 생성합니다.

python scripts/dedupe_corpus.py --audit "output/audit/corpus_audit.csv" --root "자료 디렉터리" --out-dir "output/audit" --apply

게이트: sample_flow.md가 다음을 대조할 수 있어야 합니다.

원시 파일 수 (.DS_Store/확장자 없는 파일 포함)
- 메타데이터/숨김 파일
- 지원되지 않음/변환 필요 (unsupported)
- _duplicates 등 격리 디렉터리 (quarantined)
- 0 바이트/손상/암호화/텍스트 부족
= 읽을 수 있는 자료 수
- 범위 외 (시간/유형/언어)
= 유효 자료 수
- 중복 복사본
= 고유 샘플 수 (unique_valid_files 기준)
- 키 변수 결측/코딩 불가
= 분석 샘플 수

각 모델에는 별도의 N이 있어야 합니다. 하나의 N으로 모든 것을 대체하지 마십시오.

1B 테이블 데이터 품질 감사

자료 자체가 CSV/Excel/SPSS 데이터인 경우, 코딩/모델링 전에 먼저 필드 수준 검사를 수행합니다.

행 수, 열 수, 각 열의 유형 (숫자/범주/텍스트/날짜), 결측률, 고유 값 수.
기본 키/ID의 고유성; 중복 행; 동일 단위의 여러 레코드.
범주형 변수 값의 철자 불일치 ("예/아니오/1/0/TRUE" 혼용); 날짜 범위.
연속 변수 범위, 이상치, P99 절단, 로그 변환 필요 여부.
설문지 척도 역문항, 다중 선택 분할, 단위 일관성.
인코딩 (UTF-8-SIG/GB18030), 소수점 구분 기호, SPSS 변수명 적법성.

csv_to_spss_syntax.py는 불법/중복 변수명을 정리하고 .sps를 생성합니다. auto_stats.py는 기술 통계, 그룹 간 검정 및 상관 관계를 제공하여 데이터 문제를 발견하는 데 도움을 주지만 공식 모델을 대체하지는 않습니다.

게이트: 각 열의 출처, 유형, 결측 처리, 이상치 처리 및 최종적으로 어떤 모델에 들어가는지 설명할 수 있어야 합니다.

단계 2: 코딩/추출 프로토콜

2.1 텍스트 코딩

먼저 assets/codebook-template.md의 인스턴스를 작성합니다. 각 변수에는 정의, 값, 판단 규칙, 증거 위치, 긍정 예, 부정 예, 결측 규칙이 있어야 합니다.
scripts/make_coding_sheet.py를 사용하여 전체 텍스트와 후보 증거 문장을 추출하고 코딩 워크시트를 생성합니다. 증거 조각만 제공하며 최종 판단을 대신하지 않습니다.
- 기본 --profile generic: 인터뷰, 뉴스, 정책, 보고서, 웹 페이지, 회의록 등 모든 텍스트 자료에 적용됩니다.
- --profile legal: 법원, 사건 번호, 지역, 사건 유형 후보를 추가로 추출합니다. 중국 판결문을 처리할 때만 사용합니다.
- CSV/TSV/JSON/XLSX 등 테이블은 건너뛰고 통계 프로세스를 진행하라는 메시지를 표시합니다. 이미지/오디오/비디오는 먼저 OCR/전사를 요청하는 메시지를 표시합니다.
수동/LLM 코딩 시 각 레코드는 최소한 *_ev 증거 문장을 저장해야 합니다. 증거 문장이 없는 코딩은 미완료로 간주됩니다.
자료의 10%–15%를 이중 코딩/이중 라운드로 추출하고 일치율 또는 Cohen's κ를 보고합니다. 불일치는 먼저 판결한 다음 codebook을 수정합니다.
Codebook이 동결된 후에 전체 코딩을 수행합니다. 이후 변경 사항은 버전과 영향 범위를 기록해야 합니다.

2.2 설문지/척도/구조화된 추출

먼저 항목 수준 변수 사전을 만듭니다: 항목 번호, 질문 내용, 값, 역문항, 결측 코드.
다중 선택/순위 항목을 0/1 또는 여러 열로 분할합니다. 척도 총점은 먼저 신뢰도(α/ω)와 차원을 확인합니다.
개방형 항목은 먼저 주제 코딩을 수행한 다음 개수/범주 변수로 변환할 수 있습니다. 단어 빈도를 바로 주제로 사용하지 마십시오.
표 데이터의 기본 키, 단위, 시간 필드는 원본 파일로 역추적할 수 있어야 합니다.

게이트: 10개 레코드를 무작위로 추출하여 코딩 값 → 증거 문장/원본 필드 → 원문/원본 행으로 완전히 역추적할 수 있어야 합니다. 그렇지 않으면 코딩 테이블로 돌아가 규칙을 수정합니다.

자세한 내용은 references/02-coding-protocol.md를 참조하십시오.

단계 3: 데이터셋

다음 세 가지를 권장합니다.

data/coded.jsonl: 자료별 코딩 세부 정보 + 증거 조각, 역추적 용이.
data/analysis.csv: 분석용 와이드 테이블, 한 행에 하나의 분석 단위.
data/analysis.sav: SPSS에서 직접 열 수 있으며, 변수 레이블/값 레이블 포함.

다음 표시 열을 포함해야 합니다.

열	의미
`in_scope`	연구 범위에 속하는지 여부 (시간, 유형, 지역, 언어)
`in_analysis`	기술 통계에 포함되는지 여부 (코딩 불가/키 결측 제외)
`model1_sample` 등	각 모델별 별도 샘플 표시. `in_analysis`로 대체하지 마십시오.
`dup_group`	중복 그룹 ID. 보관본은 0, 복사본은 1
`exclusion_reason`	제외 이유, 샘플 흐름 작성 용이

scripts/csv_to_spss_syntax.py를 사용하여 .sps를 생성하고, GET DATA를 수동으로 작성할 때 열 유형 불일치를 방지합니다. CSV에 "예/아니오, 있음/없음, 지원함/지원하지 않음"과 같은 이진 텍스트가 있는 경우 스크립트는 자동으로 RECODE ... ('예'=1) ('아니오'=0) INTO *_num을 추가합니다. Logistic은 숫자 열을 직접 사용합니다. --no-recode를 추가하여 이 동작을 비활성화할 수 있습니다.

게이트: CSV 행 수, JSONL 행 수, SAV 행 수, sample_flow.md의 고유 샘플 수가 서로 일치해야 합니다. 각 모델 N은 필터 조건에서 다시 계산할 수 있어야 합니다.

단계 4: 통계 분석 및 확장

먼저 분석 계획을 작성한 다음 결과를 확인합니다. 기본적으로 "주요 분석 + 기술 통계 + 이변량 + 다변량 + 진단 + 이질성 + 강건성" 조합을 수행하며, 주 모델 하나만 실행하지 않습니다.

먼저 자동 스크리닝 스크립트를 사용하여 기술 통계, 그룹 간 검정, 상관 관계 및 단변량 모델을 실행합니다.

python scripts/auto_stats.py --data data/analysis.csv --config assets/chart_config.example.json --out output/analysis_pack

descriptives.csv, group_tests.csv, binary_rates.csv, correlations.csv, univariate_models.csv, univariate_skipped.csv 및 analysis_pack.md를 출력합니다. 이는 추가 모델링할 가치가 있는 변수를 발견하는 데 사용됩니다. 최종 모델은 여전히 사전 지정된 사양에 따라 SPSS/R/Stata에서 추정되며, 자동 스크리닝의 p-값을 사용하여 변수를 선별하지 마십시오.

스크립트는 결과 변수 유형을 자동으로 식별합니다.

0/1 → 이진 결과 (Logistic/OR).
연속 숫자 → 연속 결과 (OLS/평균+CI). 다중 범주인 경우 그룹 간 검정은 Kruskal–Wallis를 사용합니다.
다중 범주 → 범주형 결과, 그룹 간 검정은 카이제곱/Cramér's V 사용. 다중 범주 독립 변수는 단변량 OLS/Logit에 더미 변수로 들어가고 변수_수준 형식으로 보고됩니다.
다중 범주 결과 자체는 이진 Logit을 사용하지 않습니다. 주 모델은 다항 Logit을 사용하거나 먼저 범주를 병합해야 합니다.
"예/아니오, 있음/없음, 지원함/지원하지 않음"과 같은 일반적인 텍스트 레이블은 자동으로 0/1로 매핑됩니다. 다른 이진 텍스트는 구성 항목 outcome_map을 사용하여 긍정 클래스를 지정해야 합니다.
완전 분리, 추정이 불안정한 단변량 모델은 univariate_skipped.csv에 기록되며, 허위로 큰 OR을 제공하지 않습니다.
결과 열이 모두 결측, 필터 후 0행, filter_query 오타가 있는 경우 즉시 오류와 함께 종료됩니다.

최소한 다음을 포함합니다.

기술 통계: 각 그룹의 N, 비율/평균, 결과율, 95% Wilson CI.
주 모델: 이진 Logistic / OLS / 다항 Logit, 종속 변수, 참조 그룹, 핵심 독립 변수, 통제 변수를 명시합니다.
메커니즘/조절 모델: 상호 작용 항, 단순 기울기 또는 그룹별 예측 값.
강건성: 종속 변수 대체, 샘플 대체, 통제 변수 추가/제거, 중복 제거 전후.
진단: 다중 공선성, 완전 분리, 샘플 크기가 부족한 셀, 교정/판별.
이질성: 범주별/지역별/연도별/그룹별.
수행 가능한 탐색: PCA, 대응 분석, 군집 분석, 예측 ROC/교정; "탐색적"으로 표시합니다.

보고서 표에는 최소한 다음이 포함되어야 합니다. 계수/OR, 95%CI, p, N, 적합도 지표, 참조 그룹 설명. 각 모델마다 별도의 행에 N을 표시합니다.

수행하고 건너뛴 분석을 analysis_manifest.md에 기록합니다(템플릿은 references/08-analysis-expansion.md 참조). 유의미한 결과만 보고하지 마십시오.

SPSS 구문 템플릿과 해석 규범은 references/03-analysis-spss.md를 참조하십시오. 확장 분석 목록은 references/08-analysis-expansion.md를 참조하십시오.

게이트: 모든 OR/β는 analysis.sps → 출력 파일 → 테이블의 세 단계로 역추적할 수 있어야 합니다. analysis_manifest.md는 각 분석의 수행/미수행 이유, 샘플 크기를 설명할 수 있어야 합니다. 본문에는 "텍스트에 특정 상황이 기록되어 있음"을 "특정 효과가 실제로 발생했음"으로 잘못 해석하는 인과 관계 결론이 없어야 합니다.

단계 5: 출판급 차트 (기본적으로 전체 패널, 8장만 그리지 않음)

먼저 scripts/auto_chart_pack.py를 실행하여 전체 차트 패키지를 생성한 다음, 본문 주요 차트, 부록 차트 및 추가로 그릴 필요가 있는 모델 차트를 선택합니다.

python scripts/auto_chart_pack.py \
  --data data/analysis.csv \
  --config assets/chart_config.example.json \
  --out output/chart_pack --tiff

연속/다중 범주 결과의 경우 스크립트를 수정할 필요가 없습니다. 결과 변수는 자동으로 "결과 분포 + 그룹 평균/구성" 차트로 전환됩니다. 텍스트 결과도 outcome_map을 사용하여 코딩을 지정할 수 있습니다. --coef는 metric (OR/HR/RR/beta) 및 n 열을 지원하며, 포레스트 플롯은 모델 샘플 크기에 따라 N을 작성합니다. --pred는 0/1 또는 "예/아니오" 레이블을 지원합니다. 상수 예측/단일 범주는 ROC/PR/교정을 건너뛰고 이유를 명시합니다. term_labels는 lv3와 같은 모델 항목 이름을 중국어로 매핑할 수 있습니다. 이중 비율 덤벨 차트는 config에서 dumbbell을 사용하여 두 개의 0/1 열을 지정해야 합니다. 추적 시간 및 이벤트 열이 있는 경우 --survival-time, --survival-event (선택적으로 --survival-group 추가)를 사용하여 Kaplan–Meier 곡선을 생성합니다.

기본적으로 7개 그룹을 다루며, 일반적으로 약 40–55개 차트를 생성합니다. 이진: 약 44개 차트 (모델 입력 포함 시 약 51개). 연속: 약 42개 차트. 다중 범주: 약 41개 차트. 열 유형, 결측 및 건너뛴 항목에 따라 수량이 달라질 수 있습니다. 실제 수량은 chart_manifest.csv를 기준으로 합니다.

A 데이터 품질: 결측률, 샘플 범주/연도/지역, 이진 변수 발생률.
B 단변량: 결과 분포 (이진/연속/다중 범주 각각 처리, 연속 결과는 Q-Q 추가), 처리 구성 (막대+도넛), 숫자 분포, 범주 구성.
C 이변량: 범주×결과, 단계×결과, 범주×단계 히트맵/스택, 지역/심급 차이, 상관 히트맵, 산점도 피팅, 버블 차트. 연속 결과는 평균+95%CI 사용, 다중 범주 결과는 그룹 내 구성 스택 차트 사용.
D 다변량: 바이올린/상자 그림, 산점도 행렬, 덤벨 차트, PCA 스크리/이중 플롯/로딩 히트맵, Ward 군집 덴드로그램, 클래식 MDS.
E 시간: 결과율/평균 추세, 3σ 관리도, 샘플 크기, 단계 구성 스택 막대/영역. 다중 범주 결과는 결과 범주 구성 추세를 추가.
F 모델 진단: 포레스트 플롯, ROC, 교정, 예측 분포, 혼동 행렬, PR 곡선, 십분위 Lift (--coef/--pred 필요). Kaplan–Meier (추적 열 필요).
G 부록: 대응 분석, Pareto.

차트 작성 전략:

각 주요 발견에는 최소 2개의 차트: 주요 결과 차트 + 강건성/진단/이질성 차트.
본문 7–10개 차트, 부록 20–50개 차트; 차트 수에는 상한이 없습니다.
각 차트에 대해 먼저 "어떤 질문에 답하는가"를 작성합니다. 질문이 없으면 그리지 않습니다.
references/07-chart-atlas.md를 사용하여 유형을 선택하고 SPSS 고급 그래프를 다룹니다: 군집/스택/100% 스택 막대, 선/영역, 히스토그램, 상자/바이올린, 오차 막대, 산점도/버블, 산점도 행렬, Pareto, ROC, 교정, Kaplan-Meier (생존 데이터 있는 경우), 스크리 플롯, 요인 로딩, 군집 덴드로그램, 대응 분석, MDS, 관리도 등.
각 차트는 chart_manifest.csv에 기록됩니다: 차트 번호, 질문, 유형, 변수, N, 범례, 파일 경로.
색상 의미는 원고 전체에서 통일됩니다. 동일 단계/동일 범주는 모든 차트에서 동일한 색상을 사용합니다.
범례에는 N, 데이터 출처, 모델 설정, 참조 그룹을 명확하게 작성합니다. 탐색적 차트(PCA/CA/군집)는 범례에 "탐색적"으로 표시합니다.

scripts/pubfig.py를 사용하여 스타일을 통일합니다.

from pubfig import set_style, save_fig, wilson_ci, forest_plot
set_style()  # 15 cm 판형, 송체/Times New Roman, 600 dpi

규범 요점:

물리적 너비 15 cm (A4 본문 15.4 cm 이내), 글꼴 크기 7.2–8.5 pt.
중국어는 송체, 서양어는 Times New Roman; PDF 글꼴 포함 (Type 42).
차트 내에는 제목을 넣지 않습니다. 차트 제목과 범례는 Word에서 배치합니다.
동시에 PNG 600 dpi, 벡터 PDF, LZW TIFF (--tiff)를 출력합니다.
오차 막대는 95% CI를 명시합니다. 포레스트 플롯은 채워진 점=유의미, 빈 점=유의미하지 않음.
왜도가 있는 연속 변수는 log10 또는 P99 절단을 사용하고 축 레이블/범례에 명시합니다.

게이트: chart_manifest.csv의 각 차트에는 질문, N, 범례, 파일이 있습니다. 본문 주요 차트와 부록 차트는 중복되지 않습니다. PDF에 포함된 이미지의 너비는 ≥ 3000 px (15 cm 너비에서 약 600 dpi)입니다. 범례, 차트, 본문 인용이 모두 완비되어 있습니다.

자세한 내용은 references/04-figures-publication.md 및 references/07-chart-atlas.md를 참조하십시오.

단계 6: 원고 조립

Word 레이아웃 요구 사항:

그림, 그림 제목, 그림 범례는 "다음 단락과 같은 페이지"로 설정하여 그림 제목이 페이지 나뉘지 않도록 합니다.
표 행은 페이지 나뉘지 않도록 하고 페이지가 나뉘면 표 머리글을 반복합니다.
표 범례는 그림/표 아래에 위치합니다. 먼저 N을 제공한 다음 유의성 규칙을 제공합니다.
본문에서 그림/표를 처음 인용할 때 번호는 파일과 일치해야 합니다 (그림 1, 표 1, 부록 그림 1).
초록, 본문, 표, 그림, 부록의 N과 백분율은 모두 동일한 출처에서 가져와야 합니다. chart_manifest.csv의 N은 범례에 다시 기록됩니다.

Word에서 PDF로 내보낼 때 Word는 600 dpi 이미지를 약 200 dpi로 압축합니다. scripts/export_pdf_hires.py를 사용하여 내보낸 후 원본 이미지를 다시 채웁니다.

python scripts/export_pdf_hires.py --docx "manuscript.docx" --out-pdf "manuscript.pdf" --figure-map "figure_map.json"

게이트: PDF 페이지 수, 그림 수, 그림 제목 수가 일치합니다. 각 그림의 포함된 너비는 ≥ 3000 px입니다. 표 행/표 머리글이 끊어지지 않습니다.

자세한 내용은 references/05-manuscript-assembly.md를 참조하십시오.

단계 7: 최종 검사

실행:

python scripts/qa_outputs.py --docx "manuscript.docx" --pdf "manuscript.pdf" --figures "figures" --data "data/analysis.csv" --audit "output/audit/corpus_audit.csv" --manifest "output/chart_pack/chart_manifest.csv" --strict

그런 다음 references/06-qa-checklist.md에 따라 수동으로 한 번 더 확인합니다. 중요한 것은 형식이 아니라 다음과 같습니다.

샘플 흐름의 각 단계 숫자가 일치해야 합니다.
중복 복사본이 분석 샘플에서 제거되었거나, 제거하지 않은 영향이 명확하게 보고되었습니다.
본문의 각 N은 해당 표/그림/모델과 일치합니다.
차트와 본문이 동일한 방향을 말하고 있으며, "그림은 상승하는데 글은 하락한다"는 상황이 없습니다.
PDF의 그림 범례 번호는 "그림1:", "그림 1.", "Table 1:" 등의 표기를 인식할 수 있습니다. 저해상도 검사는 충분히 큰 그림에 대해서만 수행됩니다. 빈 CSV는 직접 오류를 보고합니다.
이론적 코딩 변수는 방법 섹션에서 출처를 설명하고, 원시 자료에서 직접 측정된 것으로 작성하지 않습니다.
결론은 "연관/대응"을 사용하고 인과적 표현을 사용하지 않습니다.

스크립트 목록

다음 명령은 현재 디렉터리가 skill 루트 디렉터리라고 가정합니다. 프로젝트 디렉터리에서 실행하는 경우 scripts/를 skill의 절대 경로로 바꾸십시오.

스크립트	기능
`scripts/audit_corpus.py`	모든 자료 디렉터리 스캔: 파일 상태, 텍스트/페이지 수, MD5, 중복, 형식 분포, 연도 힌트
`scripts/dedupe_corpus.py`	감사 결과 기반 중복 제거 계획 생성; `--apply`는 `_duplicates/`로 이동
`scripts/make_coding_sheet.py`	PDF/Word/PPT/HTML/텍스트에서 전체 텍스트 및 키워드 증거 문장 추출; `--profile legal`인 경우에만 법원/사건 번호 필드 추출
`scripts/text_extract.py`	일반 텍스트 추출 및 파일 검사 (PDF/DOCX/ODT/PPTX/XLSX/HTML/텍스트/이미지/오디오/비디오)
`scripts/analysis_utils.py`	내부 공유 함수: 샘플 필터링, 결과 유형 식별, 이진 레이블 코딩; 자동 통계/차트 스크립트에서 가져옴
`scripts/csv_to_spss_syntax.py`	CSV 헤더에서 SPSS `GET DATA` 구문 생성; 불법/중복 변수명 정리 및 변수 레이블 작성
`scripts/auto_stats.py`	자동 기술 통계, 그룹 간 검정, 상관 관계, 단변량 모델 (다중 범주 독립 변수 더미화), 완전 분리 검사
`scripts/auto_chart_pack.py`	열 역할에 따라 약 40–55개의 데이터 품질/분포/이변량/군집/시간/모델 진단/생존 차트 및 manifest 자동 생성
`scripts/pubfig.py`	출판 그림 통일 스타일, Wilson CI, 포레스트 플롯, 히트맵, 바이올린, ROC/PR, PCA, MDS, 군집, KM, 관리도 등 30개 이상의 그래프 유형
`scripts/export_pdf_hires.py`	Word→PDF 및 600 dpi 원본 이미지 다시 채우기
`scripts/qa_outputs.py`	PDF 그림 해상도, docx 차트/표 수, 빈 데이터, 중복 키, manifest의 N/범례/경로 확인

참조 문서

파일	언제 읽는가
`references/01-corpus-audit.md`	감사 시작, 중복/손상/스캔 파일/다중 형식 발견 시
`references/02-coding-protocol.md`	변수 설계, codebook 작성, 신뢰도 검증 시
`references/03-analysis-spss.md`	모델 설정, SPSS 구문 작성, OR 해석 시
`references/04-figures-publication.md`	그림 그리고, 색상 선택, 제출 파일 내보낼 때
`references/05-manuscript-assembly.md`	Word 정리, PDF 내보내기, 그림 범례 처리 시
`references/06-qa-checklist.md`	제출/인도 전 항목별 확인 시
`references/07-chart-atlas.md`	그림 유형 선택, SPSS 고급 그래프 대응, 차트 수 결정 시
`references/08-analysis-expansion.md`	주 모델 외에 어떤 분석을 더 수행할지, 수행/미수행 기록 방법 확인 시

템플릿

assets/scope-template.md: 연구 범위, 포함/제외 기준, 샘플 흐름 뼈대.
assets/codebook-template.md: 변수 코딩 매뉴얼 뼈대.
assets/figure-spec-template.md: 그림 범례 및 제도 사양 표.
assets/figure_map.example.json: Word→PDF 다시 채움 이미지 매핑 예시.
assets/delivery-checklist.md: 인도 목록.
assets/coding-keywords.json: 교체 가능한 키워드 사전 (일반 자리 표시자 예시).
assets/chart_config.example.json: 열 역할, 레이블, 분석 샘플 필터 (filter_query) 예시.
assets/analysis-manifest-template.md: 주요 분석/확장 분석/건너뛴 항목 목록.

가장 흔한 실수 지점

폴더의 파일 수를 바로 샘플 크기로 사용. 먼저 메타데이터, 손상, 중복, 지원되지 않는 형식, 범위 외를 제외해야 합니다.
파일 이름만으로 중복 제거. 동일한 내용은 종종 "식별자 있음/없음", "- 복사본", "(2)" 등 여러 버전이 있습니다.
기술 통계 N과 모델 N 혼용. 모델에는 결측값, 필터 조건이 있으므로 N은 항상 더 작습니다.
"자료에서 특정 상황을 언급함"을 "특정 결과가 실제로 발생했음"으로 오해. 이는 텍스트 연관성이며 인과 효과가 아닙니다.
Word에서 내보낸 PDF가 정상적으로 보이지만 그림은 실제로 200 dpi에 불과. 포함된 이미지 너비를 다시 채우고 확인해야 합니다.
주요 결과 그림만 한 장 그림. 분포, 이질성, 강건성, 진단 그림을 그리지 않으면 사용자가 반복해서 질문하게 됩니다.
참고/첨부 자료의 내용을 주요 자료로 취급. 문서 유형, 보고서 유형, 웹 페이지 탐색 등은 제목/본문 구조로 판단해야 하며, 전체 텍스트 키워드만으로 판단해서는 안 됩니다.
결과가 "예/아니오" 텍스트인데 연속 변수로 직접 처리. outcome_map을 사용하여 긍정 클래스를 명시적으로 지정하거나 CSV에서 0/1로 코딩하십시오. 스크립트는 긍정/부정 방향을 추측하지 않습니다.
감사 시 특정 형식만 세고 다른 파일은 조용히 누락. 모든 파일에는 상태가 있어야 합니다. total_files는 탐색기와 대조될 수 있어야 합니다.
테이블 데이터를 텍스트 코딩에 강제로 넣음. CSV/Excel은 auto_stats/SPSS 프로세스를 직접 따릅니다. 텍스트 코딩은 문서, 인터뷰, 웹 페이지 등 비정형 자료에 적합합니다.

lybxkl/empirical-research-pipeline

empirical-research-pipeline란 무엇인가요?

즐겨 사용하는 AI에게 물어보기

문서