왜 필요한가
QIIME 2 의 명령은 이미 정해져 있습니다. 문제는 명령 사이에서 사람이 손으로 정하던 값과, 검증을 지나지 않은 차이가 원고에 들어가는 길입니다.
절단 길이(trunc-len) · 저빈도 기준(min-frequency) · 희소화 깊이(sampling-depth) · 제외 분류군 · 비교 컬럼. 사람이 정해 온 이 다섯 값은 무엇을 버렸고 왜 버렸는지가 함께 남아야 같은 결론을 다시 낼 수 있습니다.
PERMANOVA 는 군 안의 퍼짐이 다를 때도 유의해집니다. 키메라 제거에서 잃은 비율이 장 부위와 얽혀 있으면, 부위가 섞인 비교는 군집의 차이가 아니라 처리의 차이를 잴 수 있습니다.
다시 돌리면 표는 바뀌는데 손으로 옮겨 적은 숫자는 그대로 남습니다. 시연 자료에서도 같은 분석의 희소화 깊이가 문서에는 77,093, 산출물에는 77,135 로 적혀 있었습니다.
누가 쓰나
16S 앰플리콘 자료로 군집을 비교하고 그 결과를 논문에 싣는 연구팀이 대상입니다. (사용자 유형은 앱 화면에서 사람이 맡는 일 — 입력 · 결정 · 원고 · 확인 — 을 기준으로 정리했습니다.)
FASTQ · manifest · metadata 를 넣고 01단계 입력 대조 결과를 확인합니다. R 과 Python 없이 16단계의 진행과 단계마다의 판단을 읽습니다.
게이트 판정과 「결정 대기」를 보고, 막힌 절을 어떻게 풀지 — 군을 뺄지, 검정을 바꿀지, 그대로 보고할지 — 를 정합니다.
통과한 절의 표와 방법 · 결과 · 한계 문장을 한국어 또는 영어로 복사해 원고에 붙입니다. 보류된 절에는 막힌 사유가 함께 옵니다.
실행 기록(run.lock)과 아티팩트 계보로 원고의 숫자가 어느 산출물, 어느 명령에서 나왔는지 확인합니다.
네 국면, 16단계로 끝까지
화면 2열의 16단계가 네 국면으로 묶여 있고, 앞 단계가 끝나야 다음 단계가 돕니다. 게이트가 막아도 계산은 16단계까지 돌고, 막히는 것은 그 결과를 원고에 싣는 일입니다.
| 요청 (시연 대화의 첫 요청 문장) | 담당 단계 | 이 서비스가 하는 일 |
|---|---|---|
| ① 16S 자료 처리 「V3–V4, 50 샘플」 | 준비 01–04 실험 05–09 | FASTQ · manifest · metadata 세 입력을 대조해 잠그고, 리드 품질 관리 · QIIME 2 반입 · 프라이머 제거를 거쳐 절단 길이를 골라 DADA2 로 ASV 표를 만듭니다. 분류군을 붙이고 비표적 · 저빈도 서열을 빼 표를 확정합니다. |
| ② 다양성 비교 「성별 · 유전형 · 장 부위로 나눠서」 | 검증 10–14 | 희소화 깊이를 정하고 계통수를 세워 알파 지표 4종 · 거리행렬 4종을 계산합니다. 세 요인을 합친 8군(sexwithgroup,site)과 단일 요인(group, KO 대 WT)을 함께 비교하고, 베타 비교에는 PERMANOVA 와 함께 PERMDISP 를 돌립니다. |
| ③ 논문용 표 · 그림 「논문에 넣을 표랑 그림까지 정리」 | 산출 15–16 | 게이트 셋을 판정해 실행 기록을 묶고, 통과한 절만 표 · 그림 · 수치 매크로와 방법 · 결과 · 한계 문장으로 냅니다. 한국어판과 영어판을 따로 만듭니다. |
다시 도는 규칙 — 막힌 절을 풀 안을 고르면 14단계부터, 분류기를 바꾸면 07단계부터 다시 돕니다. 프라이머 · 리드 길이 · 탐색 격자가 같으면 05단계의 절단 길이 선택은 저장된 것을 다시 씁니다.

화면으로 보기 — 시연 회차 「Galectin-3 KO 장내 미생물 군집 분석」
세계김치연구소가 제공한 16S 자료(50쌍 · 8군)를 실제로 끝까지 돌린 실행을 데모 실행으로 재생해 따라갑니다. 단계 순서와 산출 수치는 그 실행에서 왔고, 줄인 것은 기다리는 시간(6시간 24분)뿐입니다. 05단계 절단 길이 표와 14단계 PERMDISP 값은 화면에 「예시」로 표시된 값입니다.
넣은 파일들이 같은 샘플을 가리키나
① 16S 자료 처리
- FASTQ · manifest · metadata 세 입력이 같은 대상을 가리키는지 대조하고 잠급니다. 여기서 어긋난 것이 뒤에서 「샘플이 조용히 빠진 표」로 나타나지 않게 하려는 것입니다.
- 리드 품질 관리(fastp), QIIME 2 반입, 프라이머(341F / 805R) 제거를 차례로 거칩니다.
- 16단계 모두 목적 · 핵심 수치 · 계약(받는 것 → 내는 것) · 실행한 명령 · 판단 · 넘김이 같은 순서로 놓입니다.
01 샘플 50 · FASTQ 100건 · manifest 100행 · 대조 불일치 0건
02 처리 쌍 50 · 평균 잔존 97.3% · Q30 88.1 → 94.6%
04 프라이머 제거율 99.4% · 잔존 0.6%

서열은 몇 종류로 확정되었고, 무엇을 잃었나
① 16S 자료 처리
- 절단 길이를 24조합 탐색해 정방향 220 · 역방향 220 을 고르고(05), DADA2 로 노이즈와 키메라를 걷어 ASV 표를 만듭니다(06).
- 분류군을 붙이고(07) 고세균 · 엽록체 · 미토콘드리아 · 미지정 · 진핵을 뺀 뒤(08), 전체 빈도 2 미만 ASV 를 지웁니다(09).
- 키메라 제거 손실이 커도 크기만으로 막지 않습니다. 샘플당 남은 리드가 희소화에 충분한지와, 손실이 비교 군과 얽혀 있는지를 봅니다.
06 ASV 1,827 · 총 리드 8,456,468 · 최소 샘플 77,157 · non-chimeric 34~67%
07 속 수준까지 이름을 받은 ASV 51.9%
08 −31 → 1,796 · 09 −335 → ASV 1,461

몇 리드에 맞춰 비교해야 하나
② 다양성 비교
- 리드가 많은 샘플일수록 ASV 가 더 관찰되므로 깊이를 맞춰야 합니다. 곡선이 포화되었는지와 그 깊이에서 몇 샘플이 빠지는지를 함께 재서 고릅니다.
- 판단 기록에는 고른 값만이 아니라 버린 안과 그 대가가 남습니다.
채택 깊이 77,135 · 탈락 샘플 0 / 50 · 곡선 기울기 0.0004
90,000 으로 올리면 기울기는 같은 0.0004 인데 샘플 3개가 빠져 손실만 늘어남
50,000 은 기울기 0.0011 로 포화 미달

군마다 다양성은 어떻게 다른가
② 다양성 비교
- 알파 지표 4종(Faith PD · Shannon · Evenness · Observed)과 거리행렬 4종(UniFrac 2 · Jaccard · Bray–Curtis)을 계산합니다.
- 8군 쌍별 비교와 단일 요인(KO 대 WT) 비교를 나란히 싣습니다. 쌍별 결과만 실으면 「KO 가 다양성을 바꿨다」로 읽히기 때문입니다.
- 게이트가 막은 그림(PCoA)은 계산은 되었지만 「보류」 표시와 함께 산출물에서 빠집니다.
알파: Shannon 쌍별 비교에서 q < 0.05 인 쌍 17 / 28 · 단일 요인 group 은 네 지표 모두 유의하지 않음(Shannon p = 0.655)
베타: PERMANOVA q < 0.05 쌍 19 / 28 · PERMDISP 위반 2쌍(예시 값) → 베타 보류

이 차이를 논문에 써도 되나
② 다양성 비교 ③ 논문용 표 · 그림
- 게이트 셋이 검사 항목을 재서 통과 · 조건부 · 차단을 냅니다 — 품질(리드가 분석을 지탱하는가) · 설계(군간 차이라고 말할 수 있는가) · 재현(같은 입력이 같은 숫자를 내는가).
- 게이트는 절 단위로 작동합니다. 베타 다양성이 막혀도 근거가 온전한 알파 다양성 절은 실립니다.
- 조건부는 범위를 좁혀 싣습니다. 시연에서는 키메라 제거 통과율이 장 부위와 얽혀 있어(LI 40.7% 대 SI 57.1%, p = 1.3e−09), 알파 절에 KO 대 WT 비교만 싣고 부위가 섞인 비교는 한계 절로 내립니다.
품질 조건부 · 설계 차단 · 재현 통과
재현: 희소화 20회 반복 Shannon 표준편차 0.004 · 원 실행과 지표 4 / 4 일치 · 손으로 옮긴 숫자 0건

논문에는 무엇을 붙이나
③ 논문용 표 · 그림
- 통과한 절만 표 · 그림 · 수치 매크로와 방법 · 결과 · 한계 문장으로 냅니다. 완성 논문이 아니라 삽입용 조각입니다 — 지면은 학술지 양식이 정하기 때문입니다.
- 한국어 · English 를 눌러 같은 실행 기록에서 만든 두 언어판을 봅니다. 표 형태로 복사해 원고에 붙이거나 LaTeX 조각으로 받습니다.
- 게이트가 막은 표 · 그림은 빠지고, 그 자리에 무엇이 왜 막혔는지가 들어갑니다.
표 1: DADA2 ASV 1,827 → 비표적 제거 1,796 → 저빈도 제거 1,461 → 희소화(77,135) 1,460
결과 문장: 「유전형 단일 요인으로는 네 지표 모두 유의하지 않았다(q ≥ 0.655)」

막힌 절은 누가, 어떻게 푸나
③ 논문용 표 · 그림
- 막힌 것은 계산이 아니라 결과를 싣는 일이라, 실행의 마지막 상태는 「완료 · 결정 대기」입니다. 기다리는 것은 사람의 판단입니다.
- 에이전트는 안과 그 대가만 내놓습니다 — 위반 2군을 뺀다(6군 15쌍으로 다시 비교) · 검정을 ANOSIM 으로 바꾼다(군 크기에 민감해 조건부로만 통과) · 그대로 보고한다(베타 절은 싣지 않고 사유를 남김).
- 하나를 고르면 14단계부터 다시 돌고, 바꾼 사실과 이유가 게이트 표와 실행 기록에 남습니다.
「위반 2군을 뺐습니다 — 14 단계부터 다시 돌려 끝났습니다」 · 상태 완료
게이트: 품질 조건부 · 설계 통과 · 재현 통과

원고의 이 숫자는 어디서 왔나
③ 논문용 표 · 그림
- 산출물의 모든 숫자는 실행 기록
run.lock한 곳에서 나옵니다 — QIIME 2 배포판 이미지와 해시, 분류기, 난수 시드, 희소화 반복, 순열 횟수, 게이트 판정. - 아티팩트 계보에는 각
.qza의 UUID 와 그것을 만든 명령이 이어집니다. - 이 QIIME 2 판의 희소화에는 시드를 걸 수 없어, 20회 반복해 지표의 변동폭을 함께 보고합니다.
QIIME 2 amplicon:2024.2 · 순열 검정 시드 42 · 희소화 20 draw(Shannon 표준편차 0.004) · 순열 999
깊이 77,135(09단계 아티팩트에서 읽음) · 아티팩트 .qza 38건 · .qzv 21건

run.lock, 아래는 아티팩트 계보(UUID 와 명령)입니다.내 자료도 넣어 볼 수 있나
① 16S 자료 처리
- 「새 분석」에 manifest · metadata · FASTQ 를 끌어다 놓으면 브라우저 안에서 01단계 입력 검증을 합니다. 파일은 브라우저 밖으로 나가지 않습니다.
- 샘플 ID 와 FASTQ 짝을 대조해 manifest 에 있는데 파일이 없는 샘플, 짝 없는 파일을 집어냅니다.
- 이 상태에서는 연구소 자료의 결과 뷰를 가립니다. 02단계부터는 QIIME 2 가 있는 서버가 받아야 하고, 이 데모 사이트는 거기까지 연결되어 있지 않습니다.
샘플 쌍 4 · FASTQ 9건 · manifest 10행 · 대조 불일치 2건
FASTQ 없음 1개(S05) · 짝 없음 1건

돌아가는 동안 무엇을 알려 주나
① 16S 자료 처리 ② 다양성 비교
- 단계가 끝날 때마다 맡은 에이전트가 3열 대화창에 보고합니다. 판단이 걸린 단계(절단 길이 · 품질 · 깊이 · 베타 다양성 · 산출)는 근거 표와 경고 상자를 붙여 보고합니다.
- 아직 돌지 않은 단계의 숫자는 화면 어디에도 보이지 않습니다 — 재생 중 최종 ASV 칸은 「09 단계 대기」처럼 비어 있습니다.
- 데모의 대화는 끝난 실행의 보고를 재생한 것입니다. 입력창에 적은 말은 대화에만 남고, 답이나 실행은 일어나지 않습니다(화면 안내 문구).
「손실의 크기로는 막지 않았습니다 … 유전형과는 얽혀 있지 않은데(KO 47.5% 대 WT 50.5%, p = 0.28) 부위와는 얽혀 있습니다(LI 40.7% 대 SI 57.1%, p = 1.3e−09)」
→ 품질 게이트 조건부 통과 · KO 대 WT 비교는 그대로 진행

믿을 수 있게 만든 원칙
이 업무에서 가장 위험한 오답은 군 안의 퍼짐 차이나 처리 손실 때문에 생긴 「유의한 차이」가 군집 조성의 차이로 원고에 실리는 것입니다. 표에 q 값이 붙어 있으면 읽는 사람은 그것을 검증된 결론으로 인용합니다.
막힌 절은 싣지 않는다
게이트가 막으면 그 게이트가 지키는 표와 그림은 조판하지 않고, 그 자리에 무엇이 왜 막혔는지를 남깁니다. 경고만 달아 싣지 않습니다 — 실제로는 표의 q 값만 인용되기 때문입니다.
판정은 미리 정한 기준이 낸다
에이전트는 판정을 만들지 않습니다. 통과 여부는 미리 정한 임계값(예: 샘플별 non-chimeric 30% 이상, merge 75% 이상)이 내고, 기본값을 통과가 쉬운 쪽으로 잡지 않았습니다.
고른 값마다 버린 안을 남긴다
사람이 정하던 다섯 값(절단 길이 · 저빈도 기준 · 희소화 깊이 · 제외 분류군 · 비교 컬럼)은 단계 상세의 「판단」에 질문 · 고른 안 · 버린 안 · 이유로 남습니다.
교락은 재고, 범위를 좁힌다
처리 손실이 비교 요인과 얽혀 있는지 검정합니다. 얽혀 있으면 어느 쪽이 원인인지 판정하지 않고, 그 비교를 싣지 않은 채 한계 절에 적습니다.
숫자는 한 곳에서
원고의 숫자는 실행 기록과 아티팩트에서만 읽습니다. 문서에 적힌 값(77,093)과 산출물의 값(77,135)이 다르면, 계산이 추적되는 산출물 쪽을 정본으로 씁니다.
막혀도 끝까지 돌고, 결정을 기다린다
막힌 단계가 파이프라인을 세우지 않습니다. 16단계까지 돌고 「결정 대기」로 끝나며, 사람이 고르면 14단계부터 다시 돌고 바꾼 사실을 함께 남깁니다.
이 앱은 AI 모델을 부르지 않습니다. 화면의 「에이전트」는 단계마다 일을 맡은 실행 단위의 이름이고, 게이트 판정은 임계값 계산이며, 원고 문장은 실행 기록의 숫자를 정해진 틀에 넣어 만든 검토용 초안입니다. 데모의 대화창은 끝난 실행의 보고를 재생합니다.
자료 범위
시연은 세계김치연구소가 제공한 16S rRNA V3–V4(341F / 805R) 앰플리콘 자료를 끝까지 돌린 실행 하나입니다. 아직 공개되지 않은 연구 자료이므로 이 사이트에는 집계된 수치만 있고 원시 리드는 없습니다.
FASTQ 100건(50쌍) · 성별 × 유전형 × 장 부위 8군, 군별 6~7
네 국면 · 실제 실행 소요 6시간 24분
DADA2 의 1,827개에서 비표적 · 저빈도 서열을 뺀 뒤
보류 표 2 · 그림 2, 한국어 · 영어 각각
한계와 다음 단계
지금 이 주소에서 보는 것은 실제로 끝난 실행을 재생하는 정적 시연 화면입니다. 내 파일은 01단계 입력 검증까지만 하고, 02~16단계를 실제로 돌리는 서버 연결은 아직 없습니다.
실제로 동작하는 것
실제 실행의 단계 순서 · 소요 시간 · 산출 수치를 재생하고, 16단계 모두 목적 · 핵심 수치 · 계약 · 명령 · 판단 · 넘김을 같은 순서로 보여 줍니다.
게이트가 절을 막고, 세 안 중 하나를 고르면 14단계부터 다시 돕니다. 논문 삽입물의 표는 복사해 원고에 붙일 수 있습니다.
manifest · metadata · FASTQ 를 넣으면 브라우저 안에서 샘플 ID 와 FASTQ 짝을 대조합니다. 파일은 밖으로 나가지 않습니다.
아직 채워야 할 것
| 항목 | 지금 상태 | 실제 서비스에 필요한 것 |
|---|---|---|
| 실행 연결 01단계까지 |
02~16단계는 QIIME 2(이미지 9GB)가 있는 서버에서 돌아야 합니다. 이 데모 사이트는 끝난 실행을 재생하고, 내 파일은 01단계 입력 검증까지만 합니다. | 검증된 입력을 실행 서버로 넘기고, 진행 · 판단 · 게이트를 이 화면으로 돌려받는 연결. |
| 시연 값 일부 예시 |
05단계 절단 길이 탐색 표와 14단계 PERMDISP 값은 원 산출물에 없어 화면에 「예시」로 표시한 값입니다. 게이트 판정 셋(통과 · 조건부 · 차단)도 막힌 게이트가 화면에 어떻게 나타나는지 보이려고 둔 시연 구성입니다. | 원 실행의 05단계 산출물을 받아 표를 실제 값으로 바꾸고, PERMDISP 를 실제로 계산해 게이트를 판정합니다. |
| 자료 범위 시연 1건 |
화면에서 볼 수 있는 실행은 이 연구 하나(V3–V4 · 50쌍 · 8군)입니다. 다른 증폭 영역 · 프라이머 · 시료로 돌린 화면은 없습니다. | 연구팀의 다른 과제 자료로 돌려 단계별 판단과 게이트가 의도대로 동작하는지 확인합니다. |
| 판단 범위 통계 검증까지 |
게이트는 품질 · 설계 · 재현만 봅니다. 차이의 생물학적 원인(예: 부위 차이가 군집 복잡도에서 왔는지)은 판정하지 않고 한계 절에 적을 뿐입니다. | 해석 절은 연구자가 쓰도록 남기고, 그 절을 검토하는 절차를 둡니다. |
| 게이트 기준값 앱이 정한 값 |
임계값(예: non-chimeric 30%, merge 75%)과 비교 규칙은 앱에 정해 둔 값이고 화면에서 바꿀 수 없습니다. | 연구소 · 통계 자문과 기준을 정하고, 바꾼 근거를 실행 기록에 남깁니다. |
| 분류 체계 SILVA 138.2 고정 |
분류기는 SILVA 138.2 (341f-785r) 하나로 고정되어 있고, 다른 DB(전장 SILVA · Greengenes2 · GTDB)는 관리자 승인 뒤에만 고를 수 있습니다. 시연에서 속 수준까지 이름을 받은 ASV 는 51.9% 입니다. | 연구 목적에 맞는 DB 선택 기준을 정하고, 분류기를 바꿨을 때 07단계부터 다시 도는 흐름을 실제 자료로 확인합니다. |
| 산출물 품질 검토용 조각 |
완성 논문이 아니라 삽입용 조각입니다. 문장은 실행 기록의 숫자를 정해진 틀에 넣은 초안이라 저자가 다듬어야 하고, 지면 조판은 형제 앱(genffice-docs)으로 넘기도록 나눠 두었습니다. | 대상 학술지 양식에서 확인하고, 저자가 문장을 검토하는 절차를 둡니다. |
| 미공개 자료 집계값만 |
시연 자료는 아직 공개되지 않은 연구 자료라 이 사이트에는 집계된 수치만 있습니다. 연결 상태 화면 기준 FASTQ 는 50쌍 중 1쌍만 있어 01~06단계 재실행은 시험 실행만 가능합니다. | 연구소와 자료 반출 · 보관 범위를 정하고, 전체 FASTQ 로 01~06단계를 다시 돌려 원 실행과 대조합니다. |
| 실행 자원 RAM 13GB 노드 |
연결 상태 화면 기준 분류 실행 노드의 RAM 이 13GB(권장 16GB)라 배치 크기를 낮춰 돌립니다. DADA2 한 번에 시간 단위가 걸립니다. | 자료 규모에 맞는 실행 서버 사양과 실행 대기열을 정합니다. |
| 접근 · 보안 로그인 없음 |
데모 사이트에는 로그인이 없어 주소를 아는 누구나 볼 수 있습니다. 넣은 파일은 브라우저 밖으로 나가지 않습니다. | 기관 계정 로그인, 연구건별 접근 분리, 미공개 자료 보관 · 삭제 정책을 갖춥니다. |
| 전문가 검증 검수 전 |
원 실행 산출물과 지표 값을 대조(4 / 4 일치)한 것 외에, 게이트 판정과 원고 문장을 연구팀이나 통계 전문가가 검수하는 절차는 아직 없습니다. | 대표 연구 몇 건으로 판정과 문장을 검수하고, 틀린 곳을 기준과 문장 틀에 반영합니다. |
| 플랫폼 연결 단독 시연 |
정적 화면 한 장으로 돌고, Genffice 플랫폼의 AI직원 · 드라이브와 연결되어 있지 않습니다. 대화 입력창의 말은 대화에만 남습니다. | 고객 플랫폼에 업무 단계로 등록해 자료 선택 · 산출물 전달과 함께 씁니다. |
다음 단계 제안
예시 값을 실제 계산으로. 05단계 절단 길이 산출물과 PERMDISP 를 실제로 채우고, 전체 FASTQ 로 01~06단계를 다시 돌려 원 실행과 대조합니다.
내 자료로 16단계까지. 01단계를 통과한 입력을 실행 서버로 넘겨 02~16단계를 돌리고, 진행 · 판단 · 게이트를 이 화면으로 돌려받습니다. 실행 노드 사양도 함께 정합니다.
기준 확정과 등록. 연구팀 · 통계 자문과 게이트 기준을 정해 검수하고, 로그인과 함께 Genffice 플랫폼 업무로 등록합니다.