71 icu entry as outcome

[gemini-wenb]

Closes #71 This PR implemented a new feature to icu_entry(). The new feature provides an option to compute ICU admission as a clinical outcome. In research projects, ICU admissions are often a study outcome, which should not take place at the same time as the exposures of interest. With this new implementation, icu_entry() has the options to return ICU-admission as a descriptive feature (i.e. not excluding entries prior to or at IP admission) or ICU-admission as a clinical outcome.

Key changes:

1. added option to return ICU as a clinical outcome or not (param as_outcome )
2. added option to customize a different cutoff time (default is IP admission time) to exclude records from being considered in the identification of ICU entries (param exclude_cutoff)
3. updated parameter naming from window to entry_since_cutoff to avoid potential confusions as a result of the new features
4. updated documentation with examples for common use cases
5. updated function warning messages on invalid date-time and exclusion details
6. created unit tests for this function: test-icu_entry.R (Reviewer, please feel free to suggest additional unit tests if there is any important testing case that has not been covered here).

[marchenaromk]

Hi Bijun, thanks for including the test cases! They were very helpful and all test cases passed. Just one quick thought: should ICU entries that occur prior to admission be considered NArather than False when as_outcome = T? This would make a clear distinction between entries that truly were not admitted to the ICU vs entries that are removed due to a specified criteria

[gemini-wenb]

Hi Bijun, thanks for including the test cases! They were very helpful and all test cases passed. Just one quick thought: should ICU entries that occur prior to admission be considered NArather than False when as_outcome = T? This would make a clear distinction between entries that truly were not admitted to the ICU vs entries that are removed due to a specified criteria

Thank you for checking out the unit tests Kayley!

Good question about whether ICU entry should be set to False vs NA. In this case, my understanding is we do not want to return NA, whether as_outcome = T or =F, because NA typically denotes missing and indeterminant (i.e. from our data we cannot determine whether icu entry has taken placed per the specified criteria), which is not the case here. Also keep in mind that one patient could have multiple records of ICU entries, and the function only removes records prior to IP-admission (when as_outcome=T with others in default), keeping post IP-admission records associating with the patient into the determining process of ICU entry.

For example, researchers are interested in knowing whether a patient was admitted to ICU as an outcome of the inpatient care. We have Patient A directly entered ICU prior to inpatient admission, this particular entry would not be considered as a result of the inpatient care (because they've never received inpatient care). This Patient A was then admitted to inpatient care. Two scenarios could happen here 1) there is no further record indicating ICU entry post IP admission for this patient; 2) there is at least one record of ICU entry post IP admission for this patient. For 1) it is clear that the patient did not enter ICU post admission, and thus ICU entry as an outcome of the inpatient care is set to FALSE. It is not NA, because the outcome can be clearly determined here. The patient was truly not admitted to ICU per criteria of researcher's interest. If we set this to NA, the patient could be dropped from analysis, although we know this patient's data actually meaningfully reflected quality of inpatient care. For 2) when there is at least one record of ICU entry post IP admission, ICU entry as an outcome of the inpatient care is set to TRUE (because the function only remove records prior to IP admission, and will still pick up icu entries post IP admission).

The function does not return any NA (we noted this in function documentation), because the same logic applies to all other specifications (e.g icu entry within 24 hours).

Does this make sense? Let me know if there are reasons to return things differently that I've missed :)

[marchenaromk]

Thanks that makes a lot of sense! Especially in the case where there could be multiple ICU entries. Thanks for the clarification! Nice work!

[gemini-wenb]

Test cases pass and I can't think of another test case that would be relevant for this function.

Thank you for reviewing the function, Kayley! I will merge this :)