Skip to content

Latest commit

 

History

History
114 lines (104 loc) · 8.31 KB

DEVELOPER_GUIDE.md

File metadata and controls

114 lines (104 loc) · 8.31 KB
Raw

Developer Guide

Table of Contents

Our Repo

Coding standards

  • Comment all functions
  • Pep standards and lint choice (TBD - devs help me here)
  • Most code changes should be done branches with pull requests managed on git hub
    • creating a new local branch named my-new-branch:
      • git checkout -b my-new-branch
    • Push your branch to the remote repository (for the first time)
      • git push --set-upstream origin my-new-branch
    • Push updates on your branch to the remote repository
      • git push origin my-new-branch
    • When ready, create a pull request

Code workflow diagram

  • (As of date: Oct 2023) image

Main project board

  • We have summarized the tasks in a Kanban Board found here: Project Board

Working with synthea

Outputs

Log files

  • You will find full_synthea_stdout_[date]_[time].txt in the project directory
    • This is a raw log version of the java run you can reference if the run hits programtic issues and to cross reference with your data input/output
  • You will find run_synthea.py_[date].log in the project directory
    • This is our helper function logging. It provides some wrapper logging for the java function, much of the same java logging as above, and some timing statistics
    • This also provides some debugging opportunity for the formatting operations of our summary output.

Output files

  • Running synthea will create the output folder in your project directory. This folder is where all patient records will be exported. Files will be exported to subfolders based on their type
  • Specifically, you have the option to configure synthea (see "Configurations" below)
  • Some description of the possible CSV summary outputs are documented here LINK

Configurations

  • Synthea runs with a multitude of optional settings, specified in a standalone text file in your project directory. We name this file "synthea_settings"
  • Some description of this file and its use is documented here LINK
  • The original default settings document from synthea org can be referenced here LINK

Appendix Tools

Installing a Virtual Machine

Even if you use a PC in the general course of business, you may still find it more convenient to code in a unix OS. A lightweight Linux VM from somewhere like VMware player can be a quick and easy solution.

Downloading and setting up the Linux VM

  • (time required: ~30-60 min)
  • Download latest VMware player (free) LINK
  • Download a Linux installation to use on the VM (free)
    • Try Mint XFCE first - its lightweight and might be all we need LINK
    • Save the iso to a directory of your choice
  • Create the VM with the Linux installation
    • Detailed Steps: LINK
    • Highlights:
      • “Create a new Virtual Machine” and choose “I will install the operating system later”
      • Select a guest operating system: Linux with version “other linux 5.x kernel 64-bit”
      • Might want at least 100gb of space for your VM filesystem. the synthea data logs can get big
        • As an aside - if you ever try to log into your VM and it loops on the login page the likely culprit is low disk space - enter the terminal with "ctr-alt-f1" and login there, then proceed to delete some files to free up space. Start with the raw /output/fhir/ files from synthea runs.
      • Right click on your new VM in the home menu of VMware workstation and go into settings
        • Allocate more memory - maybe 4gb depending on how much your physical machine has. I have 32gb RAM and usually only use up to half of it so 4-8 would be fine to allocate when using I think
        • I increased processors to 4 - no idea how important this is
        • Under CD/DVD (IDE) select “use ISO image file” and point to where you put your Mint ISO
        • No further changes to settings
      • Hit “play virtual machine” - it will send you to a welcome screen and auto start linux mint after a 10 sec count down.
      • Once launched and at the desktop screen for linux click “install linux mint” and proceed to step “b” below
    • Go through the install, reboot, and then setup instructions
      • You can safely select “erase disk and install linux mint” this is only referring to the VM disk space you allocated in step 3.a.iii.
      • After the install finishes, restart.
      • Once it boots back up you move onto configuration suggestions - make sure not to enable timeshift - it eats up your disk space and makes it difficult to login (reference topic discussion)
      • I did the update manager with whatever it suggested. Select the banner that suggest you “change mirror to a local one” to make this much much faster. In the popup just click on the two sources and give it a sec to test speeds and select the top speed option for each.
      • Install GIT from the software manager, we will need it later
      • Restart now or after you install your preferred IDE

IDE Example setup in IntelliJ

  • Within your VM install JetBrains Toolbox from the jetbrains website https://www.jetbrains.com/toolbox-app/
  • Install IntelliJ IDEA Community Edition from the toolbox
    • Note as of Summer '23 - version 2022.1.4 is the latest that supports the python plugins for some reason so install this version.

Coding and running Environment

Using a local IDE of your choice, add the GIT repos we will need and set up the virtual environment to access helper functions

  • (Create a GITHUB account if you have not already - github.com)
  • Git clone ssh://[email protected]/orchid-initiative/synthetic-database-project to your IDE
  • Download and execute synthea: synthea setup page
  • Create a virtual environment to access shared helper functions
  • Prepare to run synthea
    • if you haven't already, install synthea-with-dependencies.jar: Download Link
    • move synthea-with-dependencies.jar into your project directory (where run_synthea.py lives)
    • Run: $ python run_synthea.py --If the command 'python' is not found, use 'python3'