Login
Back to bricks list
Introduction Version

Streamlit

Streamlit is a popular Python package for rapidly building data apps. You can find more information and examples on the Streamlit website: https://streamlit.io/. With this you can integrate interactive dashboards in Constellab that aggregate informations of you experiment or even across multiple experiments.


When you're deploying a Streamlit app in Constellab, the system takes care of deployment, security, and app cleanup, so you don't need to worry about those aspects.



Introduction


To create a streamlit dashboard, you will need to generate a StreamlitApp resource. Here is the documentation about this resource. This is a special resource where the default view is the streamlit interactive dashboard. 



The StreamlitApp contains sub resources which allows you to view others resources that were used in the dashboard. 



Build streamlit app


There is 2 ways of building a StreamlitApp :


  • Through a streamlit live task
    • Though a custom task in you brick

      Live task


      The Streamlit live task is a special type of task that lets you create a Streamlit dashboard app connected to your lab's data. 



      The inputs of the live task will be automatically added to the StreamlitApp and will be ready to use in the streamlit code. The sources variable will contains the list of input resources, similar to the python live task. 


      Here is an example of a simple live task that generates a StreamlitApp. It takes a Table as input to generate an app with the dataframe and the possibility to select 2 columns to generate a scatter plot. 


      # This is a template for a streamlit live task.
      # This generates an app with one dataframe as input. Then the user can select 2 columns to plot a scatter plot.
      
      import plotly.express as px
      import streamlit as st
      from pandas import DataFrame
      
      # Your Streamlit app code here
      st.title("Dashboard example")
      
      # show a table from file_path which is a csv file full width
      if sources:
          df: DataFrame = sources[0].get_data()
      
          # show the dataframe
          st.dataframe(df)
      
          # add a select widget with the columns names with no default value
          # set the selectbox side by side
          col1, col2 = st.columns(2)
      
          with col1:
              x_col = st.selectbox("Select x column", options=df.columns, index=0)
      
          with col2:
              y_col = st.selectbox("Select y column", options=df.columns, index=1)
      
          if x_col and y_col:
              # Generate a scatter plot with plotly express
              fig = px.scatter(df, x=x_col, y=y_col)
              st.plotly_chart(fig)
      

      Here is the result app :




      Custom task


      You can also build a StreamlitApp in you brick. This allows you to complex app with multiple files.



      Create a custom task that has a StreamlitResource as output. In this task you will build the StreamlitResource, add resource to it, set parameters and provide the code for the streamlit dashboard. View StreamlitResource documentation for more information about its methods.


      Inputs


      To add input to you StreamlitResource, simply call the add_resource method. The inputs resources will be available under the sources variable (with the same order as added) in the streamlit code.   


      Any resource can be added to the streamlit app. We recommend added pre-computed data so the streamlit code does not do heavy computation which will result in a slow dashboard. 


      Config


      You can add parameters to generate pre-configured dashboard. It can be useful to limit access to certains data for example. 


      To set the parameters you can call the set_param or set_params methods. The parameters will be available as a dict under the params variable in the streamlit code.


      Code


      You can now provide the code of your streamlit app. To do this you have 2 options:


      Provide a folder (recommended)


      Provide a folder containing you streamlit app code. Call set_streamlit_folder and provide the path of the folder that contains your streamlit code. This allows you to provide a complete app with multiple files.


      Here is few rules for the folder


      • The folder must contains the entry point main.py file.
        • The folder name must start with an underscore so the streamlit code is not executed when the brick is loaded.


          Set code dynamically


          Set code dynamically (from a string) by calling set_streamlit_code. Only call this method is the code is autonomous and doesn't rely on others files (this will not work as only this code will be copied to the streamlit app).


          You can also call the set_streamlit_code_path which will read the contains of the file and save it as dynamic code. 


          Example


          Here is a example of a streamlit app using a folder and multiple files.


          First we create the structure for our StreamlitApp and our task. 



          The folder _dashboard_code contains the streamlit code. The streamlit_generator.py file contains the task that will create the dashboard. The _dashboard_code folder maintains the main.py file (entrypoint for the app). It also contains a sub module plot imported by main.py to work with multiple file. The _dashboard_code folder a a common python module structure. 


          Here is the content of the main.py file. 


          # This is a template for a streamlit live task.
          # This generates an app with one dataframe as input. Then the user can select 2 columns to plot a scatter plot.
          
          from typing import List
          
          import streamlit as st
          from gws_core import Resource
          from pandas import DataFrame
          from plot.plot_generator import generate_scatter_plot
          
          # thoses variable will be set by the streamlit app
          # don't initialize them, there are create to avoid errors in the IDE
          sources: List[Resource]
          params: dict
          
          # Your Streamlit app code here
          st.title(params.get('title'))
          
          # show a table from file_path which is a csv file full width
          if sources:
              df: DataFrame = sources[0].get_data()
          
              # show the dataframe
              st.dataframe(df)
          
              # add a select widget with the columns names with no default value
              # set the selectbox side by side
              col1, col2 = st.columns(2)
          
              with col1:
                  x_col = st.selectbox("Select x column", options=df.columns, index=0)
          
              with col2:
                  y_col = st.selectbox("Select y column", options=df.columns, index=1)
          
              generate_scatter_plot(df, x_col, y_col)
          

          And the content of plot_generator sub file.


          import plotly.express as px
          import streamlit as st
          from pandas import DataFrame
          
          
          def generate_scatter_plot(dataframe: DataFrame, x_col: str, y_col: str) -> None:
              if x_col and y_col:
                  # Generate a scatter plot with plotly express
                  fig = px.scatter(dataframe, x=x_col, y=y_col)
                  st.plotly_chart(fig)
          

          Then we create a task that will generates the StreamlitApp. It takes a table as input and a title as config.


          import os
          
          from gws_core import (ConfigParams, ConfigSpecs, InputSpec, InputSpecs,
                                OutputSpec, OutputSpecs, StreamlitResource, StrParam,
                                Table, Task, TaskInputs, TaskOutputs, task_decorator)
          
          
          @task_decorator("StreamlitGenerator", human_name="Generate dashboard for table",
                          short_description="Task to generate a custom Streamlit dashboard from a table")
          class StreamlitGenerator(Task):
          
              input_specs: InputSpecs = InputSpecs({'table': InputSpec(Table, human_name="Table")})
              output_specs: OutputSpecs = OutputSpecs({
                  'streamlit_app': OutputSpec(StreamlitResource, human_name="Streamlit app")
              })
              config_specs: ConfigSpecs = {
                  'title': StrParam(human_name='Dashboard title')
              }
          
              # retrieve the path of the app folder, relative to this file
              # the dashboard code folder starts with a underscore to avoid being loaded when the brick is loaded
              streamlit_app_folder = os.path.join(
                  os.path.abspath(os.path.dirname(__file__)),
                  "_dashboard_code"
              )
          
              def run(self, params: ConfigParams, inputs: TaskInputs) -> TaskOutputs:
          
                  # build the streamlit resource with the code and the resources
                  streamlit_resource = StreamlitResource()
          
                  # set the input in the streamlit resource
                  table: Table = inputs.get('table')
                  streamlit_resource.add_resource(table)
          
                  # set the param of the streamlit resource
                  title = params.get_value('title')
                  streamlit_resource.set_param('title', title)
          
                  # set the app folder
                  streamlit_resource.set_streamlit_folder(self.streamlit_app_folder)
          
                  return {'streamlit_app': streamlit_resource}
          

          Note that we retrieve the path of the folder relative to the path of the takes file. Never set an hardcoded absolute path in a task, as the brick might be installed in another folder. 


          That's it 🎉, the streamlit app is ready to be used. You can find the complete code of this in the academy brick.


          Use brick classes in streamlit app


          In a streamlit app the gws environment to work with classes from your brick (like resources, tasks, database...) is automatically loaded. With this you can interact with the database to create real time dashboard, generate experiments or report...


          To do this, simply import your classes from your brick.


          Here is an example of a streamlit app that creates an empty experiment when the button is clicked. 


          import streamlit as st
          from gws_core import ExperimentService, Logger, User, CurrentUserService
          
          # Your Streamlit app code here
          st.title("Create experiment app")
          
          if st.button("Create experiment"):
              st.write("Creating experiment")
              Logger.info("Creating experiment from streamlit app")
              # Call gws_core service to create the experiment
              ExperimentService.create_experiment(title="Super streamlit")
          else:
              st.write("No creating")
            


          Develop the streamlit app


          When you're deploying a Streamlit app in Constellab, the system takes care of deployment, security, and app cleanup, so you don't need to worry about those aspects.



          Simple streamlit app (no dependencies to bricks)


          You can develop and test your Streamlit app directly in the Codelab environment. Write your Streamlit app within a folder. Upload file data to your codelab and import those file in your app (you can hardcode the path, they will be removed once integrated in Constellab). 


          Once it's ready, run the Streamlit app using port 8501 with the following command: streamlit run [PATH_TO_FILE] --server.port 8501 --server.allowRunOnSave true. You should see the message: "You can now view your Streamlit app in your browser." The --server.allowRunOnSave option will automatically refresh the app when a file is save, making testing faster.


          To open your app, open the URL: https://dashboard-dev.[LAB].constellab.app. Basically, you need to take the URL of your Codelab, replace "codelab" with "streamlit-dev," and remove everything after "/". This will open the Streamlit app, allowing you to test it.



          Once your app is ready, you can test it within a Streamlit live task and connect it with your data. Replace your input variables with the sources variable and remove the st.set_page_config statement. The app should work as tested in the Codelab.


          /


          Example


          Here is a example of a streamlit app using a folder and multiple files.


          First we create the structure for our StreamlitApp and our task. 




          The folder _dashboard_code contains the streamlit code. The streamlit_generator.py file contains the task that will create the dashboard. The _dashboard_code folder maintains the main.py file (entrypoint for the app). It also contains a sub module plot imported by main.py to work with multiple file. The _dashboard_code folder a a common python module structure. 


          Here is the content of the main.py file. 


          # This is a template for a streamlit live task.
          # This generates an app with one dataframe as input. Then the user can select 2 columns to plot a scatter plot.
          
          from typing import List
          
          import streamlit as st
          from gws_core import Resource
          from pandas import DataFrame
          from plot.plot_generator import generate_scatter_plot
          
          # thoses variable will be set by the streamlit app
          # don't initialize them, there are create to avoid errors in the IDE
          sources: List[Resource]
          params: dict
          
          # Your Streamlit app code here
          st.title(params.get('title'))
          
          # show a table from file_path which is a csv file full width
          if sources:
              df: DataFrame = sources[0].get_data()
          
              # show the dataframe
              st.dataframe(df)
          
              # add a select widget with the columns names with no default value
              # set the selectbox side by side
              col1, col2 = st.columns(2)
          
              with col1:
                  x_col = st.selectbox("Select x column", options=df.columns, index=0)
          
              with col2:
                  y_col = st.selectbox("Select y column", options=df.columns, index=1)
          
              generate_scatter_plot(df, x_col, y_col)
          

            And the content of plot_generator sub file.  


          import plotly.express as px
          import streamlit as st
          from pandas import DataFrame
          
          
          def generate_scatter_plot(dataframe: DataFrame, x_col: str, y_col: str) -> None:
              if x_col and y_col:
                  # Generate a scatter plot with plotly express
                  fig = px.scatter(dataframe, x=x_col, y=y_col)
                  st.plotly_chart(fig)

           Then we create a task that will generates the StreamlitApp. It takes a table as input and a title as config.  


          import os
          
          from gws_core import (ConfigParams, ConfigSpecs, InputSpec, InputSpecs,
                                OutputSpec, OutputSpecs, StreamlitResource, StrParam,
                                Table, Task, TaskInputs, TaskOutputs, task_decorator)
          
          
          @task_decorator("StreamlitGenerator", human_name="Generate dashboard for table",
                          short_description="Task to generate a custom Streamlit dashboard from a table")
          class StreamlitGenerator(Task):
          
              input_specs: InputSpecs = InputSpecs({'table': InputSpec(Table, human_name="Table")})
              output_specs: OutputSpecs = OutputSpecs({
                  'streamlit_app': OutputSpec(StreamlitResource, human_name="Streamlit app")
              })
              config_specs: ConfigSpecs = {
                  'title': StrParam(human_name='Dashboard title')
              }
          
              # retrieve the path of the app folder, relative to this file
              # the dashboard code folder starts with a underscore to avoid being loaded when the brick is loaded
              streamlit_app_folder = os.path.join(
                  os.path.abspath(os.path.dirname(__file__)),
                  "_dashboard_code"
              )
          
              def run(self, params: ConfigParams, inputs: TaskInputs) -> TaskOutputs:
          
                  # build the streamlit resource with the code and the resources
                  streamlit_resource = StreamlitResource()
          
                  # set the input in the streamlit resource
                  table: Table = inputs.get('table')
                  streamlit_resource.add_resource(table)
          
                  # set the param of the streamlit resource
                  title = params.get_value('title')
                  streamlit_resource.set_param('title', title)
          
                  # set the app folder
                  streamlit_resource.set_streamlit_folder(self.streamlit_app_folder)
          
                  return {'streamlit_app': streamlit_resource}
          

          Note that we retrieve the path of the folder relative to the path of the takes file. Never set an hardcoded absolute path in a task, as the brick might be installed in another folder. 


          That's it 🎉, the streamlit app is ready to be used. You can find the complete code of this in the academy brick.


          Run the app in dev mode


          To run the app in dev mode define a dev_config.json file. This file will simulate the real execution when the dashboard is generated by the StreamlitGenerator. Here is the content of the file. 


          {
              "app_dir_path": "", // set the path of the app dir relative to this file's folder.
              "source_ids": [], // provide the list of resource ids stored in the lab
              "params": { // app parameters
                  "title": "Dev mode"
              }
          }

          • app_dir_path : string. Path of the folder containing the streamlit main.py file. It is recommended to set a relative path (relative to the config json file).
            • source_ids : List[string] . You can pass a list of resource input to simulate the real use. The resource must be defined in the dev environment. To find the resource id, open the resource in Constellab dev environment and retrieve the id from the url or open Resource info. The order in the array is important.
              • params : dict. Dictionnary of parameters to pass to the app. The keys must be the same as the keys defined in the StreamlitResource. Here title is the same as when we called streamlit_resource.set_param('title', title)


                Once this file is defined, you can run the streamlit app in dev mode using the following command : gws streamlit run-dev dev_config.json . Find information about the CLI here.


                Custom components


                In gws_core we developed few custom component for streamlit app. They can be imported from gws_streamlit_helper package. 


                You can find the code of those component here.


                Dataframe paginator


                Streamlit doesn't have a way of paginate big dataframe natively. You can use the dataframe_paginated method from gws_streamlit_helper. It support row and column pagination.


                Here is an example on how to use it:


                from gws_streamlit_helper import dataframe_paginated
                from pandas import DataFrame
                
                my_df : DataFrame = sources[0]
                
                dataframe_paginated(my_df, paginate_rows=True, row_page_size_options=[50,100 ,250], 
                                   paginate_columns=False, column_page_size_options=None)

                Troubleshoot


                Connecting / Connection lost / Connection timed out


                If you encounter connection issues such as "Connecting/Connection lost/Connection timed out" when opening the Streamlit app, please close the resource or view and then reopen it. This should resolve the issue and allow you to use the app again.


                Port 8501 already is use


                When developing a streamlit app, if you encounter error 'Port 8501 already is use', this means that you have another streamlit app that is already running. Streamlit app can be running : 


                • in a terminal of the codelab, in this case, kill the terminal
                  • in the lab in dev mode. In Monitoring > Other > Streamlit app you can check if there is an app running and stop it. You can also kill the dev environment.

                    If you can't find the running streamlit app, another solution might be to restart the lab from the lab manager section.