# verbal-autopsy-software/insilicova architecture

> Architecture diagram of the GitHub repository verbal-autopsy-software/insilicova, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/verbal-autopsy-software/insilicova
- Repository: https://github.com/verbal-autopsy-software/insilicova

## Overview

##### Project Overview and Purpose
- InSilicoVA is an R package (available on CRAN) that focuses on probabilistic Cause-of-death assignment using verbal autopsy data. It leverages statistical algorithms (as described in the referenced journal paper) and integrates Java code to handle computationally intensive tasks.
- The inclusion of Java components means that while the primary interface is in R (and thus, the core functionality is exposed as an R package), computational modules are offloaded to underlying Java classes accessed through the rJava package.

##### Key Components
a. R Package Layer:
- Core functions and utilities: Located under InSilicoVA/R, these include functions for training models (e.g., insilico_train.r), generating diagnostics (e.g., diag.r), plotting (e.g., indivplot.r, groupplot.r), and reporting.
- Documentation and Help Files: Man pages (InSilicoVA/man) and standard CRAN files (DESCRIPTION, NAMESPACE, NEWS.md) that explain available functionality.
- Data Files: The InSilicoVA/data directory holds sample datasets (e.g., RandomVA1.rda, condprob.rda) which the package uses to illustrate or run the algorithms.

b. Java Integration Layer:
- Java Modules used for intensive computations reside under the directories:
- InSilicoVA/inst/java (bundled jar such as Insilico.jar).
- Insilico/src and Insilico/java which contain source code for classes like InsilicoSampler, MathUtil, ProgressBar, etc.
- These Java components perform tasks such as sampling and other mathematical operations. Their functionality is exposed to R through the rJava package.
- External dependencies: Libraries such as commons-math3 and parallelcolt are packaged with the project (found in Insilico/library), which support numerical calculations.

c. Build and Continuous Integration (CI) Setup:
- GitHub Actions workflows (.github/workflows) and .travis.yml files provide guidance for testing and deployment.
- These configurations, while not directly part of the runtime architecture, are key to understanding how the system is built and maintained.

##### Relationships and Interactions
- The R Package Layer is the primary interface used by end-users.
- When a function that requires heavy computation is called, the R layer invokes the Java Integration Layer via the rJava package.
- Data flows from R to Java (for processing) and then results are returned to R for visualization, reporting, and further analysis.
- Underlying data (such as training data and sample outputs) is fed into the appropriate functions, and the output might be used to generate reports or plotted visuals.
- CI components show that new versions of the package are automatically tested and built, ensuring integration between the two codebases is maintained.

##### Architectural Patterns and Design Principles
- Separation of Concerns: The project cleanly separates statistical modeling/visualization (R) from performance-critical tasks (Java).
- Modularization: Each key task (sampling, diagnostics, plotting, etc.) is split into individual scripts or modules. In the Java side, classes are organized by functionality (sampler, utils).
- API-like Integration: The R package is designed to expose simple methods for users while abstracting away the complexities of Java computations.
- Build/CI Integration: Automated testing with GitHub Actions and Travis ensures that each component is tested independently and as part of the integrated system.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "R Package (InSilicoVA)"
        R_Core["Core Functions"] 
        R_Doc["Documentation & Help"]
        R_Data["Sample Data Files"]
    end

    subgraph "Java Computational Module"
        Java_Bin["Bundled Binary"]
        Java_Source1["Java Source (InSilicoVA/java/Insilico/src)"]
        Java_Source2["Additional Java Source (Insilico/src)"]
        Java_ExtLib["External Java Dependencies"]
    end

    subgraph "CI / Build Tools"
        CI_GH["GitHub Actions Workflows"]
        CI_Travis["Travis CI Config"]
    end

    R_Data -->|"loads_data"| R_Core
    R_Core -->|"calls_via_rJava"| Java_Bin
    Java_Bin -->|"returns_results"| R_Core
    Java_ExtLib -->|"supports"| Java_Source1
    Java_ExtLib -->|"supports"| Java_Source2
    CI_GH -->|"tests_build"| R_Core
    CI_GH -->|"tests_build"| Java_Bin
    CI_Travis -->|"tests_build"| R_Core
    CI_Travis -->|"tests_build"| Java_Bin

    class R_Core,R_Doc RComp
    class R_Data DataComp
    class Java_Bin,Java_Source1,Java_Source2,Java_ExtLib JavaComp
    class CI_GH,CI_Travis CIComp

    classDef RComp fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef JavaComp fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef DataComp fill:#FFD700,stroke:#000,stroke-width:2px;
    classDef CIComp fill:#FFA07A,stroke:#000,stroke-width:2px;

    click R_Core "https://github.com/verbal-autopsy-software/insilicova/tree/master/InSilicoVA/R"
    click R_Doc "https://github.com/verbal-autopsy-software/insilicova/tree/master/InSilicoVA/man"
    click R_Data "https://github.com/verbal-autopsy-software/insilicova/tree/master/InSilicoVA/data"
    click Java_Bin "https://github.com/verbal-autopsy-software/insilicova/blob/master/InSilicoVA/inst/java/Insilico.jar"
    click Java_Source1 "https://github.com/verbal-autopsy-software/insilicova/tree/master/InSilicoVA/java/Insilico/src"
    click Java_Source2 "https://github.com/verbal-autopsy-software/insilicova/tree/master/Insilico/src"
    click Java_ExtLib "https://github.com/verbal-autopsy-software/insilicova/tree/master/Insilico/library"
    click CI_GH "https://github.com/verbal-autopsy-software/insilicova/tree/master/.github/workflows"
    click CI_Travis "https://github.com/verbal-autopsy-software/insilicova/blob/master/InSilicoVA/.travis.yml"
```
