flydnet 0.1.0__py3-none-any.whl

flydnet/__init__.py

@@ -0,0 +1,24 @@
+"""flydnet — 초파리 커넥톰을 배선으로 쓰는 스파이킹 신경망 층
+
+    import flydnet as fd
+    mb = fd.Circuit.from_flywire()                       # 버섯체: PN → KC → MBON (+APL)
+    enc = fd.RateEncoder(784, len(mb.groups["PN"]))      # 텐서 → PN 발화율
+    layer = fd.ConnectomeLayer(mb, inputs="PN", outputs="KC")
+    feats = layer(enc(images))                           # (B, n_KC) 발화율 → 리드아웃 학습
+
+    # 역전파 학습: 배선 고정, 연결 세기 학습 (대리 기울기)
+    layer = fd.ConnectomeLayer(mb, "PN", "KC", dt=0.5, t_ms=50, input_mode="regular", trainable=True)
+    model = torch.nn.Sequential(enc, layer, torch.nn.Linear(layer.n_out, 10))
+"""
+from . import data
+from .data import data_dir, set_data_dir, download, data_status
+from .circuit import Circuit, MUSHROOM_BODY
+from .encoders import RateEncoder, GlomerularEncoder
+from .layers import ConnectomeLayer, SpikeFn, DEFAULT_PARAMS
+from .readout import extract, train_linear
+from .plasticity import DopamineReadout, AssocReadout
+from .datasets import synthetic_odors, door_odors, biconditional_mixtures
+from .visual import (visual_circuit, column_map, drifting_grating, direction_offsets,
+                     VISUAL_SYSTEM, PHOTORECEPTORS, COLUMNAR, LPTC, MOTION_PATHWAY)
+
+__version__ = "0.1.0"

flydnet/__main__.py

@@ -0,0 +1,28 @@
+"""명령줄:  python -m flydnet [status | download [flywire|door ...]]
+
+  python -m flydnet                    # 데이터 상태 (어디서 무엇을 찾았는지)
+  python -m flydnet download           # FlyWire v783 + DoOR 데이터 받기 (없는 파일만, 약 130 MB)
+  python -m flydnet download flywire   # 한 묶음만
+"""
+import sys
+
+from . import __version__
+from .data import data_status, download
+
+
+def main(argv=None):
+    argv = list(sys.argv[1:] if argv is None else argv)
+    cmd = argv.pop(0) if argv else "status"
+    if cmd == "status":
+        print(f"flydnet {__version__}")
+        data_status()
+    elif cmd == "download":
+        download(argv or ("flywire", "door"))
+    else:
+        print(__doc__)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

flydnet/circuit.py

@@ -0,0 +1,234 @@
+"""FlyWire 커넥톰에서 뉴런 묶음(회로)을 잘라내 신경망 층의 '배선'으로 쓰는 Circuit"""
+from __future__ import annotations
+
+from pathlib import Path
+
+import numpy as np
+import pandas as pd
+
+# 이름 → (주석 열, 값 또는 값 목록). 주석 열: super_class, cell_class, cell_sub_class, cell_type
+# 버섯체 기본 회로: 투사 뉴런 → Kenyon 세포 → MBON, APL이 전체를 억제
+MUSHROOM_BODY = {
+    "PN":   ("cell_class", "ALPN"),
+    "KC":   ("cell_class", "Kenyon_Cell"),
+    "APL":  ("cell_type", "APL"),
+    "MBON": ("cell_class", "MBON"),
+}
+
+
+def _repair(pre: np.ndarray, post: np.ndarray, N: int, rng, max_iter: int = 200) -> np.ndarray:
+    """섞은 뒤 생긴 중복 연결(같은 pre→post 두 번)과 자기 연결(pre == post)을 없앰.
+    문제 연결의 post를 무작위 다른 연결과 맞바꿈 → 뉴런별 연결 수는 그대로 유지.
+    (중복을 그냥 두면 합쳐져서 무작위 회로의 뉴런이 실제보다 적은 입력을 받게 됨)"""
+    post = post.copy()
+    for _ in range(max_iter):
+        bad = pd.Series(pre * N + post).duplicated().values | (pre == post)
+        if not bad.any():
+            return post
+        for i, j in zip(np.nonzero(bad)[0], rng.integers(0, len(post), bad.sum())):
+            post[i], post[j] = post[j], post[i]          # 하나씩 (한꺼번에 하면 같은 j가 겹칠 때 값이 사라짐)
+    raise RuntimeError(f"중복 연결을 {max_iter}번 안에 없애지 못함 ({bad.sum()}개 남음)")
+
+
+class Circuit:
+    """뉴런 N개와 부호 있는 시냅스 목록 (pre → post, weight = ±시냅스 수)
+
+    groups: 이름 → 이 회로 안에서의 뉴런 번호 배열 (예: groups["KC"])
+    meta:   뉴런별 주석 (cell_type, cell_sub_class 등), 행 순서 = 회로 번호
+    pos:    뉴런별 위치 (N, 3) nm (FlyWire 주석의 대표 점), 없으면 None
+    """
+
+    def __init__(self, root_ids, groups: dict[str, np.ndarray], pre, post, weight, name="circuit",
+                 meta: pd.DataFrame | None = None, pos=None):
+        self.root_ids = np.asarray(root_ids, dtype=np.int64)
+        self.groups = {k: np.asarray(v, dtype=np.int64) for k, v in groups.items()}
+        self.pre = np.asarray(pre, dtype=np.int64)
+        self.post = np.asarray(post, dtype=np.int64)
+        self.weight = np.asarray(weight, dtype=np.float32)
+        self.name = name
+        self.meta = meta.reset_index(drop=True) if meta is not None else None
+        self.pos = np.asarray(pos, dtype=np.float32) if pos is not None else None
+
+    @property
+    def N(self) -> int:
+        return len(self.root_ids)
+
+    @property
+    def n_edges(self) -> int:
+        return len(self.pre)
+
+    def group_of(self) -> np.ndarray:
+        """뉴런별 그룹 이름 (그룹이 겹치지 않는다고 가정)"""
+        g = np.empty(self.N, dtype=object)
+        for k, v in self.groups.items():
+            g[v] = k
+        return g
+
+    @classmethod
+    def from_flywire(cls, groups: dict = MUSHROOM_BODY, side: str | None = "right",
+                     data_dir: str | Path | None = None, group_by: str | None = None, annotations: str = "flywire_annotations.tsv",
+                     connectivity: str = "Connectivity_783.parquet",
+                     completeness: str = "Completeness_783.csv") -> "Circuit":
+        """주석으로 고른 뉴런들 사이의 연결만 남긴 회로 (induced subgraph)
+        group_by: 주석 열 이름 (예: "cell_type")이면 각 그룹을 그 값마다 다시 나눔 → 그룹 이름 = 값
+                  (값이 없는 뉴런은 "<그룹 이름>?"). 무작위 대조군(shuffled)도 이 단위로 섞임
+        data_dir: None이면 flydnet.data_dir("flywire") (환경변수 → ~/.flydnet/config.json → ~/.flydnet/data)"""
+        from .data import require
+        d = require("flywire", data_dir)
+        all_ids = pd.read_csv(d / completeness, index_col=0).index.values.astype(np.int64)
+        ann = pd.read_csv(d / annotations, sep="\t", low_memory=False,
+                          usecols=["root_id", "super_class", "cell_class", "cell_sub_class", "cell_type", "side",
+                                   "pos_x", "pos_y", "pos_z"])
+        ann = ann[ann.root_id.isin(all_ids)]
+        if side:
+            ann = ann[ann.side == side]
+
+        picked, gidx = [], {}
+        for name, (col, val) in groups.items():
+            vals = [val] if isinstance(val, str) else list(val)
+            sel = ann[ann[col].isin(vals)]
+            parts = sel.groupby(sel[group_by].fillna(f"{name}?"), sort=True) if group_by else [(name, sel)]
+            for sub, s in parts:
+                if sub in gidx:
+                    raise ValueError(f"그룹 이름이 겹침: {sub}")
+                gidx[sub] = np.arange(len(picked), len(picked) + len(s))
+                picked.extend(s.root_id.values)
+        ids = np.array(picked, dtype=np.int64)
+        if len(np.unique(ids)) != len(ids):
+            raise ValueError("그룹끼리 뉴런이 겹침")
+
+        # 전체 뇌 번호 → 회로 번호
+        glob = pd.Series(np.arange(len(all_ids)), index=all_ids)[ids].values
+        local = np.full(len(all_ids), -1, np.int64); local[glob] = np.arange(len(ids))
+
+        df = pd.read_parquet(d / connectivity, columns=["Presynaptic_Index", "Postsynaptic_Index",
+                                                         "Connectivity", "Excitatory"])
+        pre, post = local[df.Presynaptic_Index.values], local[df.Postsynaptic_Index.values]
+        keep = (pre >= 0) & (post >= 0)
+        w = (df.Connectivity.values * df.Excitatory.values)[keep]
+        a = ann.set_index("root_id").loc[ids]
+        meta = a[["super_class", "cell_class", "cell_sub_class", "cell_type"]].reset_index()
+        return cls(ids, gidx, pre[keep], post[keep], w, name=f"FlyWire {'/'.join(groups)} ({side or 'both'})",
+                   meta=meta, pos=a[["pos_x", "pos_y", "pos_z"]].values)
+
+    def shuffled(self, seed: int = 0, pairs=None, exclude=None, local=None, merge=None) -> "Circuit":
+        """무작위 배선 대조군: (보내는 그룹, 받는 그룹) 쌍마다 받는 뉴런을 섞음.
+        그룹 간 연결 수·시냅스 수·뉴런별 입출력 개수는 그대로, '누가 누구에게'만 무작위.
+
+        pairs:   섞을 쌍만 지정 (예: ["PN>KC"]). None이면 전부
+        exclude: 섞지 않을 쌍 (예: ["PN>KC", "KC>KC"])
+        local:   (xy, radius) 이면 받는 뉴런 위치 xy (N, 2)를 radius 크기 칸으로 나눠 같은 칸 안에서만 섞음
+                 → 시야 위치 대응(retinotopy)은 유지, 그 안의 미세 배선(누가 정확히 누구에게)만 무작위.
+                 위치가 NaN인 뉴런은 한 칸으로 묶음
+        merge:   {그룹: 별칭} 섞을 때 같은 별칭 그룹들을 하나로 봄 (예: T4a~d → "T4").
+                 받는 뉴런이 원래 다른 아형으로 가던 연결도 받게 됨 → 아형별 배선 차이(방향 구조)가 사라짐.
+                 pairs/exclude는 별칭이 아닌 원래 그룹 이름 기준
+        """
+        rng = np.random.default_rng(seed)
+        g = self.group_of()
+        post = self.post.copy()
+        key = pd.Series(g[self.pre] + ">" + g[self.post])
+        if pairs is not None and (unknown := set(pairs) - set(key.unique())):
+            raise ValueError(f"회로에 없는 연결 쌍: {sorted(unknown)}")
+        pair_of = key.values
+        if merge:
+            ga = np.array([merge.get(x, x) for x in g], dtype=object)
+            key = pd.Series(ga[self.pre] + ">" + ga[self.post])
+        if local is not None:
+            xy, radius = local
+            b = np.floor(np.asarray(xy)[self.post] / radius)
+            b = np.where(np.isnan(b).any(1, keepdims=True), np.inf, b)
+            key = key + "|" + pd.Series(b[:, 0]).astype(str) + "," + pd.Series(b[:, 1]).astype(str)
+        stuck = []
+        for k, idx in key.groupby(key).groups.items():
+            idx = np.asarray(idx)
+            if pairs is not None or exclude is not None:
+                pk = pair_of[idx]
+                sel = np.ones(len(idx), bool)
+                if pairs is not None:
+                    sel &= np.isin(pk, list(pairs))
+                if exclude is not None:
+                    sel &= ~np.isin(pk, list(exclude))
+                idx = idx[sel]
+                if len(idx) == 0:
+                    continue
+            try:
+                post[idx] = _repair(self.pre[idx], post[idx][rng.permutation(len(idx))], self.N, rng)
+            except RuntimeError:                                 # 뉴런 몇 개뿐인 쌍은 중복 없이 섞을 수 없을 때가 있음
+                stuck.append((k, len(idx)))
+        if stuck:
+            import warnings
+            warnings.warn(f"중복 없이 섞을 수 없어 원래 배선으로 둔 연결 쌍 {len(stuck)}개 "
+                          f"(연결 {sum(n for _, n in stuck):,}개 / 전체 {self.n_edges:,}개): "
+                          f"{', '.join(k for k, _ in stuck[:5])}{' …' if len(stuck) > 5 else ''}")
+        what = "" if pairs is None and exclude is None else \
+            f" {'+'.join(pairs) if pairs is not None else 'all'}{' -' + '-'.join(exclude) if exclude else ''}"
+        if local is not None:
+            what += f" local r={local[1]:g}"
+        if merge:
+            what += f" merge {'+'.join(sorted(set(merge.values())))}"
+        return Circuit(self.root_ids, self.groups, self.pre, post, self.weight,
+                       name=f"{self.name} [shuffled{what}]", meta=self.meta, pos=self.pos)
+
+    def subset(self, groups) -> "Circuit":
+        """지정한 그룹들의 뉴런만 남긴 회로 (그 사이 연결만)"""
+        groups = [g for g in groups if g in self.groups]
+        keep = np.concatenate([self.groups[g] for g in groups])
+        new = np.full(self.N, -1, np.int64); new[keep] = np.arange(len(keep))
+        m = (new[self.pre] >= 0) & (new[self.post] >= 0)
+        gidx, o = {}, 0
+        for g in groups:
+            gidx[g] = np.arange(o, o + len(self.groups[g])); o += len(self.groups[g])
+        return Circuit(self.root_ids[keep], gidx, new[self.pre[m]], new[self.post[m]], self.weight[m],
+                       name=f"{self.name} [그룹 {len(groups)}개]",
+                       meta=self.meta.iloc[keep] if self.meta is not None else None,
+                       pos=self.pos[keep] if self.pos is not None else None)
+
+    def normalized(self) -> "Circuit":
+        """받는 뉴런마다 입력 시냅스 수 합(|weight|)이 1이 되도록 나눈 회로.
+        입력 비율(누가 얼마나 주는지)은 그대로, 입력이 많은 뉴런과 적은 뉴런의 총입력 크기만 맞춤"""
+        tot = np.bincount(self.post, weights=np.abs(self.weight), minlength=self.N)
+        w = (self.weight / tot[self.post]).astype(np.float32)
+        return Circuit(self.root_ids, self.groups, self.pre, self.post, w, name=f"{self.name} [정규화]",
+                       meta=self.meta, pos=self.pos)
+
+    def with_sign(self, pre_groups, sign: int) -> "Circuit":
+        """pre_groups 뉴런이 보내는 연결을 모두 흥분(+1) 또는 억제(-1)로 바꾼 회로.
+        예: 광수용체의 히스타민은 받는 뉴런을 억제하지만 신경전달물질 예측에는 흥분으로 잡힘"""
+        if sign not in (1, -1):
+            raise ValueError("sign은 1 또는 -1")
+        pre_groups = [pre_groups] if isinstance(pre_groups, str) else list(pre_groups)
+        m = np.isin(self.pre, np.concatenate([self.groups[g] for g in pre_groups]))
+        w = self.weight.copy(); w[m] = sign * np.abs(w[m])
+        return Circuit(self.root_ids, self.groups, self.pre, self.post, w,
+                       name=f"{self.name} [{'+'.join(pre_groups)} {'흥분' if sign > 0 else '억제'}]",
+                       meta=self.meta, pos=self.pos)
+
+    def summary(self) -> pd.DataFrame:
+        """그룹 간 연결 요약 (시냅스 수, 흥분/억제)"""
+        g = self.group_of()
+        df = pd.DataFrame({"pre": g[self.pre], "post": g[self.post], "w": self.weight})
+        return df.groupby(["pre", "post"]).agg(edges=("w", "size"), exc_syn=("w", lambda x: x[x > 0].sum()),
+                                               inh_syn=("w", lambda x: -x[x < 0].sum()))
+
+    def __repr__(self):
+        gs = ", ".join(f"{k} {len(v)}" for k, v in self.groups.items())
+        return f"<Circuit '{self.name}' | {self.N:,} neurons ({gs}) | {self.n_edges:,} edges>"
+
+    # 저장: 텐서·문자열·리스트만 써서 torch.load(weights_only=True)로 안전하게 읽힘
+    def to_dict(self) -> dict:
+        import torch
+        meta = None
+        if self.meta is not None:
+            meta = {c: [None if pd.isna(v) else str(v) for v in self.meta[c]] for c in self.meta.columns}
+        return dict(root_ids=torch.from_numpy(self.root_ids), pre=torch.from_numpy(self.pre),
+                    post=torch.from_numpy(self.post), weight=torch.from_numpy(self.weight),
+                    groups={k: torch.from_numpy(v) for k, v in self.groups.items()}, name=self.name, meta=meta,
+                    pos=torch.from_numpy(self.pos) if self.pos is not None else None)
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "Circuit":
+        meta = pd.DataFrame(d["meta"]) if d.get("meta") is not None else None
+        return cls(d["root_ids"].numpy(), {k: v.numpy() for k, v in d["groups"].items()}, d["pre"].numpy(),
+                   d["post"].numpy(), d["weight"].numpy(), name=d["name"], meta=meta,
+                   pos=d["pos"].numpy() if d.get("pos") is not None else None)

flydnet/data.py

@@ -0,0 +1,145 @@
+"""데이터 위치 설정과 다운로드
+
+데이터 묶음 두 가지
+  flywire : FlyWire v783 연결·뉴런 목록 (Shiu et al. 2024 모델 저장소) + 세포 유형 주석 (Schlegel et al. 2024)
+  door    : DoOR 2.0 냄새 반응 (Münch & Galizia 2016, CC BY-SA 4.0)
+
+위치를 찾는 순서 (묶음마다)
+  1. 함수에 직접 준 경로
+  2. 환경변수  FLYDNET_FLYWIRE / FLYDNET_DOOR  (FLYDNET_DATA도 flywire로 인정 — 이전 버전 호환)
+  3. 설정 파일 ~/.flydnet/config.json  ← fd.set_data_dir()로 저장
+  4. 기본값    ~/.flydnet/data/<묶음>
+
+    import flydnet as fd
+    fd.download()                                   # 없는 파일만 받음 (약 140 MB)
+    fd.set_data_dir(flywire=r"D:\\my\\flywire")      # 이미 받아 둔 곳을 쓰려면
+    fd.data_status()                                # 어디서 무엇을 찾았는지
+"""
+from __future__ import annotations
+
+import json
+import os
+import urllib.request
+from pathlib import Path
+
+CONFIG = Path.home() / ".flydnet" / "config.json"
+DEFAULT_ROOT = Path.home() / ".flydnet" / "data"
+
+# 파일 이름 → (URL, 바이트 크기). 크기로 다운로드가 온전한지 확인
+SOURCES = {
+    "flywire": {
+        "Connectivity_783.parquet":
+            ("https://github.com/philshiu/Drosophila_brain_model/raw/main/Connectivity_783.parquet", 100804642),
+        "Completeness_783.csv":
+            ("https://github.com/philshiu/Drosophila_brain_model/raw/main/Completeness_783.csv", 3327347),
+        "flywire_annotations.tsv":
+            ("https://github.com/flyconnectome/flywire_annotations/raw/main/supplemental_files/"
+             "Supplemental_file1_neuron_annotations.tsv", 31720298),
+    },
+    "door": {
+        name: (f"https://raw.githubusercontent.com/ropensci/DoOR.data/master/data/{name}", None)
+        for name in ("door_response_matrix.csv", "door_mappings.csv", "odor.csv")
+    },
+}
+CITATIONS = {
+    "flywire": "FlyWire: Dorkenwald et al. 2024, Schlegel et al. 2024 (Nature); "
+               "연결 파일: Shiu et al. 2024 (Nature), github.com/philshiu/Drosophila_brain_model (MIT)",
+    "door": "DoOR 2.0: Münch & Galizia 2016 (Sci Rep 6:21841), github.com/ropensci/DoOR.data (CC BY-SA 4.0)",
+}
+_ENV = {"flywire": ("FLYDNET_FLYWIRE", "FLYDNET_DATA"), "door": ("FLYDNET_DOOR",)}
+
+
+def _config() -> dict:
+    try:
+        return json.loads(CONFIG.read_text(encoding="utf-8"))
+    except (FileNotFoundError, json.JSONDecodeError):
+        return {}
+
+
+def data_dir(kind: str = "flywire", path: str | Path | None = None) -> Path:
+    """묶음(kind)의 데이터 폴더. 파일이 실제로 있는지는 확인하지 않음 (require()가 확인)"""
+    if kind not in SOURCES:
+        raise ValueError(f"kind는 {list(SOURCES)} 중 하나")
+    if path is not None:
+        return Path(path)
+    for env in _ENV[kind]:
+        if os.environ.get(env):
+            return Path(os.environ[env])
+    if kind in _config():
+        return Path(_config()[kind])
+    return DEFAULT_ROOT / kind
+
+
+def set_data_dir(flywire: str | Path | None = None, door: str | Path | None = None):
+    """이 컴퓨터에서 쓸 데이터 위치를 ~/.flydnet/config.json에 저장 (None인 항목은 그대로)"""
+    cfg = _config()
+    for kind, p in (("flywire", flywire), ("door", door)):
+        if p is not None:
+            cfg[kind] = str(Path(p).resolve())
+    CONFIG.parent.mkdir(parents=True, exist_ok=True)
+    CONFIG.write_text(json.dumps(cfg, indent=2, ensure_ascii=False), encoding="utf-8")
+    return cfg
+
+
+def missing(kind: str = "flywire", path=None) -> list[str]:
+    d = data_dir(kind, path)
+    return [f for f in SOURCES[kind] if not (d / f).exists()]
+
+
+def require(kind: str = "flywire", path=None) -> Path:
+    """데이터 폴더를 돌려주되, 파일이 없으면 무엇을 하면 되는지 알려주는 오류"""
+    d = data_dir(kind, path)
+    lack = missing(kind, path)
+    if lack:
+        raise FileNotFoundError(
+            f"{kind} 데이터 파일이 없음: {lack}\n  찾은 위치: {d}\n"
+            f"  받기: flydnet.download('{kind}')  또는  python -m flydnet download {kind}\n"
+            f"  이미 있으면: flydnet.set_data_dir({kind}=r'경로') 또는 환경변수 {_ENV[kind][0]}")
+    return d
+
+
+def download(kinds=("flywire", "door"), path=None, overwrite: bool = False, quiet: bool = False) -> dict:
+    """없는 파일만 받음. 반환: {묶음: 폴더}"""
+    kinds = [kinds] if isinstance(kinds, str) else list(kinds)
+    out = {}
+    for kind in kinds:
+        d = data_dir(kind, path if len(kinds) == 1 else None)
+        d.mkdir(parents=True, exist_ok=True)
+        for name, (url, size) in SOURCES[kind].items():
+            f = d / name
+            if f.exists() and not overwrite and (size is None or f.stat().st_size == size):
+                if not quiet:
+                    print(f"  있음  {f}")
+                continue
+            tmp = f.with_suffix(f.suffix + ".part")
+            if not quiet:
+                print(f"  받는 중 {name} ← {url}", flush=True)
+            _fetch(url, tmp, quiet)
+            if size is not None and tmp.stat().st_size != size:
+                got = tmp.stat().st_size
+                tmp.unlink()
+                raise IOError(f"{name} 크기가 다름 (받은 {got:,} B, 기대 {size:,} B) — 다시 시도")
+            tmp.replace(f)
+        if not quiet:
+            print(f"[{kind}] {d}\n  출처: {CITATIONS[kind]}")
+        out[kind] = d
+    return out
+
+
+def _fetch(url: str, dest: Path, quiet: bool):
+    with urllib.request.urlopen(url, timeout=60) as r, open(dest, "wb") as f:
+        total = int(r.headers.get("Content-Length") or 0)
+        done, step = 0, max(total // 10, 1)
+        while chunk := r.read(1 << 20):
+            f.write(chunk)
+            done += len(chunk)
+            if not quiet and total and done // step != (done - len(chunk)) // step:
+                print(f"    {done / total * 100:3.0f}%", flush=True)
+
+
+def data_status() -> dict:
+    """묶음별 위치와 빠진 파일"""
+    st = {k: dict(dir=str(data_dir(k)), missing=missing(k)) for k in SOURCES}
+    for k, v in st.items():
+        print(f"{k:<8} {'준비됨' if not v['missing'] else '빠짐: ' + ', '.join(v['missing'])}  ({v['dir']})")
+    return st

flydnet/datasets.py

@@ -0,0 +1,93 @@
+"""시험용 데이터 생성"""
+import torch
+
+
+def synthetic_odors(n_classes: int, n_glomeruli: int, n_train: int, n_test: int, protos_per_class: int = 1,
+                    active_frac: float = 0.2, noise: float = 0.5, add_noise: float = 0.1, seed: int = 0):
+    """합성 냄새 분류 과제
+
+    냄새 원형: 사구체마다 active_frac 확률로 켜짐, 세기 U(0.2, 1)
+    클래스:   원형 protos_per_class개의 묶음 (예: '먹이' = 사과 냄새 또는 효모 냄새).
+              2개 이상이면 사구체 공간에서 선형 분리가 어려워짐 → 확장 층(KC)이 필요한 과제
+    샘플:     클래스의 원형 하나를 골라 × exp(N(0, noise)) (사구체별 세기 흔들림) + |N(0, add_noise)| (배경)
+    반환: (Xtr, ytr, Xte, yte), X는 (n, n_glomeruli), 클래스당 n_train / n_test 개
+    """
+    g = torch.Generator().manual_seed(seed)
+    P = n_classes * protos_per_class
+    on = torch.rand(P, n_glomeruli, generator=g) < active_frac
+    protos = on * (0.2 + 0.8 * torch.rand(P, n_glomeruli, generator=g))
+
+    def sample(n):
+        y = torch.arange(n_classes).repeat_interleave(n)
+        k = y * protos_per_class + torch.randint(0, protos_per_class, (len(y),), generator=g)
+        x = protos[k] * torch.exp(noise * torch.randn(len(y), n_glomeruli, generator=g))
+        x = x + (add_noise * torch.randn(len(y), n_glomeruli, generator=g)).abs()
+        return x, y
+
+    Xtr, ytr = sample(n_train)
+    Xte, yte = sample(n_test)
+    return Xtr, ytr, Xte, yte
+
+
+# 같은 계열인데 이름이 다른 DoOR 화학 계열
+_CLASS_ALIASES = {"arom": "aromatics", "terpenes": "terpene", "sulfid": "sulfide"}
+
+
+def door_odors(glomeruli, data_dir=None, min_measured: int = 20):
+    """DoOR 2.0 실제 냄새 반응 → 사구체 벡터 (Münch & Galizia 2016, CC BY-SA 4.0)
+
+    data_dir에 door_response_matrix.csv, door_mappings.csv, odor.csv 필요. None이면 flydnet.data_dir("door")
+    (없으면 flydnet.download("door"), 출처 https://github.com/ropensci/DoOR.data 의 data/ 폴더)
+
+    glomeruli: 사구체 이름 순서 (예: GlomerularEncoder.glomeruli)
+    반환 dict:
+      X        (n_odors, n_glomeruli) 반응 − 자발 발화(SFR), 0 아래는 0. 측정 안 된 칸도 0
+      measured (n_odors, n_glomeruli) 측정 여부
+      names, classes (화학 계열), inchikey
+    min_measured: 이만큼 이상의 사구체가 측정된 냄새만
+    """
+    import numpy as np
+    import pandas as pd
+    from .data import require
+
+    d = require("door", data_dir)
+    R = pd.read_csv(d / "door_response_matrix.csv", sep=";")
+    M = pd.read_csv(d / "door_mappings.csv", sep=";")
+    O = pd.read_csv(d / "odor.csv", sep=";").drop_duplicates("InChIKey").set_index("InChIKey")
+    sfr = R.loc["SFR"]
+    R = R.drop(index="SFR")
+
+    col = {g: j for j, g in enumerate(glomeruli)}
+    X = np.zeros((len(R), len(glomeruli)), np.float32)
+    meas = np.zeros_like(X, dtype=bool)
+    for rec, glo in M[["receptor", "code"]].dropna().itertuples(index=False):
+        if rec in R.columns and glo in col:
+            v = R[rec].values
+            ok = ~np.isnan(v)
+            X[ok, col[glo]] = np.maximum(v[ok] - sfr[rec], 0)
+            meas[ok, col[glo]] = True
+
+    keep = meas.sum(1) >= min_measured
+    info = O.reindex(R.index[keep])
+    classes = info["Class"].fillna("other").replace(_CLASS_ALIASES).values
+    return dict(X=torch.tensor(X[keep]), measured=torch.tensor(meas[keep]), names=info["Name"].fillna("").values,
+                classes=classes, inchikey=R.index[keep].values)
+
+
+def biconditional_mixtures(X0, sets, n: int, noise: float = 0.5, add_noise: float = 0.05, sat: float = 0.3,
+                           generator=None):
+    """조건부 구별 과제 샘플: 냄새 4개 (a, b, c, d) 묶음마다 AB, CD → 1 (보상), AC, BD → 0 (무보상)
+
+    혼합물 = 포화(Σ 성분 × exp(N(0, noise)) + |N(0, add_noise)|), 포화(x) = x / (x + sat)
+    반환: (x, y, 묶음 번호), 묶음·혼합물마다 n개
+    """
+    xs, ys, ps = [], [], []
+    G = X0.shape[1]
+    for p, (a, b, c, d) in enumerate(sets):
+        for comp, label in (((a, b), 1), ((c, d), 1), ((a, c), 0), ((b, d), 0)):
+            base = sum(X0[k] * torch.exp(noise * torch.randn(n, G, generator=generator)) for k in comp)
+            x = base + (add_noise * torch.randn(n, G, generator=generator)).abs()
+            xs.append(x / (x + sat))
+            ys += [label] * n
+            ps += [p] * n
+    return torch.cat(xs), torch.tensor(ys), torch.tensor(ps)

flydnet/encoders.py

@@ -0,0 +1,71 @@
+"""텐서 → 입력 뉴런 발화율(Hz) 변환. '설탕 뉴런 150Hz 자극'을 일반 데이터로 확장한 것"""
+import numpy as np
+import torch
+import torch.nn as nn
+
+
+def _to_rates(x: torch.Tensor, max_rate: float) -> torch.Tensor:
+    """음수는 0, 샘플마다 최댓값 = max_rate (전체 세기가 달라도 같은 패턴이면 같은 발화율)"""
+    x = x.clamp_min(0)
+    return x / x.amax(1, keepdim=True).clamp_min(1e-8) * max_rate
+
+
+class RateEncoder(nn.Module):
+    """입력 특징 n_in개를 입력 뉴런 n_out개의 발화율로 바꿈
+
+    - n_in == n_out 이고 projection=None: 특징 하나 = 뉴런 하나
+    - 아니면 고정 무작위 희소 투영: 뉴런마다 특징 k개를 모아 받음 (사구체가 여러 수용체 입력을 모으듯)
+    출력은 샘플마다 최댓값이 max_rate가 되도록 정규화 (음수는 0)
+    """
+
+    def __init__(self, n_in: int, n_out: int, max_rate: float = 100.0, k: int = 20, seed: int = 0,
+                 projection: str | None = "random"):
+        super().__init__()
+        self.n_in, self.n_out, self.max_rate = n_in, n_out, max_rate
+        if projection is None:
+            if n_in != n_out:
+                raise ValueError("projection=None이면 n_in == n_out 이어야 함")
+            self.P = None
+        else:
+            g = torch.Generator().manual_seed(seed)
+            cols = torch.stack([torch.randperm(n_in, generator=g)[:k] for _ in range(n_out)])
+            P = torch.zeros(n_out, n_in)
+            P.scatter_(1, cols, 1.0 / k)
+            self.register_buffer("P", P)
+
+    def forward(self, x: torch.Tensor) -> torch.Tensor:
+        x = x.flatten(1).float()
+        if self.P is not None:
+            x = x @ self.P.T.to(x.device)
+        return _to_rates(x, self.max_rate)
+
+
+class GlomerularEncoder(nn.Module):
+    """냄새 = 사구체별 활성 벡터 (B, n_glomeruli) → 투사 뉴런(PN) 발화율 (B, n_PN)
+
+    실제 더듬이엽 구조를 따름: 같은 사구체의 단일 사구체형 PN들은 같은 발화율을 받음.
+    다중 사구체형 PN은 입력 0 (오른쪽 버섯체에서 PN→KC 시냅스의 96%가 단일 사구체형).
+    사구체 이름은 cell_type의 '_' 앞부분 (예: DM1_lPN → DM1)
+    """
+
+    def __init__(self, circuit, group: str = "PN", max_rate: float = 100.0):
+        super().__init__()
+        if circuit.meta is None:
+            raise ValueError("circuit.meta(세포 주석)가 필요함 — Circuit.from_flywire()로 만든 회로를 쓸 것")
+        m = circuit.meta.iloc[circuit.groups[group]]
+        uni = m.cell_sub_class.astype(str).eq("uniglomerular").values
+        glom = m.cell_type.astype(str).str.split("_").str[0].values
+        self.glomeruli = sorted(set(glom[uni]))
+        col = {gname: j for j, gname in enumerate(self.glomeruli)}
+        P = torch.zeros(len(m), len(self.glomeruli))
+        for i in np.nonzero(uni)[0]:
+            P[i, col[glom[i]]] = 1.0
+        self.register_buffer("P", P)
+        self.max_rate = max_rate
+
+    @property
+    def n_glomeruli(self) -> int:
+        return len(self.glomeruli)
+
+    def forward(self, odor: torch.Tensor) -> torch.Tensor:
+        return _to_rates(odor.float() @ self.P.T.to(odor.device), self.max_rate)