Building Time Series Visualization

• Building Time Series Visualization
  • Installation Manual
    • Git Large File Storage
    • Clone the Repository
    • Run in Docker
    • Run Natively
    • App Usage
  • Documentation
  • Test Suite
    • Coverage Report
  • Demos
    • Dataset Abstraction
    • Running the App in Test Mode

Installation Manual

Git Large File Storage

This repository uses Git Large File Storage to manage its large datasets. Download and install Git LFS from https://git-lfs.com/. Once downloaded and installed, set up GitLFS for your user account by running:

git lfs install

Clone the Repository

Clone the repository, then to retrieve the datasets, in the root directory of the repository run:

git lfs pull

Run in Docker

Ensure you have the Docker Engine installed and that Docker is running.

In the root directory of the repository run:

docker compose up

It may take up to 5 minutes to build the image for the first time. Once built, it may take a minute to ingest the dataset and run the analyses. You'll see a progress meter in the terminal, but once complete you should see that Dash is running on http://0.0.0.0:8050/.

Open http://127.0.0.1:8050 in your browser.

Run Natively

The app was developed and tested with Python 3.12, and it is recommended to use the same version for compatibility.

Create a virtual environment for the app:

python -m venv .venv

Activate the virtual environment (see Python Docs for commands on other platforms):

source .venv/bin/activate

Install the dependencies:

pip install -r requirements.txt

Run the app:

python src/app.py --building B \
    datasets/bts_site_b_train/train.zip \
    datasets/bts_site_b_train/mapper_TrainOnly.csv \
    datasets/bts_site_b_train/Site_B.ttl \
    datasets/bts_site_b_train/Brick_v1.2.1.ttl

It may take a minute to ingest the dataset and run the analyses. You'll see a progress meter in the terminal, but once complete you should see that Dash is running on http://127.0.0.1:8050/.

Open http://127.0.0.1:8050 in your browser.

App Usage

Help is available by passing the -h or --help options, e.g.:

python src/app.py -h

Documentation

Documentation is automatically generated upon changes to the main branch and published on GitHub Pages:

https://fluffy-broccoli-nvjrm9y.pages.github.io/

For further information on generating this documentation see the docs directory.

Test Suite

A comprehensive test suite is provided, requiring additional dependencies to be installed:

pip install -r src/tests/requirements.txt

Once installed, from the root directory all tests can be run with:

pytest

A test coverage report may be generated while running the tests with:

pytest --cov=src

Please note, end-to-end tests assume Chrome is installed.

Coverage Report

The test suite is automatically run upon changes to the main branch, and the updated coverage report is published on GitHub Pages:

https://fluffy-broccoli-nvjrm9y.pages.github.io/coverage/

This report does not include callback functions, which are challenging to unit test due to their inherent connection to the UI and interdependent components, meaning they’re likely not fully captured by coverage reports. These functions are, however, still tested as part of the end-to-end testing suite.

Demos

Dataset Abstraction

All analytical modules share a common abstraction of the dataset, provided by src/analytics/dbmgr.py.

A Jupyter Notebook is provided in demos/dbmgr.ipynb to demonstrate its main capabilities and usage.

This requires additional dependencies, which may be installed by running:

pip install -r demos/requirements.txt

Running the App in Test Mode

The app may be run in test mode by passing the -t or --test-mode options, e.g.:

python src/app.py -t

This will utilise sample data and plot configurations, as found in src/sampledata/plot_configs.py, and is useful to understand how analytical results can be transformed into UI components.