Added checkbox for switching charts to logarithmic scale on the y-axis

Author: psahgal

src/penn_chime/model/parameters.py

@@ -136,6 +136,7 @@ def validate(string):
     "ventilated": ValDisposition,
     "hospitalized": ValDisposition,
     "icu": ValDisposition,
+    "use_log_scale": OptionalValue
 }
 
 
@@ -160,16 +161,17 @@ def validate(string):
     "relative_contact_rate": "Social distancing reduction rate: 0.0 - 1.0",
     "ventilated_days": "Average days on ventilator",
     "ventilated_rate": "Ventilated Rate: 0.0 - 1.0",
+    "use_log_scale": "Flag to use logarithmic scale on charts instead of linear scale."
 }
 
 
 ARGS = (
     (
         "parameters",
         str,
-        None,
-        None,
-        False,
+        None, # Min value
+        None, # Max value
+        False, # Whether it is required or optional.
     ),
     (
         "current_hospitalized",
@@ -297,15 +299,24 @@ def validate(string):
         1.0,
         True,
     ),
+    (
+        "use_log_scale",
+        bool,
+        None,
+        None,
+        False
+    )
 )
 
 
 def to_cli(name):
     return "--" + name.replace('_', '-')
 
-
 class Parameters:
-    """Parameters."""
+    """
+    Object containing all of the parameters that can be adjusted by the user, either from the command line or using
+    the side bar of the web app.
+    """
 
     @classmethod
     def parser(cls):
@@ -314,11 +325,20 @@ def parser(cls):
 
         for name, cast, min_value, max_value, required in ARGS:
             arg = to_cli(name)
-            parser.add_argument(
-                arg,
-                type=validator(arg, cast, min_value, max_value, required),
-                help=HELP.get(name),
-            )
+            if cast == bool:
+                # This argument is a command-line flag and does not need validation.
+                parser.add_argument(
+                    arg,
+                    action='store_true',
+                    help=HELP.get(name),
+                )
+            else:
+                # Use a custom validator for any arguments that take in values.
+                parser.add_argument(
+                    arg,
+                    type=validator(arg, cast, min_value, max_value, required),
+                    help=HELP.get(name),
+                )
         return parser
 
     @classmethod
@@ -395,6 +415,7 @@ def __init__(self, **kwargs):
         self.relative_contact_rate = None
         self.recovered = None
         self.ventilated = None
+        self.use_log_scale = False
 
         passed_and_default_parameters = {}
         for key, value in kwargs.items():

src/penn_chime/view/charts.py

@@ -1,21 +1,33 @@
 from typing import Dict, Optional
 
-from altair import Chart
+from altair import Chart, Scale
 import pandas as pd
 import numpy as np
 
 from ..constants import DATE_FORMAT
 
 
 def build_admits_chart(
-    *, alt, admits_floor_df: pd.DataFrame, max_y_axis: Optional[int] = None
+    *, alt, admits_floor_df: pd.DataFrame, max_y_axis: Optional[int] = None, use_log_scale: bool = False
 ) -> Chart:
-    """Build admits chart."""
-    y_scale = alt.Scale()
-    if max_y_axis is not None:
-        y_scale.domain = (0, max_y_axis)
+    """
+    This builds the "New Admissions" chart, projecting daily admissions over time.
 
-    x = dict(shorthand="date:T", title="Date", axis=alt.Axis(format=(DATE_FORMAT)))
+    Args:
+        alt: Reference to Altair package.
+        admits_floor_df: Pandas data frame containing three columns: "admits_hospitalized", "admits_icu", and
+        "admits_ventilated".
+        max_y_axis: Optional maximum value for the Y axis of the chart.
+        use_log_scale: Set to true to use a logarithmic scale on the Y axis. Default is linear scale.
+
+    Returns: The newly created chart.
+
+    """
+
+    adjusted_admits_floor_df = __adjust_data_for_log_scale(admits_floor_df) if use_log_scale else admits_floor_df
+    y_scale = __build_y_scale(alt, max_y_axis, use_log_scale)
+
+    x = dict(shorthand="date:T", title="Date", axis=alt.Axis(format=DATE_FORMAT))
     y = dict(shorthand="value:Q", title="Daily admissions", scale=y_scale)
     color = "key:N"
     tooltip = ["date:T", alt.Tooltip("value:Q", format=".0f", title="Admit"), "key:N"]
@@ -40,19 +52,31 @@ def build_admits_chart(
         .mark_rule(color="black", opacity=0.35, size=2)
     )
     return (
-        alt.layer(points, bar, data=admits_floor_df)
+        alt.layer(points, bar, data=adjusted_admits_floor_df)
         .configure_legend(orient="bottom")
         .interactive()
     )
 
 
 def build_census_chart(
-    *, alt, census_floor_df: pd.DataFrame, max_y_axis: Optional[int] = None
+    *, alt, census_floor_df: pd.DataFrame, max_y_axis: Optional[int] = None, use_log_scale: bool = False
 ) -> Chart:
-    """Build census chart."""
-    y_scale = alt.Scale()
-    if max_y_axis:
-        y_scale.domain = (0, max_y_axis)
+    """
+    This builds the "Admitted Patients" census chart, projecting total number of patients in the hospital over time.
+
+    Args:
+        alt: Reference to Altair package.
+        census_floor_df: Pandas data frame containing three columns: "census_hospitalized", "census_icu", and
+        "census_ventilated".
+        max_y_axis: Optional maximum value for the Y axis of the chart.
+        use_log_scale: Set to true to use a logarithmic scale on the Y axis. Default is linear scale.
+
+    Returns: The newly created chart.
+
+    """
+
+    adjusted_census_floor_df = __adjust_data_for_log_scale(census_floor_df) if use_log_scale else census_floor_df
+    y_scale = __build_y_scale(alt, max_y_axis, use_log_scale)
 
     x = dict(shorthand="date:T", title="Date", axis=alt.Axis(format=(DATE_FORMAT)))
     y = dict(shorthand="value:Q", title="Census", scale=y_scale)
@@ -79,19 +103,31 @@ def build_census_chart(
         .mark_rule(color="black", opacity=0.35, size=2)
     )
     return (
-        alt.layer(points, bar, data=census_floor_df)
+        alt.layer(points, bar, data=adjusted_census_floor_df)
         .configure_legend(orient="bottom")
         .interactive()
     )
 
 
 def build_sim_sir_w_date_chart(
-    *, alt, sim_sir_w_date_floor_df: pd.DataFrame, max_y_axis: Optional[int] = None
+    *, alt, sim_sir_w_date_floor_df: pd.DataFrame, max_y_axis: Optional[int] = None, use_log_scale: bool = False
 ) -> Chart:
-    """Build sim sir w date chart."""
-    y_scale = alt.Scale()
-    if max_y_axis is not None:
-        y_scale.domain = (0, max_y_axis)
+    """
+    This builds the "Susceptible, Infected, and Recovered" chart, projecting the number of those individuals in the
+    hospital's region over time.
+
+    Args:
+        alt: Reference to the Altair package.
+        sim_sir_w_date_floor_df: A Pandas data frame with columns named "susceptible", "infected", and "recovered".
+        max_y_axis: Optional maximum value for the Y axis of the chart.
+        use_log_scale: Set to true to use a logarithmic scale on the Y axis. Default is linear scale.
+
+    Returns: The newly created chart.
+
+    """
+
+    adjusted_sim_sir_w_date_floor_df = __adjust_data_for_log_scale(sim_sir_w_date_floor_df) if use_log_scale else sim_sir_w_date_floor_df
+    y_scale = __build_y_scale(alt, max_y_axis, use_log_scale)
 
     x = dict(shorthand="date:T", title="Date", axis=alt.Axis(format=(DATE_FORMAT)))
     y = dict(shorthand="value:Q", title="Count", scale=y_scale)
@@ -118,7 +154,7 @@ def build_sim_sir_w_date_chart(
         .mark_rule(color="black", opacity=0.35, size=2)
     )
     return (
-        alt.layer(points, bar, data=sim_sir_w_date_floor_df)
+        alt.layer(points, bar, data=adjusted_sim_sir_w_date_floor_df)
         .configure_legend(orient="bottom")
         .interactive()
     )
@@ -131,3 +167,37 @@ def build_table(
     table_df.date = table_df.date.dt.strftime(DATE_FORMAT)
     table_df.rename(labels)
     return table_df
+
+
+def __adjust_data_for_log_scale(dataframe: pd.DataFrame) -> pd.DataFrame:
+    """
+    This will clean and adjust some of the data so that Altair can plot it using a logarithmic scale. Altair does not
+    allow zero values on the Y axis when plotting with a logarithmic scale, as log(0) is undefined.
+
+    Args:
+        dataframe: The data to plot on the chart.
+
+    Returns: A new data frame with the appropriate adjustments for plotting on a log scale.
+
+    """
+    return dataframe.replace(0, float('nan'))  # We use NaN so that the values will not appear at all on the chart.
+
+
+def __build_y_scale(alt, max_y_axis: Optional[int] = None, use_log_scale: bool = False) -> Scale:
+    """
+    Creates the Y axis of the chart, taking into account some of the configuration parameters set by the user.
+
+    Args:
+        alt: Reference to Altair package.
+        max_y_axis: The maximum value of the Y axis. This is optional.
+        use_log_scale: Whether to use a logarithmic scale instead of a linear scale.
+
+    Returns: A newly created Scale instance.
+
+    """
+    scale_type = 'log' if use_log_scale else 'linear'
+    y_scale = alt.Scale(type=scale_type)
+    if max_y_axis is not None:
+        y_scale.domain = (0, max_y_axis)
+
+    return y_scale

src/penn_chime/view/st_app.py

@@ -36,7 +36,7 @@ def main():
 
     st.subheader("New Admissions")
     st.markdown("Projected number of **daily** COVID-19 admissions.")
-    admits_chart = build_admits_chart(alt=alt, admits_floor_df=m.admits_floor_df, max_y_axis=p.max_y_axis)
+    admits_chart = build_admits_chart(alt=alt, admits_floor_df=m.admits_floor_df, max_y_axis=p.max_y_axis, use_log_scale=p.use_log_scale)
     st.altair_chart(admits_chart, use_container_width=True)
     display_download_link(
         st,
@@ -46,7 +46,7 @@ def main():
 
     st.subheader("Admitted Patients (Census)")
     st.markdown("Projected **census** of COVID-19 patients, accounting for arrivals and discharges.")
-    census_chart = build_census_chart(alt=alt, census_floor_df=m.census_floor_df, max_y_axis=p.max_y_axis)
+    census_chart = build_census_chart(alt=alt, census_floor_df=m.census_floor_df, max_y_axis=p.max_y_axis, use_log_scale=p.use_log_scale)
     st.altair_chart(census_chart, use_container_width=True)
     display_download_link(
         st,
@@ -56,7 +56,7 @@ def main():
 
     st.subheader("Susceptible, Infected, and Recovered")
     st.markdown("The number of susceptible, infected, and recovered individuals in the hospital catchment region at any given moment")
-    sim_sir_w_date_chart = build_sim_sir_w_date_chart(alt=alt, sim_sir_w_date_floor_df=m.sim_sir_w_date_floor_df)
+    sim_sir_w_date_chart = build_sim_sir_w_date_chart(alt=alt, sim_sir_w_date_floor_df=m.sim_sir_w_date_floor_df, use_log_scale=p.use_log_scale)
     st.altair_chart(sim_sir_w_date_chart, use_container_width=True)
     display_download_link(
         st,

src/penn_chime/view/st_display.py

@@ -174,10 +174,10 @@ def __init__(self, st_obj, label, value=None, key=None):
 
 
 def display_sidebar(st, d: Parameters) -> Parameters:
-    # Initialize variables
-    # these functions create input elements and bind the values they are set to
-    # to the variables they are set equal to
-    # it's kindof like ember or angular if you are familiar with those
+    """
+    Initializes the UI in the sidebar. These function calls create input elements, and bind the values they are set to
+    to the appropriate variables. It's similar to Ember or Angular, if you are familiar with those frameworks.
+    """
 
     st_obj = st.sidebar
     # used_widget_key = st.get_last_used_widget_key ( )
@@ -364,7 +364,9 @@ def display_sidebar(st, d: Parameters) -> Parameters:
         max_y_axis = max_y_axis_input()
 
     current_date = current_date_input()
-    #Subscribe implementation
+    use_log_scale = st.sidebar.checkbox(label="Use logarithmic scale on charts instead of linear scale.", value=d.use_log_scale)
+
+    # Subscribe implementation
     subscribe(st_obj)
 
     return Parameters(
@@ -389,9 +391,10 @@ def display_sidebar(st, d: Parameters) -> Parameters:
         ventilated=Disposition.create(
             rate=ventilated_rate,
             days=ventilated_days),
+        use_log_scale=use_log_scale
     )
 
-#Read the environment variables and cteate json key object to use with ServiceAccountCredentials
+# Read the environment variables and create json key object to use with ServiceAccountCredentials
 def readGoogleApiSecrets():
     client_secret = {}
     os.getenv

tests/penn_chime/view/test_charts.py

@@ -1,5 +1,6 @@
 import altair as alt
 import pytest
+import math
 
 from penn_chime.view.charts import (
     build_admits_chart,
@@ -8,7 +9,6 @@
 
 DISPOSITION_KEYS = ("hospitalized", "icu", "ventilated")
 
-
 def test_admits_chart(admits_floor_df):
     chart = build_admits_chart(alt=alt, admits_floor_df=admits_floor_df)
     assert isinstance(chart, (alt.Chart, alt.LayerChart))
@@ -28,3 +28,54 @@ def test_census_chart(census_floor_df):
     # test fx call with no params
     with pytest.raises(TypeError):
         build_census_chart()
+
+def test_admits_chart_log_scale(admits_floor_df):
+    """
+    Verifies that if the log scale is used, then the values on the chart are adjusted appropriately.
+
+    Args:
+        admits_floor_df: Sample admission data.
+
+    """
+    chart = build_admits_chart(alt=alt, admits_floor_df=admits_floor_df, use_log_scale=True)
+
+    # We check a few values to verify that zero was replaced with NaN.
+    assert chart.data.iloc[1].admits_hospitalized == 2
+    assert math.isnan(chart.data.iloc[1].admits_icu)
+    assert math.isnan(chart.data.iloc[1].admits_ventilated)
+
+    assert chart.data.iloc[2].admits_hospitalized == 2
+    assert math.isnan(chart.data.iloc[2].admits_icu)
+    assert math.isnan(chart.data.iloc[2].admits_ventilated)
+
+    assert chart.data.iloc[3].admits_hospitalized == 3
+    assert math.isnan(chart.data.iloc[3].admits_icu)
+    assert math.isnan(chart.data.iloc[3].admits_ventilated)
+
+    assert chart.data.iloc[4].admits_hospitalized == 3
+    assert chart.data.iloc[4].admits_icu == 1
+    assert math.isnan(chart.data.iloc[4].admits_ventilated)
+
+def test_census_chart_log_scale(census_floor_df):
+    """
+    Verifies that if the log scale is used, then the values on the chart are adjusted appropriately.
+
+    Args:
+        census_floor_df: Sample census data.
+
+    """
+    chart = build_census_chart(alt=alt, census_floor_df=census_floor_df, use_log_scale=True)
+
+    # We check a few values to verify that zero was replaced with NaN.
+    assert math.isnan(chart.data.iloc[0].census_hospitalized)
+    assert math.isnan(chart.data.iloc[0].census_icu)
+    assert math.isnan(chart.data.iloc[0].census_ventilated)
+
+    assert chart.data.iloc[1].census_hospitalized == 3
+    assert chart.data.iloc[1].census_icu == 1
+    assert chart.data.iloc[1].census_ventilated == 1
+
+    assert chart.data.iloc[2].census_hospitalized == 6
+    assert chart.data.iloc[2].census_icu == 2
+    assert chart.data.iloc[2].census_ventilated == 2
+