How davidcarayon/ideatools works
Main Components
• Entry Points:
• Command-Line Interface (invoking functions directly, e.g. diag_idea()).
• Graphical User Interface provided by runGUI() and the Shiny app (inst/ShinyApp/app.R).
• Core Modules:
• Data Input: read_idea() for file validation and data extraction, and old_idea() for legacy calculator handling.
• Computation Engine: compute_idea() which calculates the IDEA components based on the input.
• Visualization: plot_idea() for generating graphical outputs.
• Reporting: write_idea() which handles the export of raw graphs and formatted reports.
• Orchestrator: diag_idea() that coordinates the entire workflow by sequentially calling the appropriate modules.
• Auxiliary Modules:
• Additional utilities in utils.R and theme functions in themes.R.
• The jsonify module (mentioned in the README as jsonify2()) which converts Excel data to JSON for use by external systems like WEBIDEA.
• Documentation & Support Files:
• The man, docs, and vignettes directories, which document the functionality and usage.
• Test and Continuous Integration configurations (.github workflows, .gitlab-ci.yml, etc.)
• External Dependencies:
• A dependency on LaTeX (for PDF reports) and Helvetica font.
• R interpreter and additional R packages (for processing, Shiny for the GUI).
Relationships and Interactions
• The diag_idea() function acts as the central "orchestrator" calling:
• The Reading module (read_idea() / old_idea()) to validate and extract input data.
• The Computation module (compute_idea()) to compute indicators.
• The Plotting module (plot_idea()) to produce figures.
• The Reporting module (write_idea()) to finally export results in diverse formats.
• The runGUI() function provides a UI-based access point that eventually triggers the same backend workflow but through a Shiny application.
• There are dependencies among the R functions—the output of read_idea() is input for compute_idea(), whose output feeds plot_idea() and write_idea().
Architectural Patterns and Design Principles
• Modular Design: Each function (module) handles a specific part of the diagnostic pipeline so that responsibilities are clearly separated.
• Layered Approach: The system can be visualized as layers:
• Interface Layer (CLI and GUI),
• Processing Layer (data reading, computation, plotting),
• Output Layer (report generation).
• Extensibility: The use of helpers, themes, and utility functions (utils.R, themes.R) implies that the system is designed for adaptability (e.g., supporting new input formats or output types).
Specific Technologies, Frameworks, and Libraries
• R as the core language/platform and the R package structure (modules in R/ directory, DESCRIPTION, NAMESPACE).
• Shiny framework for the GUI (located in inst/ShinyApp).
• LaTeX for PDF report generation.
• pkgdown for generating online documentation.
• Version control and CI/CD systems, as seen from .github workflows and .gitlab-ci.yml.
Elements
• Clear Labels: For each component (input, compute, plot, reporting, orchestration, GUI).
Putting It All Together
• How the diag_idea() function “glues” all the modules together.