1. 문제 발견

Feature Engineering 관련 업무를 진행하다 22개의 주요 피쳐를 추출하는 pycatch22의 파이썬 패키지에서 잘못된 점을 발견했습니다. 

참고로, catch22(“Canonical Time-series CHaracteristics”)는 2019년 Lubba 외 연구진이 제안한, 시계열 데이터의 핵심 성질을 빠르고 직관적으로 추출할 수 있는 22가지 피쳐 집합을 추출하는 패키지입니다. 각 피처는 엔트로피, 자기상관, 스펙트럼 전력, 모티프 통계 등 시계열의 동적 거동을 대표하는 정보를 담고 있으며, 모두 C로 최적화되어 있어 계산 속도가 매우 빠릅니다. 이런 특징 덕분에 catch22는 시계열 분류나 클러스터링 같은 머신러닝 과제에서 효율적이면서도 해석 가능한 피처 엔지니어링 도구로 널리 활용되고 있습니다.

 

catch22의 피쳐 이름이 워낙 길어서 short_name도 같이 지원을 하고 있는데요. catch_22_all 이라는 함수를 통해 data에서 모든 피쳐값을 추출할 때 short_name도 같이 명시하게 할 수 있습니다. 

하지만 pycatch22 패키지의 catch22_all(data, short_names=True)를 호출을 했을 때, SP_Summaries_welch_rect_area_5_1 피처에 "centroid_freq"로 

SP_Summaries_welch_rect_centroid 피처에 "low_freq_power"로

잘못 매핑돼 있음을 발견하게 되었습니다.

 

별 거 아닐 수 있지만 short_name을 이용해 해당 패키지를 이용하는 사람이 있다면 값이 완전히 다르게 나타날 수 있기 때문에 수정이 필요해 보였습니다. 

그래서 처음으로 공개된 파이썬 오픈소스 라이브러리에 수정사항을 반영한 코드를 제안해봤습니다. 이번 포스팅에서는 실제로 버그를 찾아 고치고, 깃허브에 PR(Pull Request)을 올리기까지의 전체 과정을 단계별로 담았습니다.

아래 단계별 가이드를 따라 하시면, 포크 → 브랜치 생성 → 코드 수정 → 커밋 → 푸시 → PR 생성까지 오픈소스 기여의 전체 플로우를 한 번에 익히실 수 있습니다. 설명의 편의성을 위해 User의 GitHub 저장소는 your-username/catch22이고, 원본 저장소가 orig-owner/catch22라고 가정하겠습니다. 

 

2. 오픈소스 기여 과정

2.1 저장소 포크 (Fork) & 로컬 클론 (Clone)

1. GitHub에서 원본 저장소로 이동

2. 우측 상단 ‘Fork’ 버튼 클릭 → 내 계정(your-username/catch22)으로 복사 

3. 로컬에 Clone

# 1) 내 계정으로 포크된 저장소를 로컬로 클론
git clone <https://github.com/your-username/catch22.git>

cd catch22

 

4. 원본 저장소를 upstream으로 지정 : 원본 저장소의 변경내역을 쉽게 가져오기 위해 upstream 리모트를 추가합니다.

# 원본 저장소를 ‘upstream’이라는 이름으로 추가
git remote add upstream <https://github.com/orig-owner/catch22.git>

# 설정 확인 (origin: 내 fork, upstream: 원본)
git remote -v

 

5. 최신 커밋 동기화

# 메인 브랜치로 이동
git checkout main

# 원본 저장소의 최신 변경사항을 가져와서 내 로컬 main에 병합
git fetch upstream
git merge upstream/main

 

 

2.2 브랜치 생성

새로운 기능 추가 혹은 버그 픽스에 대한 내용을 담은 새로운 브랜치 생성

# 브랜치 이름은 ‘fix/short-names-mapping’ 같은 의미 있는 이름으로
git checkout -b fix/short-names-mapping

2.3 코드 수정

  1. 수정해야 하는 부분 수정 : catch22_all 함수 정의부에서 features_short 리스트의 두 항목을 스왑
  2. 로컬에서 유닛테스트 추가 또는 실행하여 정상 동작 확인
# 편집기 열고 수정
vim catch22_all.py

2.4 커밋 & 푸시 

1. 커밋 

커밋 메시지 규칙

  • <type>(<scope>): <short description>
  • type 예시: fix, feat, docs
  • scope 예시: 해당 모듈명(catch22)
# 변경된 파일 스테이징
git add catch22_all.py tests/test_catch22.py

# 커밋 작성
git commit -m "fix(catch22): correct short_names mapping for SP_Summaries features"

2. 내 Fork에 푸시 

git push origin fix/short-names-mapping

2.5 PR(Pull Request) 생성 

1. GitHub 내 your-username/catch22 페이지로 이동

2. “Compare & pull request” 버튼 클릭

3. PR 제목과 본문에 커밋 메세지 작성하기

**Description**  

**What’s Changed**  
- The `short_names` entries for `SP_Summaries_welch_rect_area_5_1` and `SP_Summaries_welch_rect_centroid` were swapped.  
- This patch swaps the entries at indices 15 and 20 in the `features_short` list to restore correct mapping.

**Why**  
When calling `catch22_all(..., short_names=True)`, the area and centroid features returned misleading labels, which could confuse downstream users and analyses.

**How**  
- In `catch22_all`, swap the two entries in `features_short` so that:  
  - `SP_Summaries_welch_rect_area_5_1` → `low_freq_power`  
  - `SP_Summaries_welch_rect_centroid` → `centroid_freq`  
- Added two unit tests to verify each mapping.

**Testing**  
```python
import pycatch22 as catch22

data = [0, 1, 2, 3, 4] * 20
out = catch22.catch22_all(data, short_names=True)

idx_area = out['names'].index('SP_Summaries_welch_rect_area_5_1')
assert out['short_names'][idx_area] == 'low_freq_power', "Area feature mapping is incorrect"

idx_cent = out['names'].index('SP_Summaries_welch_rect_centroid')
assert out['short_names'][idx_cent] == 'centroid_freq', "Centroid feature mapping is incorrect"

4. “Create pull request” 클릭

5. 원본 저장소에 Pull Requeats 확인 

 

3. 마치며

하루만에 리뷰어가 승인해 원본 저장소에 병합 완료!

사용이 활발한 패키지는 아니기 때문에 merge가 빠르게 이루어질까 했는데 하루도 걸리지 않아 병합이 완료되었습니다. 

 

작은 버그 하나가 사용자에게는 큰 불편을 안겨줄 수 있습니다. 거창하게 수식의 오류를 발견하거나 대대적인 최적화를 수행한 것은 아니지만, 이렇게 간단한 오류라도 사용하는 사람들이 불편함을 느낄 수 있지 않을까 생각하니 매우 뿌듯했습니다. 

 

실제로 제가 저 매핑이 잘못된 걸 모르고 값이 계속 잘못 나와 몇 시간을 고생했거든요... 

 

그래서 사소해 보여도 문제를 발견하면 바로 수정하는 것이 좋지 않을까 싶습니다. 이번 경험을 통해 오픈소스 기여하는 과정이 생각보다는 어렵지 않다는 걸 느꼈습니다. 앞으로도 문제가 있거나 개선이 필요하면 빠르게 PR을 시도해 볼 예정입니다. 

 

이번 포스팅 내용처럼 거창하지 않더라도 누구나 쉽게 오픈소스에 기여를 할 수 있습니다. 처음엔 낯설더라도, 직접 한 번 해 보면 크게 어렵지 않으니 차근차근 따라 해 보시면 좋을 것 같습니다. 개발자로서 오픈소스 라이브러리에 기여하는 경험은 코드에 대한 이해도를 높여 줄 뿐 아니라, 개발자로서 커뮤니티에 기여했다는 뿌듯함도 같이 줍니다. 

 

커밋메세지가 반영된 원본 저장소를 보니 매우 뿌듯하네요. 

 

 

데이by데이
데이by데이

티스토리툴바