77 lines
3.0 KiB
Markdown
77 lines
3.0 KiB
Markdown
# perdalam-protean
|
|
|
|
Research code for **server-side prototype aggregation in PROTEAN** using class-specific
|
|
sample support, for rare attack detection under non-IID federated intrusion detection.
|
|
|
|
The planned study modifies only how the server combines local class prototypes. The
|
|
proposed support-weighted aggregation is:
|
|
|
|
```
|
|
Cbar_j(beta) = ( sum_{i in S_j} N_ij^beta C_ij ) / ( sum_{i in S_j} N_ij^beta )
|
|
```
|
|
|
|
with `S_j = { i | N_ij > 0 and C_ij exists }` and candidate
|
|
`beta in {0.0, 0.25, 0.5, 0.75, 1.0}`.
|
|
|
|
**Current checkpoint: baseline only.** The proposed beta-weighted aggregation and the
|
|
`equal_available` control are **not implemented** in this checkpoint; they are deferred to
|
|
the later beta/controls phase, which must not begin until the baseline is verified. See
|
|
`docs/handoff/SESSION_HANDOFF.md`.
|
|
|
|
## Immutable source
|
|
|
|
- `planningawal/PROTEAN_Revisi_Lurus.md` is the authoritative research specification and is
|
|
**read-only**. Do not edit, add, rename, move, or delete anything under `planningawal/`.
|
|
|
|
## External raw datasets (read-only, never copied into the repo)
|
|
|
|
- `~/datasets/X-IIoTID/X-IIoTID-dataset.csv`
|
|
- `~/datasets/5G-NIDD/5G-NIDD.csv`
|
|
|
|
Paths are configured in `configs/datasets/datasets.yaml` (with environment overrides) and are
|
|
never hardcoded in source. Generated artifacts go under `artifacts/`.
|
|
|
|
## Layout
|
|
|
|
```
|
|
docs/research/ spec interpretation, dataset inspection, implementation plan, protocol
|
|
docs/baseline/ PROTEAN baseline investigation + baseline implementation notes
|
|
docs/handoff/ session handoff (start here for a new session)
|
|
configs/ datasets, experiments, model
|
|
src/protean_research/ data, models, aggregation, federated, evaluation, utils (baseline)
|
|
scripts/ run_baseline.py, generate_partitions.py
|
|
tests/ focused unit + integration tests
|
|
artifacts/ results/ generated outputs (not source)
|
|
```
|
|
|
|
## Status
|
|
|
|
The minimum reproducible **baseline** is implemented and smoke-tested. No full-scale
|
|
training and no beta sweep have been run. The original PROTEAN baseline has **no public
|
|
official code**, so it is reproduced from the paper/thesis with explicitly documented
|
|
reproduction assumptions (`docs/baseline/BASELINE_IMPLEMENTATION.md`).
|
|
|
|
Read `docs/handoff/SESSION_HANDOFF.md` first, then
|
|
`planningawal/PROTEAN_Revisi_Lurus.md`.
|
|
|
|
## Quickstart
|
|
|
|
```bash
|
|
# inside the repo, with the project virtualenv (numpy, pandas, torch, pyyaml, pytest)
|
|
.venv/bin/python -m pytest -q
|
|
|
|
# baseline smoke test (writes only to ignored directories)
|
|
.venv/bin/python scripts/run_baseline.py --dataset xiiotid --alpha 0.5 --seed 0 \
|
|
--max-rows 3000 --sample-from 60000 --clients 4 --rounds 2 --local-epochs 1
|
|
|
|
# generate + verify all deterministic partition manifests (full data)
|
|
.venv/bin/python scripts/generate_partitions.py
|
|
```
|
|
|
|
The baseline aggregation is dependency-free and testable without pandas/torch:
|
|
|
|
```python
|
|
from protean_research.aggregation import aggregate_prototypes
|
|
aggregate_prototypes([[0.0, 2.0], [2.0, 0.0]]) # equal mean over the contributor set S_j
|
|
```
|