How verbal-autopsy-software/insilicova works
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.