1.1 한눈에 보기#

쿡북의 어떤 챕터에서 어떤 파일을 어떤 함수로 다루는지, 전체 그림을 먼저 잡고 들어갑니다. 모든 후속 챕터의 코드가 이 두 트리 안에서 움직입니다.

입력 파일과 사용자 함수#

입력 파일과 입력 개체#

엔진은 두 클래스의 개체 만 받습니다 — Basis (산출기초 = 가정) 와 ModelPoints. measure(mp, basis) 호출의 두 인자가 바로 이 개체들. 사용자가 다루는 입력 파일들 은 reader 함수를 거쳐 이 두 개체로 모입니다. Basis 는 개별 가정 (사망률·해지율·할인율 …) 을 묶은 산출기초이고, ModelPoints 는 평가 대상 계약들입니다:

Basis 클래스 (산출기초) — basis = fcf.read_basis(...) 가 한 입력 파일 (basis.xlsx, multi-sheet 워크북) 을 읽어 산출기초 개체를 만듭니다.
ModelPoints 클래스 — mp = fcf.read_model_points(...) 가 세 입력 파일 (policies.csv / coverages.csv / calculation_methods.csv) 을 읽어 한 개체로 합칩니다.

Basis 클래스 — 한 입력 파일에서 만드는 개체#

Basis (basis = fcf.read_basis(...))
└── basis.xlsx                ── 산출기초 (multi-sheet workbook)
    ├── segments              · (product, channel) → 어느 테이블 쓸지 (product_name / channel_name 라벨 컬럼을 둘 수는 있으나 엔진은 무시)
    ├── mortality_tables      · table_id × sex × age → 사망률
    ├── lapse_tables          · table_id × duration → 해지율
    ├── discount_tables       · table_id × year → 할인율
    ├── expense_tables        · table_id → 사업비 행 (acquisition / maintenance / ...)
    └── coverages             · 담보 코드 → 어느 위험률 테이블을 쓸지

ModelPoints 클래스 — 세 입력 파일에서 만드는 개체#

ModelPoints (mp = fcf.read_model_points(...))
├── policies.csv              ── 보유 계약 (한 줄 = 한 계약, 가입 시점 영구 spec)
│   ├── mp_id                 · 계약 식별자 (다른 파일과 join 키)
│   ├── product          · 어느 segment 가정을 쓸지 (basis 의 segments 와 맞물림)
│   ├── channel          · 채널
│   ├── issue_age             · 가입연령
│   ├── sex                   · 0 = 남, 1 = 여
│   ├── term_months           · 보험기간 (개월)
│   ├── premium_term_months   · 보험료 납입기간 (개월)
│   ├── issue_date            · 가입일 (선택; 연도 cohort 그룹화에 사용)
│   └── count                 · 이 줄이 대표하는 계약 수 (없으면 1)
│
├── coverages.csv             ── 담보 가입금액 (한 줄 = 한 (계약, 담보))
│   ├── mp_id                 · 담보가 붙는 계약의 식별자 (policies.csv 의 mp_id 와 join)
│   ├── coverage         · 담보 코드 (calculation_methods 의 코드와 맞물림)
│   ├── amount                · 가입금액 (보험금)
│   ├── premium               · 월 보험료 (선택)
│   ├── waiting               · 면책기간 개월수 (선택)
│   ├── reduction_end         · 감액기간 종료 개월수 (선택)
│   └── reduction_factor      · 감액기간 중 지급률 (선택, 0..1)
│
└── calculation_methods.csv      ── 담보별 산출방식 (담보 코드 → 산출방식)
    ├── coverage         · 담보 코드 (DEATH, CANCER, INPATIENT ...)
    ├── coverage_name         · 사람 친화 라벨 (선택)
    └── calculation_method       · DEATH / MORBIDITY / DIAGNOSIS / ANNUITY / MATURITY

결산 모드 (보유계약 평가) 에서는 policies.csv 가 분기말 상태 컬럼 네 개를 더 갖는 inforce_2026Q1.csv 같은 한 파일로 들어옵니다 — elapsed_months / count (잔존) / prior_csm (직전 분기 CSM) / lock_in_rate (가입 시점의 할인율). reader 도 mp, state = fcf.read_inforce_policies(...) 로 바뀌어 두 개체를 돌려줍니다.

사용자 함수#

fastcashflow 사용자 API
├── 샘플 파일 폴더에 생성 (한 번만, 자기 파일이 있으면 생략)
│   ├── fcf.samples.export(dir, template="gmm")           ── basis.xlsx + policies/coverages/calculation_methods (+inforce)
│   ├── fcf.samples.export(dir, template="vfa")           ── 변액(VFA) 세트 (basis.xlsx + policies)
│   └── fcf.samples.templates()                           ── 사용 가능한 template 목록
│
├── 파일 읽어 들이기
│   ├── fcf.read_basis(path)                              ── basis dict 반환
│   ├── fcf.read_model_points(path, coverages=, ...)      ── 신계약 평가용
│   └── fcf.read_inforce_policies(path, coverages=, ...)  ── 결산 1-파일 reader
│
├── 평가
│   ├── fcf.gmm.measure(mp, basis)                        ── 신계약, 시간 trajectory 전체
│   ├── fcf.gmm.measure(mp, basis, full=False)            ── 시점 0 headline 4 숫자 (빠름); basis 가 dict 면 세그먼트 라우팅
│   └── fcf.gmm.measure_inforce(mp, basis, state, full=)  ── 결산(보유계약) 측정; full=False 면 headline 만
│
├── 결과 저장
│   ├── fcf.write_measurement(val, path)                  ── 결과 한 파일에 저장
│   └── fcf.gmm.measure_stream(policies, out_dir, basis, coverages=...)  ── 메모리 초과 portfolio 스트리밍
│
├── 변동분해 (분기간 비교)
│   ├── fcf.roll_forward(m, period_months=...)            ── 분기 사이 변동 분해
│   └── fcf.reconcile(movements)                          ── 분해 결과를 항별로 합산
│
└── 검증 / 시각화
    ├── fcf.gmm.trace(mp_index, mp, basis)                   ── 한 계약의 BEL 계산 ASCII 트리
    ├── fcf.gmm.trace_bel_step(mp_index, mp, basis, ...)     ── 월별 BEL 식 전개
    ├── fcf.gmm.trace_csm_step(mp_index, mp, basis, ...)     ── 월별 CSM 식 전개
    └── fcf.plot_liability(m) / plot_cashflows(m) / plot_csm_runoff(m) ...

자세한 결산 모드 워크플로는 튜토리얼 11장 참조.

코드에서 reader 가 도는 순서가 그대로입니다 — read_basis 가 먼저 (engine 가정), 그 다음 read_model_points 가 policies / coverages / calculation_methods 셋을 읽어 한 ModelPoints 개체로 묶습니다.

어느 챕터에서 어디까지 쓰나#

챕터	사용하는 자리
담보와 산출방식 매칭	`calculation_methods.csv` 의 자리. 다섯 산출방식의 의미.
보장 청구 메커니즘	DEATH / MORBIDITY / DIAGNOSIS 의 kernel 알고리즘.
정기보험	`samples.export` → `read_*` → `measure` → `print`
검증 패턴	`gmm.trace` / `gmm.trace_bel_step` / `gmm.trace_csm_step` / `gmm.trace_diff`
튜토리얼 11장	파일 입출력의 자세한 schema 와 결산 워크플로

각 챕터는 이 그림의 일부만 다룹니다. 챕터를 읽다 모르는 함수 / 파일이 나오면 위 두 트리에서 어디에 있는지 한 번 확인.

파일 구조가 처음이면 — `samples.export` 로 실물 보기#

샘플 파일을 떨어뜨려 컬럼을 직접 확인하세요

자기 데이터를 fastcashflow 형식으로 맞추기 전에, 어떤 컬럼이 어떤 순서로 들어가는지 실물로 보는 게 가장 빠릅니다. 패키지가 각 입력 파일의 작동하는 예시 한 세트를 디스크에 써 주는 samples.export 를 제공합니다:

import fastcashflow as fcf

fcf.samples.export("samples", template="gmm", quiet=True)   # basis.xlsx + policies / coverages / calculation_methods (+ inforce)

써진 파일을 Excel / 텍스트 편집기로 열어 컬럼 이름과 한두 행의 값만 훑어보면, 후속 챕터의 read_* 가 무엇을 기대하는지 바로 감이 옵니다. .csv 외에 .xlsx / .parquet / .feather 로도 써집니다 (확장자로 결정).