2325 lines before lunch

The dissertation question is: can federated learning let Long-Term Care facilities train a shared predictive model without sharing any patient data? The answer is probably yes. The point of FedAcuity is to prove it formally enough to publish.

April 18 was the day the answer stopped being theoretical.

The architecture of a research project

The first commit is 28 files and 2325 lines. That might seem fast, but a research project’s architecture is mostly settled before the code starts — by the literature, by the problem structure, by the constraints that are non-negotiable from day one.

The problem structure here is the non-IID data distribution. Long-Term Care facilities split into three types: Memory Care (MC), Skilled Nursing Facilities (SNF), and Independent Living (IL). Their patient populations are clinically distinct. A global model trained on pooled data treats them as one population. The hypothesis is that care-type-aware clustering (Clustered FL) does better — for the same reason a specialist outperforms a generalist on their specialty.

config.yaml — 161 lines — is the single control point for the whole experiment. Everything else is deterministic from it. Ten simulated facilities (three MC, four SNF, three IL) each with 1095 rows of daily LTC records generated by CTGAN from the schema defined in schema.py.

Five strategies from the start

The evaluation requires baselines. The scaffold ships with all five: local (no federation — each facility trains on its own data only), centralised (theoretical oracle — all data pooled as if privacy didn’t exist), fedavg (standard Federated Averaging), fedprox (FedAvg with a proximal term to handle heterogeneous data), and clustered (Clustered FL, care-type-aware aggregation).

src/fl/simulation.py runs all of them. src/fl/client.py implements the Flower NumPyClient interface for XGBoost. src/fl/clustered_fl.py handles the care-type assignment and per-cluster aggregation.

The XAI module was also included from day one — src/xai/scorecard.py defines the audit scorecard structure. The plan is to run SHAP attribution post-training to explain why the model makes each prediction. That comes after the FL pipeline is verified.

The paper alongside the code

An IEEE JBHI paper scaffold went into the repo the same day. Title, author, abstract placeholder, references structure. The commitment is that the paper evolves with the code, not after it. Every major result goes into the paper the same session it’s produced.

The two artifacts — code and paper — are intended to be mutually consistent. The architecture diagram in docs/architecture.md is the same diagram that will appear in the paper.

---

Next: get the pipeline running end-to-end and producing numbers.