diff --git a/.DS_Store b/.DS_Store index 2cf51257028026c2fd9dd06d3da54d35242e7bcf..fbf73d8f06ff52658b2942a2df2f32b8074e9ae1 100644 Binary files a/.DS_Store and b/.DS_Store differ diff --git a/documentation/.DS_Store b/documentation/.DS_Store new file mode 100644 index 0000000000000000000000000000000000000000..870e38a6ec48205a378c5aba077a6881565b46f9 Binary files /dev/null and b/documentation/.DS_Store differ diff --git a/documentation/doc_en.md b/documentation/doc_en.md new file mode 100644 index 0000000000000000000000000000000000000000..a14983b5d24e11bc8583e0907b14d5c5f8c80f23 --- /dev/null +++ b/documentation/doc_en.md @@ -0,0 +1,183 @@ +# Malaria Lite Project Documentation 1.2 + +## Project Structure +The project consists of three main files: +- `notes_time_series.R`: Time series analysis +- `server.R`: Shiny server configuration and logic +- `ui.R`: Application user interface + +## 1. notes_time_series.R +This script enables malaria case time series analysis. + +### Main Features: +- Case incidence calculation over time +- Time series decomposition for trend and seasonality identification +- Data filtering and analysis by health center +- Temporal trend visualization + +### Code Details: +```r +# Incidence calculation +consultation_date <- JSON_cons_har$consultation_date +inc <- as.data.frame(incidence(dates = consultation_date, interval = 1)) +``` +This section calculates daily case incidence. + +```r +# Time series decomposition +inc_ts <- ts(inc$counts, frequency = 7) +inc_dec <- stl(inc_ts, s.window="periodic") +``` +This part decomposes the time series to identify seasonal components. + +## 2. server.R +Main Shiny server file managing application logic. + +### Initial Setup: +- Loading required libraries +- Translation file import +- Utility function loading +- Geographic and consultation data initialization + +### Main Modules: +1. Harmonized module (harmonized.R) +2. Harmonized localities module (harmonized_loc.R) +3. Download module (download.R) +4. Ranking module (ranking.R) +5. Information quality module (infoq.R) +6. Map module (map.R) + +### Security and Terms of Use: +The server implements a modal dialog with terms of use in three languages (Portuguese, French, English), compliant with CNIL requirements. + +## 3. ui.R +Shiny application user interface. + +### Interface Features: +- Theme: Purple skin +- Multilingual support (EN/FR/PT) +- Dashboard structure with sidebar +- Google Analytics integration + +### Main Components: +```r +dashboardPage( + dashboardHeader(...), # Header with title + dashboardSidebar(...), # Sidebar with menu and language selection + dashboardBody(...) # Main body with dynamic content +) +``` + +## JSON Data Structures + +### Consultation Data Format (`consultation_harmonized.json`) +```json +{ + "data": [ + { + "id_consultation": "string", // Unique consultation ID + "source": "string", // "BR" or "FR-GF" + "consultation_date": "DD/MM/YYYY", // Date in French format + "id_center": "string", // Health center ID + "residence_place": "string", // Residence place ID + "infection_place": "string", // Presumed infection place ID + "patient_age": "number", // Patient age (0-100) + "patient_sex": "string", // "Male", "Female" or "Desconhecido" + "diagnosis_result": "string", // Result code (1-11) + "active_diagnosis": "boolean", // Active or passive diagnosis + "new_attack": "boolean" // New attack or relapse + } + ] +} +``` + +## Time Series Decomposition Algorithms + +### 1. STL Decomposition (Seasonal-Trend using Loess) + +```r +# Main decomposition function +decompose <- function(x) { + # Data preparation + date1 <- min(x) + date2 <- max(x) + + # Daily incidence calculation + inc <- as.data.frame(incidence(dates = x, interval = 1)) + + # Missing dates completion + full <- data.frame(dates = seq(date1, date2, by = "day")) + inc <- dplyr::right_join(inc, full, by = "dates") + inc[is.na(inc)] <- 0 + + # Time series creation with annual frequency + inc_ts <- ts(inc$counts, frequency = 365) + + # STL decomposition + inc_dec <- stl(inc_ts, s.window="periodic") + + return(df_dec) +} +``` + +Decomposition Components: +1. **Trend**: Long-term evolution +2. **Seasonality**: Annual cyclic patterns +3. **Remainder**: Unexplained variations + +## Implementation Notes + +### Geographic Data Management: +- Use of shapefiles for spatial data +- Support for Brazil (BR) and French Guiana (GF) coordinates +- Unique identifier management (id_sivep, id_cdps) + +### Data Security: +- Anonymized data as per CNIL requirements +- Authorized automated processing (Decision N°2019-025) +- Commercial use restrictions + +### Performance: +- Optimized data loading +- Efficient use of st_read for shape files +- Effective data joining management + +## Maintenance Instructions + +To update the application: +1. Update JSON files in "data/" folder +2. Check last update dates in "data/dates_recup_donnees_syst_surveillance.txt" +3. Validate translations in "locale/translation.bin" +4. Test filtering and visualization functionalities + +## Shiny Modules (modules/ folder) + +### Harmonized Analysis Modules + +1. `harmonized.R` +- Analysis of harmonized data between BR and FR-GF +- Temporal visualizations (incidence, age, sex, plasmodium) +- Dynamic filters (dates, cases, diagnosis, age, sex) +- Reactive statistics calculations + +2. `harmonized_loc.R` +- Geographic analysis of harmonized data +- Location-based visualization +- Multi-country support (BR/FR-GF) +- Configurable temporal aggregation + +### Map Module + +`map.R` +- Interactive mapping interface +- OpenStreetMap integration +- Case visualization by area +- GBIF data support for Anopheles +- WMS layers for risk models + +Key Module Features: +1. Reactivity: Extensive use of Shiny reactive functions +2. Modularity: Clear separation of responsibilities +3. Multilingual: Integrated support for 3 languages +4. Performance: Calculation and rendering optimization +5. Extensibility: Architecture allowing new module addition \ No newline at end of file diff --git a/documentation/doc_fr.md b/documentation/doc_fr.md new file mode 100644 index 0000000000000000000000000000000000000000..257ca52ed4d02ab3f8cba723fe0ad4450d6dca2f --- /dev/null +++ b/documentation/doc_fr.md @@ -0,0 +1,372 @@ +# Documentation du Projet Malaria Lite 1.2 + +## Structure du Projet +Le projet est composé de trois fichiers principaux : +- `notes_time_series.R` : Analyse des séries temporelles +- `server.R` : Configuration et logique du serveur Shiny +- `ui.R` : Interface utilisateur de l'application + +## 1. notes_time_series.R +Ce script permet l'analyse des séries temporelles des cas de malaria. + +### Fonctionnalités principales : +- Calcul de l'incidence des cas au fil du temps +- Décomposition des séries temporelles pour identifier les tendances et la saisonnalité +- Filtrage et analyse des données par centre de santé +- Visualisation des tendances temporelles + +### Détails du code : +```r +# Calcul de l'incidence +consultation_date <- JSON_cons_har$consultation_date +inc <- as.data.frame(incidence(dates = consultation_date, interval = 1)) +``` +Cette section calcule l'incidence journalière des cas. + +```r +# Décomposition des séries temporelles +inc_ts <- ts(inc$counts, frequency = 7) +inc_dec <- stl(inc_ts, s.window="periodic") +``` +Cette partie décompose la série temporelle pour identifier les composantes saisonnières. + +## 2. server.R +Fichier principal du serveur Shiny qui gère la logique de l'application. + +### Configuration initiale : +- Chargement des bibliothèques nécessaires +- Importation des fichiers de traduction +- Chargement des fonctions utilitaires +- Initialisation des données géographiques et des consultations + +### Modules principaux : +1. Module harmonisé (harmonized.R) +2. Module des localités harmonisées (harmonized_loc.R) +3. Module de téléchargement (download.R) +4. Module de classement (ranking.R) +5. Module de qualité d'information (infoq.R) +6. Module cartographique (map.R) + +### Sécurité et conditions d'utilisation : +Le serveur implémente une boîte de dialogue modale avec les conditions d'utilisation en trois langues (portugais, français, anglais), conformément aux exigences de la CNIL. + +## 3. ui.R +Interface utilisateur de l'application Shiny. + +### Caractéristiques de l'interface : +- Thème : Purple skin +- Support multilingue (EN/FR/PT) +- Structure en dashboard avec barre latérale +- Intégration de Google Analytics + +### Composants principaux : +```r +dashboardPage( + dashboardHeader(...), # En-tête avec titre + dashboardSidebar(...), # Barre latérale avec menu et sélection de langue + dashboardBody(...) # Corps principal avec contenu dynamique +) +``` + +## Notes d'implémentation + +### Gestion des données géographiques : +- Utilisation de fichiers shapefile pour les données spatiales +- Support des coordonnées pour le Brésil (BR) et la Guyane française (GF) +- Gestion des identifiants uniques (id_sivep, id_cdps) + +### Sécurité des données : +- Données anonymisées conformément aux exigences CNIL +- Traitement automatisé autorisé (Délibération N°2019-025) +- Restrictions d'usage commercial + +### Performance : +- Chargement optimisé des données +- Utilisation de st_read pour les fichiers shape +- Gestion efficace des jointures de données + +## Fonctions Utilitaires (dossier functions/) + +### Fonctions de Gestion des Données +1. `consultation_har_ingest.R` +```r +# Fonction principale pour charger et prétraiter les données de consultation +consultation_har_ingest <- function(json.dir, json.file) +``` +- Charge les données JSON des consultations +- Effectue le nettoyage des données (NA, dates, facteurs) +- Conversion des types de données appropriés + +2. `area_har_ingest.R` et `healthcenter_har_ingest.R` +- Fonctions similaires pour charger les données des zones et centres de santé +- Utilise `data.table` pour une gestion efficace des données + +### Fonctions de Filtrage et Analyse + +1. `consultation_har_filter.R` +```r +consultation_har_filter <- function(df, source = "Any", new_attack, dateStart = "Any", + dateEnd = "Any", diagn = "Any", minAge = NULL, + maxAge = NULL, sex = "Any", active_diagn = "No") +``` +- Filtrage flexible des données de consultation +- Gestion des critères multiples (date, diagnostic, âge, sexe) +- Support du filtrage FR-GF/BR + +2. `decompose.R` +```r +decompose <- function(x) +``` +- Décomposition des séries temporelles +- Calcul de l'incidence journalière +- Gestion des données manquantes + +### Fonctions de Visualisation + +1. `calendarHeat.R` +- Implémentation d'une carte de chaleur calendaire +- Basé sur le travail de Paul Bleicher +- Visualisation des données temporelles sous forme de calendrier + +2. `addLegendCustom.R` +```r +addLegendCustom <- function(map, colors, labels, sizes, opacity = 0.5) +``` +- Personnalisation des légendes pour les cartes +- Support des styles personnalisés + +### Fonctions Utilitaires + +1. `translate.R` +```r +tr <- function(text) +``` +- Gestion de la traduction (EN/FR/PT) +- Utilise un système de clés de traduction + +2. `last_update.R` +```r +last_update <- function(ftxt="data/dates_recup_donnees_syst_surveillance.txt") +``` +- Gestion des dates de mise à jour +- Support pour BR et GF + +3. `update_OSM_data.R` +- Mise à jour des données OpenStreetMap +- Récupération des informations sur les hôpitaux et cliniques + +### Conversions et Exports + +1. `consultation_json2csv.R` +- Conversion des données JSON en CSV +- Fonctions de lecture et écriture +- Prétraitement des données similaire à `consultation_har_ingest.R` + +## Modules Shiny (dossier modules/) + +### Modules d'Analyse Harmonisés + +1. `harmonized.R` +- Analyse des données harmonisées entre BR et FR-GF +- Visualisations temporelles (incidence, âge, sexe, plasmodium) +- Filtres dynamiques (dates, cas, diagnostic, âge, sexe) +- Calculs réactifs des statistiques + +2. `harmonized_loc.R` +- Analyse géographique des données harmonisées +- Visualisation par localisation (centres, zones de résidence, lieux d'infection) +- Support multi-pays (BR/FR-GF) +- Agrégation temporelle configurable + +### Modules de Classement et Téléchargement + +1. `ranking.R` +```r +# Fonctionnalités principales +- Classement des zones par nombre de cas +- Filtrage multi-critères (type, dates, diagnostic) +- Visualisation tabulaire avec tri dynamique +``` + +2. `download.R` +- Export des données filtrées +- Support de multiples formats (CSV, Excel, PDF) +- Sélection des zones géographiques +- Personnalisation des périodes + +### Module Cartographique + +`map.R` +- Interface cartographique interactive +- Intégration de données OpenStreetMap +- Visualisation des cas par zone +- Support des données GBIF pour Anopheles +- Couches WMS pour modèles de risque + +### Modules de Qualité des Données + +1. `infoq.R` +```r +# Analyse de la qualité des données +- Suivi des données manquantes +- Graphiques temporels de complétude +- Ventilation par source de données +``` + +2. `brazil.R` et `brazil_age.R` +- Analyses spécifiques aux données brésiliennes +- Visualisations démographiques +- Statistiques d'âge et de distribution + +### Architecture de l'Interface + +`server_ui.R` +- Configuration des menus et onglets +- Gestion du multilingue (EN/FR/PT) +- Construction dynamique de l'interface +- Gestion des événements utilisateur + +Caractéristiques clés des modules : +1. Réactivité : Utilisation intensive de fonctions réactives Shiny +2. Modularité : Séparation claire des responsabilités +3. Multilingue : Support intégré de 3 langues +4. Performance : Optimisation des calculs et des rendus +5. Extensibilité : Architecture permettant l'ajout de nouveaux modules + +## Structures des Données JSON + +### Format des Données de Consultation (`consultation_harmonized.json`) +```json +{ + "data": [ + { + "id_consultation": "string", // Identifiant unique de consultation + "source": "string", // "BR" ou "FR-GF" + "consultation_date": "DD/MM/YYYY", // Date au format français + "id_center": "string", // Identifiant du centre de santé + "residence_place": "string", // Identifiant du lieu de résidence + "infection_place": "string", // Identifiant du lieu d'infection présumé + "patient_age": "number", // Âge du patient (0-100) + "patient_sex": "string", // "Male", "Female" ou "Desconhecido" + "diagnosis_result": "string", // Code du résultat (1-11) + "active_diagnosis": "boolean", // Diagnostic actif ou passif + "new_attack": "boolean" // Nouvelle attaque ou rechute + } + ] +} +``` + +### Format des Centres de Santé (`JSON_healthcenter_har.csv`) +```csv +id_center,name,source,geocoded,x_coordinate,y_coordinate +"11/160050","Centre de Santé A","BR",true,-51.548,3.938 +"CAM","CDPS Camopi","FR-GF",true,-52.339,3.167 +``` + +### Format des Zones Géographiques (`unique_Spatial_referential.shp`) +- Format Shapefile contenant les polygones des zones +- Attributs obligatoires : + - country : "BR" ou "GF" + - name : Nom de la localité + - id_sivep : Identifiant SIVEP (Brésil) + - id_cdps : Identifiant CDPS (Guyane française) + - geocoded : Statut de géocodage + +## Algorithmes de Décomposition Temporelle + +### 1. Décomposition STL (Seasonal-Trend using Loess) + +```r +# Fonction principale de décomposition +decompose <- function(x) { + # Préparation des données + date1 <- min(x) + date2 <- max(x) + + # Calcul de l'incidence journalière + inc <- as.data.frame(incidence(dates = x, interval = 1)) + + # Complétion des dates manquantes + full <- data.frame(dates = seq(date1, date2, by = "day")) + inc <- dplyr::right_join(inc, full, by = "dates") + inc[is.na(inc)] <- 0 + + # Création de la série temporelle avec fréquence annuelle + inc_ts <- ts(inc$counts, frequency = 365) + + # Décomposition STL + inc_dec <- stl(inc_ts, s.window="periodic") + + # Extraction des composantes + df_dec <- as.data.frame(inc_dec$time.series) + df_dec <- cbind(df_dec, dates = inc$dates) + + return(df_dec) +} +``` + +Composantes de la décomposition : +1. **Tendance (trend)** : Évolution à long terme +2. **Saisonnalité (seasonal)** : Motifs cycliques annuels +3. **Résidus (remainder)** : Variations non expliquées + +### 2. Analyse des Pics Saisonniers + +```r +# Identification des pics saisonniers +analyze_seasonality <- function(df_dec) { + # Calcul des quantiles pour identifier les pics + q <- quantile(df_dec$seasonal, c(.90)) + sub <- subset(df_dec, seasonal >= q) + + # Distribution mensuelle des pics + monthly_dist <- table(lubridate::month(sub$dates)) + + return(monthly_dist) +} +``` + +### 3. Calcul de l'Incidence + +```r +# Calcul de l'incidence avec différentes agrégations +calculate_incidence <- function(dates, interval = 1) { + if(interval == 1) { + # Incidence journalière + inc <- group_by(dates = floor_date(consultation_date, "day")) + } else if(interval == 7) { + # Incidence hebdomadaire (ISO) + inc <- incidence(dates, interval = 7, iso_week = TRUE) + } else if(interval == 30) { + # Incidence mensuelle + inc <- group_by(dates = floor_date(consultation_date, "month")) + } + + return(inc) +} +``` + +### Visualisation des Décompositions + +1. **Carte de Chaleur Calendaire** +- Utilisation de `calendarHeat()` +- Visualisation jour par jour des cas +- Code couleur paramétrable (r2g, g2r, etc.) + +2. **Graphiques de Tendance** +- Utilisation de Plotly pour l'interactivité +- Support du zoom et des survols +- Comparaison BR/FR-GF + +3. **Analyse des Résidus** +- Tests de normalité +- Détection des valeurs aberrantes +- Autocorrélation + +## Instructions de maintenance + +Pour mettre à jour l'application : +1. Mettre à jour les fichiers JSON dans le dossier "data/" +2. Vérifier les dates de dernière mise à jour dans "data/dates_recup_donnees_syst_surveillance.txt" +3. Valider les traductions dans "locale/translation.bin" +4. Tester les fonctionnalités de filtrage et de visualisation diff --git a/documentation/doc_pt.md b/documentation/doc_pt.md new file mode 100644 index 0000000000000000000000000000000000000000..5fcd44a8b674614f8171e9aa89af186c711cbe5c --- /dev/null +++ b/documentation/doc_pt.md @@ -0,0 +1,183 @@ +# Documentação do Projeto Malaria Lite 1.2 + +## Estrutura do Projeto +O projeto é composto por três arquivos principais: +- `notes_time_series.R`: Análise de séries temporais +- `server.R`: Configuração e lógica do servidor Shiny +- `ui.R`: Interface do usuário da aplicação + +## 1. notes_time_series.R +Este script permite a análise de séries temporais dos casos de malária. + +### Funcionalidades Principais: +- Cálculo da incidência de casos ao longo do tempo +- Decomposição de séries temporais para identificação de tendências e sazonalidade +- Filtragem e análise de dados por centro de saúde +- Visualização de tendências temporais + +### Detalhes do Código: +```r +# Cálculo da incidência +consultation_date <- JSON_cons_har$consultation_date +inc <- as.data.frame(incidence(dates = consultation_date, interval = 1)) +``` +Esta seção calcula a incidência diária de casos. + +```r +# Decomposição de séries temporais +inc_ts <- ts(inc$counts, frequency = 7) +inc_dec <- stl(inc_ts, s.window="periodic") +``` +Esta parte decompõe a série temporal para identificar componentes sazonais. + +## 2. server.R +Arquivo principal do servidor Shiny que gerencia a lógica da aplicação. + +### Configuração Inicial: +- Carregamento das bibliotecas necessárias +- Importação dos arquivos de tradução +- Carregamento das funções utilitárias +- Inicialização dos dados geográficos e de consultas + +### Módulos Principais: +1. Módulo harmonizado (harmonized.R) +2. Módulo de localidades harmonizadas (harmonized_loc.R) +3. Módulo de download (download.R) +4. Módulo de classificação (ranking.R) +5. Módulo de qualidade da informação (infoq.R) +6. Módulo de mapa (map.R) + +### Segurança e Termos de Uso: +O servidor implementa uma caixa de diálogo modal com termos de uso em três idiomas (português, francês, inglês), em conformidade com os requisitos da CNIL. + +## 3. ui.R +Interface do usuário da aplicação Shiny. + +### CaracterÃsticas da Interface: +- Tema: Skin roxa +- Suporte multilÃngue (EN/FR/PT) +- Estrutura de painel com barra lateral +- Integração com Google Analytics + +### Componentes Principais: +```r +dashboardPage( + dashboardHeader(...), # Cabeçalho com tÃtulo + dashboardSidebar(...), # Barra lateral com menu e seleção de idioma + dashboardBody(...) # Corpo principal com conteúdo dinâmico +) +``` + +## Estruturas de Dados JSON + +### Formato dos Dados de Consulta (`consultation_harmonized.json`) +```json +{ + "data": [ + { + "id_consultation": "string", // ID único da consulta + "source": "string", // "BR" ou "FR-GF" + "consultation_date": "DD/MM/YYYY", // Data no formato francês + "id_center": "string", // ID do centro de saúde + "residence_place": "string", // ID do local de residência + "infection_place": "string", // ID do local presumido de infecção + "patient_age": "number", // Idade do paciente (0-100) + "patient_sex": "string", // "Male", "Female" ou "Desconhecido" + "diagnosis_result": "string", // Código do resultado (1-11) + "active_diagnosis": "boolean", // Diagnóstico ativo ou passivo + "new_attack": "boolean" // Novo ataque ou recaÃda + } + ] +} +``` + +## Algoritmos de Decomposição Temporal + +### 1. Decomposição STL (Seasonal-Trend using Loess) + +```r +# Função principal de decomposição +decompose <- function(x) { + # Preparação dos dados + date1 <- min(x) + date2 <- max(x) + + # Cálculo da incidência diária + inc <- as.data.frame(incidence(dates = x, interval = 1)) + + # Preenchimento de datas faltantes + full <- data.frame(dates = seq(date1, date2, by = "day")) + inc <- dplyr::right_join(inc, full, by = "dates") + inc[is.na(inc)] <- 0 + + # Criação da série temporal com frequência anual + inc_ts <- ts(inc$counts, frequency = 365) + + # Decomposição STL + inc_dec <- stl(inc_ts, s.window="periodic") + + return(df_dec) +} +``` + +Componentes da Decomposição: +1. **Tendência**: Evolução a longo prazo +2. **Sazonalidade**: Padrões cÃclicos anuais +3. **ResÃduos**: Variações não explicadas + +## Notas de Implementação + +### Gestão de Dados Geográficos: +- Uso de shapefiles para dados espaciais +- Suporte para coordenadas do Brasil (BR) e Guiana Francesa (GF) +- Gestão de identificadores únicos (id_sivep, id_cdps) + +### Segurança dos Dados: +- Dados anonimizados conforme requisitos CNIL +- Processamento automatizado autorizado (Decisão N°2019-025) +- Restrições de uso comercial + +### Desempenho: +- Carregamento otimizado de dados +- Uso eficiente de st_read para arquivos shape +- Gestão eficaz de junções de dados + +## Instruções de Manutenção + +Para atualizar a aplicação: +1. Atualizar arquivos JSON na pasta "data/" +2. Verificar datas de última atualização em "data/dates_recup_donnees_syst_surveillance.txt" +3. Validar traduções em "locale/translation.bin" +4. Testar funcionalidades de filtragem e visualização + +## Módulos Shiny (pasta modules/) + +### Módulos de Análise Harmonizada + +1. `harmonized.R` +- Análise de dados harmonizados entre BR e FR-GF +- Visualizações temporais (incidência, idade, sexo, plasmodium) +- Filtros dinâmicos (datas, casos, diagnóstico, idade, sexo) +- Cálculos estatÃsticos reativos + +2. `harmonized_loc.R` +- Análise geográfica de dados harmonizados +- Visualização baseada em localização +- Suporte multi-paÃs (BR/FR-GF) +- Agregação temporal configurável + +### Módulo de Mapa + +`map.R` +- Interface de mapeamento interativa +- Integração com OpenStreetMap +- Visualização de casos por área +- Suporte a dados GBIF para Anopheles +- Camadas WMS para modelos de risco + +CaracterÃsticas Principais dos Módulos: +1. Reatividade: Uso extensivo de funções reativas Shiny +2. Modularidade: Separação clara de responsabilidades +3. MultilÃngue: Suporte integrado para 3 idiomas +4. Desempenho: Otimização de cálculos e renderização +5. Extensibilidade: Arquitetura permitindo adição de novos módulos \ No newline at end of file