Package: covid19-dashboard-lbiragnet
Welcome to the Covid-19 Dashboard Documentation!IntroductionThis Covid Dashboard Application was developped as part of my coursework for programming. It displays current coronavirus data, such as the number of infections in the past 7 days, the number of hospital cases, etc., as well as up to date news articles from various sources.The application is built using Python, and uses Flask to run on a local server. It uses live data from the uk-covid19 API, and NewsAPI for news articles.PrerequisitesThe application requires a version of Python that is at least 3.8.0 or above.Certain packages / modules are also required to be installed:osschedtimedatetimerequestscsvjsonloggingThese can be installed via pip in the command line:$ pip install <package>InstallationYou can download the application directly from GitHub, athttps://github.com/lbiragnet/covid_dashboard_lbiragnetby clicking "Download ZIP" and then extracting the files to the application of your choice.The application is also available as a Python package on PyPi. It can be installed using pip in the command line:$ pip install covid19_dashboard_lucbiragnetGetting StartedConfiguring the applicationOnce the application has been installed, it needs to be configured using your chosen location and API key. These are necessary to extract the correct data from the uk-covid19 api, and to provide access to the news api. You can register for an API key onhttps://newsapi.org/. This will usually look like a long sequence of different characters. Do not share your API key, as this might lead to you losing access to the news API.If you have download the application from GitHub, navigate to the application folder namedcovid19_dashboard_lbiragnetand head over to\src\configand openconfig.json. This will open the application configuration file.If installed using pip, the configuration file will most likely be under a different directory.Enter your API key in quotation marks in theAPI keysection.The configuration file can be edited for covid data to correspond to the location of your choice: to do this, enter the name of your chosen city in quotation marks in thelocationsection, which is set toExeterby default. Thelocation typesection can also be modified. The full list of valid metrics for this section can be found in the uk-covid19 api documentation athttps://coronavirus.data.gov.uk/details/developers-guide/main-api#methods-get. TheOutput Formatsection defines which data is requested to the uk-covid19 API. Note that modifying this section will require the source code to be changed in order to process the data accordingly.Running the applicationOnce the application has been configured with your API key and the location of your choice, navigate to the src folder via the command line. To run the application, type:$ python -m mainThe application will be run on a local server, and will be accessible in your browser at the address:http://127.0.0.1:5000/index.The dashboard contains an updates section (on the left), a covid data section (in the center), and a news articles section (on the right). The bottom section also allows you to schedule updates for covid data and/or news articles.Note that the dashboard will retain full functionality as long as it is being run. Exiting or interrupting the command line when the application is running will stop the execution. Any scheduled updates will be deleted.Covid DataThe Dashboard provides up-to-date covid data, including the following metrics:The local 7-day infection rateThe national 7-day infection rateThe national number of hospital casesThe national number of cumulative deathsThese metrics can be modified in the configuration file, but it will also be necessary to change the source code in order to process different metrics, as well as the html code for the dashboard to correctly label the different data.Scheduling updatesThe dashboard allows you to schedule updates to the covid data and news articles. If no updates have been scheduled, the left side of the dashboard will appear empty. To schedule an update, first enter the name of your update in the designated area. Then, enter the time at which you wish the update to occur in the designated area. You are then able to check three different options:Update Covid data (updates the covid data using the uk covid-19 API)Update news articles (updates the news articles using the newsAPI)Repeat update (repeats the update every 24 hours)Scheduled updates will then be displayed in the left section of the dashboard, and will be labelled using the name given to them by the user.Checking certain options will schedule the relevant update (covid data or news articles) at the given time, and will repeat every 24 hours if "Repeat" is checked. Checking both the "Update Covid data" and "Update news articles" options will schedule a separate double update (covid data and news articles), which can be repeated. Hence there are three types of updates: covid data updates, news articles updates and double updates. Note that scheduling an update of a certain type at the same time as another of the same type will fail. When scheduling a double update, this applies if an update of any kind has already been scheduled at the same time.Repeating updatesIf an update has been scheduled as a repeated update, the dashboard will schedule a (repeat) update with the same name as the initial update, 24 hours after the inital update is completed. Note that the dashboard will only generate a single repeated update: this avoids an infinite number of updates from being displayed on the dashboard. However, the repeated update will also repeat itself 24 hours later.Cancelling updatesUpdates shown in the updates section can be cancelled by clicking the dismiss button. For repeated updates, both the update and its repetition will need to be cancelled in order for the "repetition" cycle to be cancelledDeleting news articlesThe dashboard displays a list of 7 news articles on its right section, each of which contains a title and relevant content. The articles can be individually deleted by clicking the dismiss button. This will add a new article to the list, and this process can be repeated as many times as the number of articles received from the newsAPI (which is very large) if these are not updated, giving the user the possibility to consult multiple articles.Exiting the applicationThe application can be exited by terminating it in the command line (Ctrl + C for Windows), or by closing the command line.TestingThe application comes with a variety of tests designed to verify that the different modules are functioning correctly. Hence thetestsfolder within the application folder contains tests for multiple functions included in the application modules. The tests are grouped within modules, each containing test functions of one particular module.Running the tests requires thepytestmodule, which can be installed using pip. To run the tests, open the command line navigate to thesrcfolder within thecovid19-dashboard-lbiragnetfolder:$ cd <path to the application folder>\covid19-dashboard-lbiragnet\srcThen type:$ python -m pytestAfter a few seconds, the tests will have completed and pytest will return a detailed report describing their outcomes and the potential errors which were encountered.Developer DocumentationThe source code contains 4 Python modules:main.pycovid_data_handler.pycovid_news_handling.pytime_calculations.pyThe source code also includes:A configuration fileconfig.jsonA logging fileapp.logA sample csv data filenation_2021-10-28.csvData files stored in thedatafilesfolderAn html templateindex.htmlA PNG image stored in\static\imagesTest files stored in\testsThe__init__.pyfile used to package the source codemain moduleNAMEmain - Main application moduleDESCRIPTIONThis module runs a COVID-19 Dashboard application.
It contains the main logic of the application.
It also defines functions to schedule and remove updates, and add and remove news articles.FUNCTIONSadd_news() -> list
    Adds a news article to the dashboard when one is deleted by the user

    The function goes through the news articles list pulled from the news API.
    If an article has not been deleted by the user and is not currently displayed,
    the function then adds it to the list of articles displayed on the dashboard.

index() -> None
    Returns the html template as an interactive dashboard on a local server

    The function is triggered when the user accesses the application
    Updates schedulers are set to run.
    The function requests arguments from the url when the user interacts with the dashboard.
    The function schedule/cancels updates and adds/removes articles when prompted by the user.
    The function returns the html template with data from the APIs at http://127.0.0.1:5000/index

remove_update(update: dict) -> list
    Removes an update that is deleted by the user from the list of updates

    The function checks if an update deleted by the user is in the list of updates.
    If it is in the list, the update is removed from the list.
    Arguments:
    | update -- dictionary containing details about an update (an item of the updates list)

schedule_data_update(data_update_name: str, data_update_time: str, data_update_repeat: str) -> list
    Schedules a covid data update at a given time

    The function calculates the epoch time of the update given by the user.
    If there isn't already a covid data update scheduled at the same time,
    The planned update is added to the updates list and dictionary,
    And a scheduled event is added to the covid data updates scheduler.
    The function returns both the updates list and the covid data updates list.
    Arguments:
    | data_update_name -- the name of the update given by the user
    | data_update_time -- the time of the update given by the user
    | data_update_repeat -- set to "repeat" if the update is to be repeated

schedule_double_updates(update_name: str, update_time: str, update_repeat: str) -> list
    Schedules a double (news and covid data) update at a given time

    The function calculates the epoch time of the update given by the user.
    If there isn't already a double update scheduled at the same time,
    The planned update is added to the updates list and dictionary,
    And a scheduled event is added to the double updates scheduler.
    The function returns both the updates list and the double updates list.
    Arguments:
    | update_name -- the name of the update given by the user
    | update_time -- the time of the update given by the user
    | update_repeat -- set to "repeat" if the update is to be repeated

schedule_news_update(news_update_name: str, news_update_time: str, news_update_repeat: str) -> list
    Schedules a news update at a given time

    The function calculates the epoch time of the update given by the user.
    If there isn't already a news update scheduled at the same time,
    The planned update is added to the updates list and dictionary,
    And a scheduled event is added to the news updates scheduler.
    The function returns both the updates list and the news updates list.
    Arguments:
    | news_update_name -- the name of the update given by the user
    | news_update_time -- the time of the update given by the user
    | news_update_repeat -- set to "repeat" if the update is to be repeated

update_covid_data()
    Updates covid data

    The function requests updated data from the covid-19 API.
    Variables containing the current covid data are redefined to update the data.

update_data_and_news() -> None
    Combines the update_covid_data and update_news_articles functions into one function

update_news_articles() -> list
    Updates news articles

    The function requests updated news articles from the news API.
    The news variable displaying the articles is redefined to update the articles.DATACANCELED_DATA_UPDATES = []

CANCELED_DOUBLE_UPDATES = []

CANCELED_NEWS_UPDATES = []

DATA_UPDATE_SCHEDULER = <sched.scheduler object>

DOUBLE_UPDATE_SCHEDULER = <sched.scheduler object>

NEWS_UPDATE_SCHEDULER = <sched.scheduler object>

SCHEDULED_DATA_UPDATES = []

SCHEDULED_DOUBLE_UPDATES = []

SCHEDULED_NEWS_UPDATES = []

UPDATES_DICT = {}

UPDATES_LIST = []

app = <Flask 'main'>

request = <LocalProxy unbound>covid_data_handler moduleNAMEcovid_data_handler - This module handles the covid data section of the dashboardFUNCTIONScovid_API_request(location: str = 'Exeter', location_type: str = 'ltla') -> <module 'json' from 'C:\\Users\\luc biragnet\\AppData\\Local\\Programs\\Python\\Python39\\lib\\json\\__init__.py'>
    Retrieve live covid data from the uk covid-19 API

    The function requests data from the covid-19 API using the given arguments
    The response is returned in the json format
    Arguments:
    | location -- the location given by the user
    | location_type -- the location type given by the user

get_covid_data() -> <module 'json' from 'C:\\Users\\luc biragnet\\AppData\\Local\\Programs\\Python\\Python39\\lib\\json\\__init__.py'>
    Retrieve live covid data from the uk covid-19 API

    The function requests data from the covid-19 API the filters and structure arguments.
    These can be modified by the user from the configuration file.
    The function makes a request for local data and another for national data.
    Both responses are then returned in the json format.

parse_csv_data(csv_filename: str) -> list
    Return the data from the csv file as a list

    csv_filename is a csv file
    The function turns the data from this file into a list
    Each item of the list is a list, the first of which specifies how the data is formatted.
    Each further item corresponds to a particular day (following the most recent order)

process_covid_csv_data(covid_csv_data: list) -> int
    Process the parsed covid csv data to return basic data to the user

    The function returns the number of cases in the past 7 days,
    The number of hospital cases, and the number of cumulative deaths
    Arguments:
    | covid_csv_data -- list containing the covid data as would be returned by parse_csv_data

process_live_covid_data(local_data: dict, national_data: dict) -> int
    Process live covid data to return basic data to the user

    The function calculates the number of local cases in the past 7 days.
    The function calculates the number of national cases in the past 7 days.
    The function retrieves the most recent number of nationwide hospital cases.
    The function retrieves the most recent number of nationwide cumulative deaths.
    The function returns these numbers.
    Arguments:
    | local_data -- local data in json format as returned by the get_covid_data function
    | national_data -- national data in json format as returned by the get_covid_data function

schedule_covid_updates(update_interval: str, update_name: str)
    Schedule a covid data update
    The function creates a scheduler object.
    An event is added at a given time interval, to update the data.
    The function returns the name of the update, and the time interval at which it is scheduled
    Arguments:
    | update_interval -- the interval time of the update as given by the user
    | update_name -- the name of the scheduled update as given by the user

update_data() -> <module 'json' from 'C:\\Users\\luc biragnet\\AppData\\Local\\Programs\\Python\\Python39\\lib\\json\\__init__.py'>
    Update covid data for a scheduled update

    The function uses the covid_API_request function to update the data.DATACONFIG_DATA = {'Covid Data Configuration': {'Location': 'Exeter', 'Loc...

COVID_DATA_FILTERS = ['areaType=ltla', 'areaName=Exeter']

OUTPUT_FORMAT = {'areaCode': 'areaCode', 'areaName': 'areaName', 'cumC...

config_file = <_io.TextIOWrapper name='./config/config.json' mode='r' ...covid_news_handling moduleNAMEcovid_news_handling - This module handles the news articles section of the dashboardFUNCTIONSnews_API_request(covid_terms: str = 'Covid COVID-19 coronavirus') -> dict
    Request news articles from the news api in the json format

    The covid_terms argument is formatted for the API request: <term> OR <term> OR <term>...
    The function requests news articles whose titles include relevant terms as given in the argument
    The articles are sorted by popularity and are at most from the previous day
    The response is returned in the json format.
    Arguments:
    | covid_terms -- terms to look for in article titles when retrieving articles from the API

select_articles(news_dict_list: dict) -> list
    Select a limited number of articles which have not been deleted by the user

    The function returns a list of 7 articles from the API response returned by news_API_request
    It is also executed when the page is refreshed, allowing the removal of deleted articles.
    Arguments:
    | news_dict_list -- list of dictionaries (news articles), as returned by news_API_request

update_news(article) -> list
    Updates news articles

    The function adds a news article to the list of current articles
    The list of updated articles is returned.DATAAPI_KEY = ''

CONFIG_NEWS = {'Covid Data Configuration': {'Location': 'Exeter', 'Loc...

config_file = <_io.TextIOWrapper name='./config/config.json' mode='r' ...

news_articles = []time_calculations moduleNAMEtime_calculations - This module includes functions used for calculations including timeFUNCTIONScalc_update_epoch_interval(update_time_hhmm: str) -> float
    Calculate interval between current epoch time and update epoch time

calc_update_interval(update_time_hhmm: str) -> int
    Calculates interval in seconds between current time and scheduled time for an update

current_time_hhmm() -> str
    Returns local time in the HH:MM format

hhmm_to_seconds(hhmm: str) -> int
    Converts time in the HH:MM format to seconds

hours_to_minutes(hours: str) -> int
    Converts hours to minutes

minutes_to_seconds(minutes: str) -> int
    Converts minutes to secondsDetailsAuthorsLuc Biragnet (Python)Matt Collison (HTML/Flask template)LicenseCopyright (c) [2021] [Luc Biragnet]Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.AcknowledgementsI would like to thank Matt Collison for his guidance and help throughout the project!