Package: femr
FEMRFramework for Electronic Medical RecordsFEMRis a Python package for manipulating longitudinal EHR data for machine learning, with a focus on supporting the creation of foundation models and verifying theirpresumed benefitsin healthcare. Such a framework is needed given thecurrent state of large language models in healthcareand the need for better evaluation frameworks.The currently supported foundation models areCLMBRandMOTOR.FEMRby default supports theOMOP Common Data Modeldeveloped by the OHDSI community, but can also be used with other forms of EHR / claims data with minimal processing.FEMRhas been used to process data from a variety of sources, including MIMIC-IV, Optum, Truven, STARR-OMOP, and SickKids-OMOP.FEMRhelps users:Manipulate events in the EHR data comprising a patient's timelineAlgorithmically label patient records based on structured dataGenerate tabular features from patient timelines for use with traditional gradient boosted tree modelsTrainandfinetuneCLMBR-derived models for binary classification and prediction tasks.Trainand finetune MOTOR-derived models for making time-to-event predictions.We recommend users start with ourtutorial folderInstallationThere are two variants of theFEMRpackage, a CPU only version and a CUDA enabled version.How to installFEMRwithout CUDApipinstallfemrIf you have a particularly old CPU, we offer a variant of femr without CPU optimations.pipinstallfemr_oldcpuHow to installFEMRwith CUDA supportNote that CUDA-enabledFEMRrequires jax in order to function.pipinstall--upgrade"jax[cuda11_pip]==0.4.8"-fhttps://storage.googleapis.com/jax-releases/jax_cuda_releases.html
pipinstall"femr_cuda[models]"Getting StartedThe first step of usingFEMRis to convert your patient data into a femr.datasets.PatientDatabase, the standard file format used by theFEMRcodebase to hold and query patient timelines.There are two recommended paths for doing this, each with a corresponding tutorial:Convert your data to OMOP format, and then run the OMOP converterConvert your data to FEMR's simple csv format, and then run the simple FEMR converterThe simple csv route has an advantage of being an easier ETL, but does come with some downsides. See the below table for what features we support with what ETLs.CapabilityOMOP -> FEMRSimple CSV -> FEMRCore Labeling Tools:white_check_mark::white_check_mark:OMOP Specific Labeling:white_check_mark::x:Tabular Feature Generation:white_check_mark::white_check_mark:Foundation Model Training:white_check_mark::white_check_mark:Shared Vocabulary Enabling Cross-Site Foundation Model Transfer:white_check_mark::x:DevelopmentThe following guides are for developers who want to contribute toFEMR.Building from sourceIn some scenarios (such as contributing toFEMR), you might want to compile the package from source.In order to do so, follow the following instructions.condacreate-nFEMR_ENVpython=3.10bazel=6-cconda-forge-y
condaactivateFEMR_ENVexportBAZEL_USE_CPP_ONLY_TOOLCHAIN=1gitclonehttps://github.com/som-shahlab/femr.gitcdfemr
pipinstall-e.Special note for NERO usersAs Nero does not have internet access, you must run the following before running the code above.exportDISTDIR=/local-scratch/nigam/distdir(Optional) Installing CUDA on Nero / CarinaAs a side note for Nero/Carina users, do not use your home directory to save the femr repo and installation files due to limited storage. We recommend using the shared project folder, e.g., on nero, use '/local-scratch/nigam/project/...'If you are using Nero, you will need to install CUDA manually until the CUDA version on Nero is updated. To do so, follow these steps:Download version 11.8 of CUDA onto your local machinefrom hereCopy your CUDA download from your local machine onto Nero, into whatever folder you'd like. We'll refer to the path to this folder as<PATH_TO_CUDA_INSTALLER>from now on.Note:Nero doesn't work withscp. You can use an alternative likepscp, which functions basically identically toscp. You can installpscpon a Mac by usingbrew install putty.sshinto Nero usingssh <username>@nero-nigam.compute.stanford.eduOn Nero, run the CUDA installer as a bash command as follows:bash <PATH_TO_CUDA_INSTALLER> --installpath=<INSTALL_PATH>, where<PATH_TO_CUDA_INSTALLER>is the path to the file you downloaded/transferred in Step #2, and<INSTALL_PATH>is where you'd like to save your CUDA installation files. We recommend using~or something similar.The CUDA installer will pop-up a window during installation. Uncheck all of the boxes it presents except for the box labeled "cuda toolkit".After the installation completes, the installer will print out two paths to your console. Take note of these paths, and copy them into your.bashrcfile by running the following commands.Install cuDNN v8.7.0 (November 28th, 2022) for CUDA. Go to thislinkand download the fileDownload cuDNN v8.7.0 (November 28th, 2022), for CUDA 11.x->Local Installer for Linux x86_64 (Tar)on your local computer and transfer it
over to your local folder in nero. Then follow the instructionheresection 1.3. Note that you need to copy over cudnn files to your local cuda. For example,cp cudnn-*-archive/include/cudnn*.h <path_to_your_cuda>/includecp -P cudnn-*-archive/lib/libcudnn* <path_to_your_cuda>/lib64chmod a+r <path_to_your_cuda>/include/cudnn*.h <path_to_your_cuda>/lib64/libcudnn*Add the following to your .bashrc file. You may need to restart your terminal for the changes to be reflected.exportPATH="<INSTALL_PATH>/bin:$PATH"exportLD_LIBRARY_PATH="<INSTALL_PATH>/lib64:$LD_LIBRARY_PATH"To write in a .bashrc file, usenano~/.bashrcRunrm /tmp/cuda-installer.logto remove the installer log (if you don't do this, it will cause a segmentation fault for other users when they try to install CUDA).Precommit checksBefore committing, please run the following commands to ensure that your code is formatted correctly and passes all tests.Installationcondainstallpre-commitpytest-y
pre-commitinstallRunningTest FunctionspytesttestsFormatting Checkspre-commitrun--all-filesMiscellaneousGZIP decompression commandsexportOMOP_SOURCE=/share/pi/nigam...
gunzip$OMOP_SOURCE/**/*.csv.gzZstandard compression commandsexportOMOP_SOURCE=/share/pi/nigam...
zstd-1--rm$OMOP_SOURCE/**/*.csvGenerating extract# Set up environment variables#   Path to a folder containing your raw STARR-OMOP download, generated via `tools.stanford.download_bigquery.py`exportOMOP_SOURCE=/path/to/omop/folder...#   Path to any arbitrary folder where you want to store your FEMR extractexportEXTRACT_DESTINATION=/path/to/femr/extract/folder...#   Path to any arbitrary folder where you want to store your FEMR extract logsexportEXTRACT_LOGS=/path/to/femr/extract/logs...# Do some data preprocessing with Stanford-specific helper scripts#   Extract data from flowsheetspythontools/stanford/flowsheet_cleaner.py--num_threads5$OMOP_SOURCE"${EXTRACT_DESTINATION}_flowsheets"#   Normalize visitspythontools/omop/normalize_visit_detail.py--num_threads5"${EXTRACT_DESTINATION}_flowsheets""${EXTRACT_DESTINATION}_flowsheets_detail"# Run actual FEMR extractionetl_stanford_omop"${EXTRACT_DESTINATION}_flowsheets_detail"$EXTRACT_DESTINATION$EXTRACT_LOGS--num_threads10Example usage (Note: This should take ~10 minutes on a 1% extract of STARR-OMOP)exportOMOP_SOURCE=/local-scratch/nigam/projects/ethanid/som-rit-phi-starr-prod.starr_omop_cdm5_deid_1pcent_2022_11_09exportEXTRACT_DESTINATION=/local-scratch/nigam/projects/mwornow/femr_starr_omop_cdm5_deid_1pcent_2022_11_09exportEXTRACT_LOGS=/local-scratch/nigam/projects/mwornow/femr_starr_omop_cdm5_deid_1pcent_2022_11_09_logs

pythontools/stanford/flowsheet_cleaner.py--num_threads5$OMOP_SOURCE"${EXTRACT_DESTINATION}_flowsheets"pythontools/omop/normalize_visit_detail.py--num_threads5"${EXTRACT_DESTINATION}_flowsheets""${EXTRACT_DESTINATION}_flowsheets_detail"etl_stanford_omop"${EXTRACT_DESTINATION}_flowsheets_detail"$EXTRACT_DESTINATION$EXTRACT_LOGS--num_threads10(Optional) Installing PyTorchIf you are on Nero, you need to install PyTorch using:condainstallnumpy-y
pipinstalltorch==1.12.0torchvision==0.13.0torchaudio==0.12.0--extra-index-urlhttps://download.pytorch.org/whl/cu111If you are on Carina, you need to install PyTorch using:condainstallnumpypytorchtorchvisiontorchaudiopytorch-cuda=11.7-cpytorch-cnvidia-y