Ir para o conteúdo

Research

Esta pasta concentra especificações e códigos de experimentos de pesquisa executados sobre o framework federado.

Análises de literatura

  • Revisão e reescrita da apresentação de doutorado (revisao-apresentacao-doutorado.md): parecer científico, mudanças realizadas e pendências para a proposta e a defesa final.

  • Análise detalhada dos trabalhos relacionados da apresentação HDT-AF: síntese crítica dos 12 estudos/frameworks da tabela, avaliação da matriz e formulação da lacuna comparativa.

Regra de organização

Todo experimento deve ficar em:

research/experiments/{experiment_id}/
  specification.md
  manifest.yaml
  docker.env.example
  src/main/java/

O framework base permanece em modules/. Código específico de experimento, loaders de dataset, TrainingLocalModel, manifests e especificações científicas devem ficar em research/.

Os dados particionados por cliente nao ficam em research/. Ao executar um experimento, o framework cria:

data/{client_id}/{experiment_id}/dataset.csv
data/{client_id}/{experiment_id}/metadata.json

O client_id deve ser numerico e representa o cliente federado no contrato, no consentimento, nos topicos MQTT e na auditoria.

Para consumir esses dados, experimentos devem usar br.ufma.lsdi.localcdm.DataComponent. O componente recebe client_id e experiment_id, resolve a pasta local e fornece um DigitalTwinDataset para o loader do experimento.

Dataset de teste do contrato

Quando o pesquisador definir um dataset de teste no contrato (EvaluationDatasetSpec), esse dataset deve ficar fora de data/{client_id}/{experiment_id}. Ele é usado apenas por componentes autorizados de avaliação, como pesquisador, orquestrador, agregador ou avaliador central.

Regras:

  • nunca montar o dataset de teste em containers de cliente;
  • nunca publicar o dataset de teste por MQTT;
  • registrar uri, hash, metricName e distributionPolicy no contrato;
  • usar distributionPolicy=researcher_only_never_to_clients;
  • avaliar modelos locais e modelo global candidato com esse dataset quando o contrato solicitar.

Organização para Docker

Experimentos devem assumir que caminhos de runtime podem mudar dentro do container. Use br.ufma.lsdi.experiment.sdk.ExperimentRuntimePaths em vez de caminhos fixos.

Função Variável preferencial Padrão local Montagem Docker
Dados locais HDT_AF_DATA_ROOT data /app/data
Artefatos off-chain HDT_AF_ARTIFACT_ROOT target/artifacts /app/artifacts
Runtime temporário HDT_AF_RUNTIME_ROOT target/{runtime} /app/runtime
Pesquisa e datasets brutos HDT_AF_RESEARCH_ROOT research /app/research

Para clientes isolados em Docker, monte apenas:

target/classes -> /app/classes:ro
data/{client_id}/{experiment_id} -> /app/data/{client_id}/{experiment_id}:ro
target/artifacts -> /app/artifacts
target/docker-runtime/{experiment_id}/round-{round_id}/clients/{client_id} -> /app/runtime
target/docker-sim/{experiment_id}/round-{round_id}/clients/{client_id} -> /app/output
research/experiments/{experiment_id} -> /app/research/experiments/{experiment_id}:ro

Essa separação impede que um container de cliente visualize dados de outros clientes e deixa artefatos/resultados fora da pasta de código.

Experimentos disponíveis

Experimento Descrição
exp-har-smartphones-001 Human Activity Recognition Using Smartphones
exp-ecg5000-anomaly-001 Detecção federada de anomalias em ECG com autoencoder e privacidade diferencial
exp-mimic-v31-icu-mortality-001 Predição federada de mortalidade em UTI a partir de coorte tabular MIMIC v3.1
exp-ergonomic-risk-001 Classificação federada de risco ergonômico com janelas sintéticas publicadas pelo simulador MQTT
exp-dt-federated-001 Experimento sintético de gêmeos digitais industriais

Execução

O script scripts/compile.sh compila tanto modules/ quanto research/.

sh scripts/run-har-experiment.sh
sh scripts/run-har-experiment-docker.sh
sh scripts/run-simulator-docker.sh
sh scripts/package-experiment.sh exp-mimic-v31-icu-mortality-001