🌐 English|한국어

문제 해결

이 가이드는 PhyloForester의 일반적인 문제를 해결하는 데 도움을 줘요.

설치 문제

애플리케이션이 시작되지 않음

Windows:

  • 오류: “VCRUNTIME140.dll is missing”

    해결 방법: Microsoft에서 Visual C++ Redistributable을 설치하세요

  • 오류: “Application failed to start”

    해결 방법: 관리자 권한으로 실행하고, 백신 프로그램이 차단하지 않는지 확인하세요

macOS:

  • 오류: “App is damaged and can’t be opened”

    해결 방법: ``xattr -cr /path/to/PhyloForester.app``을 실행하세요

  • 오류: “Cannot verify developer”

    해결 방법: 오른쪽 클릭 → 열기 (Gatekeeper 우회)

Linux:

  • 오류: “error while loading shared libraries: libQt5Core.so.5”

    해결 방법: Qt5 라이브러리를 설치하세요 (설치 참조)

Python 소스 설치 실패

  • 오류: “No module named ‘PyQt5’”

    해결 방법: pip install PyQt5

  • 오류: “Microsoft Visual C++ 14.0 is required” (Windows)

    해결 방법: Visual Studio Build Tools를 설치하세요

데이터 관리 문제

데이터베이스를 열 수 없음

증상: “Failed to open database” 오류

해결 방법:

  1. 파일 권한을 확인하세요 (읽기/쓰기 권한)

  2. 데이터베이스 파일이 손상되지 않았는지 확인하세요: - SQLite 브라우저에서 열어보세요 - 백업에서 복원하세요

  3. 디스크 공간을 확인하세요 (데이터베이스가 커질 공간이 필요해요)

데이터베이스 손상

증상: 애플리케이션 충돌, 데이터 누락, 저장 시 오류

복구:

  1. PhyloForester를 종료하세요

  2. 데이터베이스 파일을 찾으세요: - Windows: C:\\Users\\<name>\\PaleoBytes\\PhyloForester\\PhyloForester.db - macOS/Linux: ~/PaleoBytes/PhyloForester/PhyloForester.db

  3. SQLite 복구를 시도하세요:

    sqlite3 PhyloForester.db "PRAGMA integrity_check;"

  4. 손상된 경우 백업에서 복원하세요

예방:

  • 정기적으로 백업하세요 (.db 파일 복사)

  • 저장 중 강제 종료하지 마세요

  • 충분한 디스크 공간을 확보하세요

가져오기/내보내기 문제

파일을 가져올 수 없음

일반적인 원인:

  1. 지원되지 않는 형식

    파일 확장자를 확인하세요 (.nex, .phy, .tnt)

  2. 잘못된 파일 형식

    텍스트 편집기에서 형식을 검증하세요

  3. 인코딩 문제

    UTF-8 또는 ASCII 인코딩을 시도하세요

해결 방법:

  • 로그 메시지에서 구체적인 오류를 확인하세요

  • 텍스트 편집기에서 파일을 열어보세요

  • Nexus 형식으로 변환하세요 (가장 안정적)

내보내기 실패

해결 방법:

  1. 대상 폴더의 쓰기 권한을 확인하세요

  2. 사용 가능한 디스크 공간을 확인하세요

  3. 다른 내보내기 형식을 시도하세요

  4. 간단한 파일명을 사용하세요 (특수 문자 없이)

분석 문제

외부 소프트웨어를 찾을 수 없음

증상: “TNT not found” 또는 유사한 오류

해결 방법:

  1. 소프트웨어 경로 설정: - 편집 → 환경설정 - 실행 파일 위치로 이동 - 확인 클릭

  2. 실행 파일 확인: - 명령줄에서 소프트웨어를 실행해보세요 - 파일 권한을 확인하세요 (Linux/macOS에서 실행 권한)

  3. 철자 확인: - Windows: tnt.exe - Linux/macOS: tnt (확장자 없음)

분석 시작 실패

확인 사항:

  1. 데이터매트릭스에 데이터가 있는지 (비어있지 않음)

  2. 외부 소프트웨어 경로가 올바른지

  3. 프로젝트/데이터매트릭스 이름에 특수 문자가 없는지

  4. 출력 파일을 위한 충분한 디스크 공간이 있는지

로그 탭에서 오류 메시지를 확인하세요

분석이 실행되지만 결과가 없음

가능한 원인:

  1. 트리를 찾을 수 없음 (parsimony) - 데이터가 너무 동질적일 수 있어요 - 더 많은 반복 시도를 해보세요

  2. 분석이 조기 종료됨 - 중지 버튼을 클릭했는지 확인하세요 - 시스템 리소스를 확인하세요

  3. 출력 파싱 실패 - 로그 탭에서 원본 출력을 확인하세요 - 소프트웨어 업데이트가 필요할 수 있어요

분석 시간이 너무 오래 걸림

Parsimony의 경우:

  • 몇 초에서 몇 분 안에 완료되어야 해요

  • 멈춘 경우 Hold 매개변수를 줄이세요

Maximum Likelihood의 경우:

  • 몇 분에서 몇 시간 걸릴 수 있어요

  • 테스트를 위해 부트스트랩 반복 횟수를 줄이세요

  • “Fast” 알고리즘 옵션을 사용하세요

Bayesian의 경우:

  • 몇 시간에서 며칠 걸릴 것으로 예상돼요

  • 주기적으로 수렴을 확인하세요

  • 중지하고 재개할 수 있어요 (MrBayes에서 직접)

해결 방법:

  • 테스트를 위해 데이터셋 크기를 줄이세요

  • 더 빠른 컴퓨터를 사용하세요

  • 밤새 실행하세요

  • 대용량 데이터셋의 경우 클라우드 컴퓨팅을 고려하세요

UI 및 화면 표시 문제

창 레이아웃 손상

창 크기 및 위치 초기화:

  1. PhyloForester를 종료하세요

  2. 설정 파일을 삭제하세요: - Windows: C:\\Users\\<name>\\AppData\\Roaming\\PaleoBytes\\PhyloForester - macOS: ~/Library/Preferences/com.paleobytes.PhyloForester.plist - Linux: ~/.config/PaleoBytes/PhyloForester.conf

  3. PhyloForester를 재시작하세요

트리가 표시되지 않음

해결 방법:

  1. 트리 데이터가 존재하는지 확인하세요 (로그에서 확인)

  2. 목록에서 다른 트리를 시도하세요

  3. 트리를 Newick으로 내보내고 유효한지 확인하세요

  4. 애플리케이션을 재시작하세요

텍스트가 너무 작거나 큼

시스템 DPI 설정으로 조정하세요:

Windows:

설정 → 디스플레이 → 배율

macOS:

시스템 환경설정 → 디스플레이 → 해상도

Linux:

데스크톱 환경 설정

키보드 단축키가 작동하지 않음

확인 사항:

  1. 포커스가 올바른 창/위젯에 있는지

  2. OS 단축키와 충돌하지 않는지

  3. NumLock 상태 (넘패드 사용 시)

macOS:

Ctrl 단축키 대신 Cmd를 사용해야 할 수 있어요

데이터매트릭스 편집기 문제

셀을 편집할 수 없음

확인 사항:

  1. 데이터매트릭스가 편집 모드로 열려있는지 (읽기 전용이 아님)

  2. 셀이 선택되어 있는지 (한 번 클릭하여 선택)

  3. 뒤에 숨겨진 대화 상자가 없는지

실행 취소/다시 실행이 작동하지 않음

제한 사항:

  • 단일 편집 세션 내에서만 작동해요

  • 편집기를 닫으면 실행 취소 기록이 지워져요

  • 최대 실행 취소 스택 크기: 50개 작업

작동하지 않는 경우:

  • 저장하고 편집기를 다시 여세요

  • 애플리케이션을 재시작하세요

복사/붙여넣기가 작동하지 않음

확인 사항:

  1. 셀이 선택되어 있는지 (강조 표시되어야 함)

  2. 클립보드에 데이터가 있는지 (다른 곳에 붙여넣어 확인)

  3. 형식이 호환되는지 (앱 간 전송은 탭 구분)

해결책:

  • 대용량 데이터 전송은 내보내기/가져오기를 사용하세요

  • 외부 텍스트 편집기를 통해 복사하세요

성능 문제

애플리케이션이 느림

원인 및 해결 방법:

  1. 대용량 데이터베이스 - 오래된 프로젝트를 보관하세요 - 여러 데이터베이스로 분할하세요

  2. 분석에 트리가 많음 - 저장되는 트리 수를 제한하세요 (Hold 매개변수) - 오래된 분석을 삭제하세요

  3. RAM 부족 - 다른 애플리케이션을 종료하세요 - 하드웨어를 업그레이드하세요

  4. 느린 디스크 - 데이터베이스를 SSD로 이동하세요 - 디스크 조각 모음 (Windows)

트리 렌더링이 느림

큰 트리의 경우 (>100 분류군):

  • 일시적으로 형질 매핑을 비활성화하세요

  • Newick으로 내보내고 전문 뷰어에서 보세요

  • 모든 트리 대신 요약 트리(합의 트리)를 사용하세요

오류 메시지

“Permission Denied”

원인: 파일 시스템 권한 부족

해결 방법:

  1. 상승된 권한으로 PhyloForester를 실행하세요

  2. 쓰기 권한이 있는 폴더로 데이터베이스를 이동하세요

  3. 파일이 다른 프로그램에서 열려있지 않은지 확인하세요

“Out of Memory”

원인: 작업을 수행하기에 RAM이 부족함

해결 방법:

  1. 다른 애플리케이션을 종료하세요

  2. 데이터셋 크기를 줄이세요

  3. 가상 메모리/스왑을 늘리세요

  4. 64비트 버전을 사용하세요 (사용 가능한 경우)

“Database Locked”

원인: 다른 프로세스가 데이터베이스에 접근 중

해결 방법:

  1. 모든 PhyloForester 인스턴스를 종료하세요

  2. 좀비 프로세스를 종료하세요

  3. 컴퓨터를 재시작하세요

  4. 데이터베이스를 새 위치로 복사하세요

“Invalid Datamatrix”

원인: 데이터 형식 문제

해결 방법:

  1. 확인 사항: - 일관되지 않은 행 길이 - 유효하지 않은 문자 - 누락된 분류군/형질 이름

  2. 원본 파일에서 다시 가져오세요

  3. 데이터매트릭스를 수동으로 다시 생성하세요

버그 보고

지속적인 문제가 발생하는 경우:

  1. 문제가 이미 보고되었는지 확인하세요: https://github.com/jikhanjung/PhyloForester/issues

  2. 다음 정보와 함께 새 이슈를 생성하세요: - PhyloForester 버전 (도움말 → 정보) - 운영 체제 및 버전 - 재현 단계 - 오류 메시지 (정확한 텍스트) - 로그 파일 (가능한 경우) - 스크린샷

로그 위치:

  • Windows: C:\\Users\\<name>\\AppData\\Local\\PaleoBytes\\PhyloForester\\Logs

  • macOS/Linux: ~/.local/share/PaleoBytes/PhyloForester/Logs

도움 받기

도움을 요청할 때 다음 정보를 포함하세요:

  • 무엇을 하려고 했는지

  • 어떤 일이 일어날 것으로 예상했는지

  • 실제로 어떤 일이 일어났는지

  • 오류 메시지

  • PhyloForester 버전

  • 운영 체제

다음 단계

  • 일반적인 사용법은 :doc:`user_guide`를 참조하세요

  • 분석 관련 도움말은 :doc:`analysis_guide`를 참조하세요

  • 고급 문제 해결은 :doc:`developer_guide`를 참조하세요