Merge branch 'chore/documentation' docs first draft

README.md

@@ -6,7 +6,7 @@ colorTo: red
 sdk: streamlit
 sdk_version: 1.39.0
 python_version: "3.10"
-app_file: call_models/entry_and_hotdog.py
+app_file: src/main.py
 pinned: false
 license: apache-2.0
 short_description: 'SDSC Hackathon - Project 10. '

app.py

@@ -1 +0,0 @@
-call_models/entry_and_hotdog.py

dev/call_hf_batch.py

@@ -0,0 +1,94 @@
+import os
+from huggingface_hub import HfApi
+import cv2
+from pathlib import Path
+import pandas as pd
+
+from transformers import pipeline
+from transformers import AutoModelForImageClassification
+import time
+
+'''
+how to use this script:
+1. get data from the kaggle competition, including images and the train.csv file
+edit the "base" variable, assuming the following layout
+
+ceteans/
+├── images
+│   ├── 00021adfb725ed.jpg
+│   ├── 000562241d384d.jpg
+│   ├── ...
+└── train.csv
+
+2. inspect the df_results dataframe to see how the model is performing
+
+
+'''
+# setup for the ML model on huggingface (our wrapper)
+os.environ["PROTOCOL_BUFFERS_PYTHON_IMPLEMENTATION"] = "python"
+rev = 'main'
+
+# load the model
+cetacean_classifier = AutoModelForImageClassification.from_pretrained(
+    "Saving-Willy/cetacean-classifier", 
+    revision=rev,
+    trust_remote_code=True)
+
+# get ready to load images
+base = Path('~/Documents/ceteans/').expanduser()
+df = pd.read_csv(base / 'train.csv')
+
+i_max = 100 # put a limit on the number of images to classify in this test (or None)
+
+# for each file in the folder base/images, 1/ load image, 2/ classify, 3/ compare against the relevant row in df
+# also keep track of the time it takes to classify each image
+
+
+classifications = []
+
+img_pth = base / 'images'
+img_files = list(img_pth.glob('*.jpg'))
+
+
+for i, img_file in enumerate(img_files):
+    # lets check we can get the right target.
+    img_id = img_file.name # includes .jpg
+    target = df.loc[df['image'] == img_id, 'species'].item()
+    #print(img_id, target)
+
+    start_time = time.time()
+    image = cv2.imread(str(img_file))
+    load_time = time.time() - start_time
+
+    start_time = time.time()
+    out = cetacean_classifier(image) # get top 3 matches
+    classify_time = time.time() - start_time
+
+    whale_prediction1 = out['predictions'][0]
+
+    # comparison
+    ok = whale_prediction1 == target
+    any = target in [x for x in out['predictions']]
+    row = [img_id, target, ok, any, load_time, classify_time] + list(out['predictions'])
+
+    print(i, row)
+
+    classifications.append(row)
+
+    if i_max is not None and i >= i_max:
+        break
+
+
+df_results = pd.DataFrame(classifications, columns=['img_id', 'target', 'ok', 'any', 'load_time', 'classify_time'] + [f'pred_{i}' for i in range(3)])
+
+# print out a few summary stats
+# mean time to load and classify (formatted 3dp), +- std dev (formatted to 2dp), 
+print(f"Mean load time: {df_results['load_time'].mean():.3f} +- {df_results['load_time'].std():.2f} s")
+print(f"Mean classify time: {df_results['classify_time'].mean():.3f} +- {df_results['classify_time'].std():.2f} s")
+
+# accuracy: count of ok / count of any
+print(f"Accuracy: correct with top prediction: {df_results['ok'].sum()} | any of top 3 correct: {df_results['any'].sum():.3f} (of total {df_results.shape[0]})")
+
+# diversity: is the model just predicting one class for everything it sees?
+print("Which classes are predicted?")
+print(df_results.pred_0.value_counts())

docs/dev_notes.md

@@ -0,0 +1,40 @@
+# How to run the UI
+
+We set this up so it is hosted as a huggingface space. Each commit to `main` triggers a push and a rebuild on their servers.
+
+For local testing, assuming you have all the required packages installed in a
+conda env or virtualenv, and that env is activated:
+
+```
+cd src
+streamlit run main.py
+```
+Then use a web browser to view the site indiciated, by default: http://localhost:8501
+
+# How to build and view docs locally
+
+We have a CI action to presesnt the docs on github.io. 
+To validate locally, you need the deps listed in `requirements.txt` installed. 
+
+Run
+```
+mkdocs serve
+```
+And navigate to the wish server running locally, by default: http://127.0.0.1:8888/
+
+This automatically watches for changes in the markdown files, but if you edit the 
+something else like the docstrings in py files, triggering a rebuild in another terminal
+refreshes the site, without having to quit and restart the server.
+```
+mkdocs build -c
+```
+
+
+
+# Set up a venv
+
+(standard stuff)
+
+# Set up a conda env
+
+(Standard stuff)

docs/fix_tabrender.md

@@ -0,0 +1,5 @@
+A js fix for certain UI elements, including maps, getting rendered into a
+zero-sized frame by default. Here we resize it so it is visible once the tab is
+clicked and no further interaction is required to see it.
+
+::: src.fix_tabrender

docs/input_handling.md

@@ -0,0 +1,8 @@
+This module focuses on image and metadata entry:
+
+- UI elements to upload an image and populate the metadata (or edit the
+  auto-discovered metadata)
+- a container class for an observation
+
+
+::: src.input_handling

docs/main.md

@@ -0,0 +1,10 @@
+# Main entry point 
+
+This module sets up the streamlit UI frontend, 
+as well as logger and session state elements in the backend.
+
+The session state is used to retain values from one interaction to the next, since the streamlit execution model is to re-run the entire script top-to-bottom upon each user interaction (e.g. click). 
+See streamlit [docs](https://docs.streamlit.io/develop/api-reference/caching-and-state/st.session_state).
+
+
+::: src.entry_and_hotdog

docs/obs_map.md

@@ -0,0 +1,7 @@
+This module provides rendering of observations on an interactive map, with a variety of tilesets available. 
+
+Note: OSM, ESRI, and CartoDB map tiles are served without authentication/tokens,
+and so render correctly on the huggingface deployment. The Stamen tiles render
+on localhost but require a token to present on a 3rd-party site.
+
+::: src.obs_map

docs/st_logs.md

@@ -0,0 +1,7 @@
+This module provides utilities to incorporate a standard python logger within streamlit.
+
+
+# Streamlit log handler 
+
+::: src.st_logs
+

docs/whale_gallery.md

@@ -0,0 +1,4 @@
+This module provides a gallery of the whales and dolphins that the classifier 
+is trained on. It diplays the images and links to further info on the species.
+
+::: src.whale_gallery

docs/whale_viewer.md

@@ -0,0 +1,4 @@
+This module provides a streamlit rendering for the whales and dolphins that the classifier is aware of, and also holds the 
+metadata for them (images, class names that the classifier uses, and URLS for further information about each species).
+
+::: src.whale_viewer

mkdocs.yaml

@@ -16,10 +16,27 @@ plugins:
   - mkdocstrings:
       default_handler: python
       handlers:
-        python:
-          paths: [src]
+        python: 
+          paths: [nonexistent_path_on_purpose]
 
 
 nav:
   - README: index.md
-  - App: app.md
+  #- Quickstart:
+    #- Installation: installation.md
+    #- Usage: usage.md
+  - API:
+    - Main app: main.md
+    - Modules:
+      - Data entry handling: input_handling.md
+      - Map of observations: obs_map.md
+      - Whale gallery: whale_gallery.md
+      - Whale viewer: whale_viewer.md
+      - Logging: st_logs.md
+      - Tab-rendering fix (js): fix_tabrender.md
+
+    - Development clutter:
+      - Demo app: app.md
+    
+  - How to contribute:
+    - Dev Notes: dev_notes.md

snippets/extract_meta.py

@@ -38,7 +38,7 @@ def extract_gps(image_path):
 
         return (lat, lon)
 # Example usage
-image_path = '../call_models/imgs/cakes.jpg'
+image_path = 'imgs/cakes.jpg' # this file has good exif data, inc GPS, timestamps etc.
 datetime_info = extract_datetime(image_path)
 gps_info = extract_gps(image_path)
 print(f'Date and Time: {datetime_info}')

{call_models → src}/entry_and_hotdog.py

@@ -1,27 +1,27 @@
-import datetime
-import os
+#import datetime
 import json
 import logging
+import os
 import tempfile
+
 import pandas as pd
 import streamlit as st
+from streamlit.delta_generator import DeltaGenerator # for type hinting
 import folium
 from streamlit_folium import st_folium
 from huggingface_hub import HfApi
-#from datasets import load_dataset
-#from fix_tabrender import js_show_zeroheight_iframe
+from transformers import pipeline
+from transformers import AutoModelForImageClassification
 
-import whale_viewer as sw_wv
-import input_handling as sw_inp
 import alps_map as sw_am
-import whale_gallery as sw_wg
+import input_handling as sw_inp
 import obs_map as sw_map
 import st_logs as sw_logs
+import whale_gallery as sw_wg
+import whale_viewer as sw_wv
 
 
 
-from transformers import pipeline
-from transformers import AutoModelForImageClassification
 
 # setup for the ML model on huggingface (our wrapper)
 os.environ["PROTOCOL_BUFFERS_PYTHON_IMPLEMENTATION"] = "python"
@@ -64,14 +64,29 @@ if "tab_log" not in st.session_state:
     st.session_state.tab_log = None
     
 
-def metadata2md():
+def metadata2md() -> str:
+    """Get metadata from cache and return as markdown-formatted key-value list
+
+    Returns:
+        str: Markdown-formatted key-value list of metadata
+        
+    """
     markdown_str = "\n"
     for key, value in st.session_state.full_data.items():
             markdown_str += f"- **{key}**: {value}\n"
     return markdown_str
 
 
-def push_observation(tab_log=None):
+def push_observation(tab_log:DeltaGenerator=None):
+    """
+    Push the observation to the Hugging Face dataset
+    
+    Args:
+        tab_log (streamlit.container): The container to log messages to. If not provided,
+            log messages are in any case written to the global logger (TODO: test - didn't 
+            push any data since generating the logger)
+    
+    """
     # we get the data from session state: 1 is the dict 2 is the image.
     # first, lets do an info display (popup)
     metadata_str = json.dumps(st.session_state.full_data)
@@ -105,7 +120,26 @@ def push_observation(tab_log=None):
     st.info(msg)
     
 
-if __name__ == "__main__":
+
+def main() -> None:
+    """
+    Main entry point to set up the streamlit UI and run the application.
+
+    The organisation is as follows:
+
+    1. data input (a new observation) is handled in the sidebar
+    2. the rest of the interface is organised in tabs:
+    
+        - cetean classifier
+        - hotdog classifier
+        - map to present the obersvations
+        - table of recent log entries
+        - gallery of whale images
+    
+    The majority of the tabs are instantiated from modules. Currently the two 
+    classifiers are still in-line here.
+    
+    """
 
     g_logger.info("App started.")
     g_logger.warning(f"[D] Streamlit version: {st.__version__}. Python version: {os.sys.version}")
@@ -306,3 +340,6 @@ if __name__ == "__main__":
             tab_hotdogs.write(f"Session Data: {json.dumps(st.session_state.full_data)}")
             
             
+
+if __name__ == "__main__":
+    main()

{call_models → src}/fix_tabrender.py

@@ -10,6 +10,21 @@ import streamlit as st
 import uuid, html
 # workaround for streamlit making tabs height 0 when not active, breaks map
 def inject_iframe_js_code(source: str) -> None:
+    """
+    Injects JavaScript code into a Streamlit app using an iframe.
+
+    This function creates a hidden div with a unique ID and injects the provided
+    JavaScript code into the parent document using an iframe. The iframe's source
+    is a JavaScript URL that creates a script element, sets its type to 'text/javascript',
+    and assigns the provided JavaScript code to its text content. The script element
+    is then appended to the hidden div in the parent document.
+
+    Args:
+        source (str): The JavaScript code to be injected.
+
+    Returns:
+        None
+    """
     div_id = uuid.uuid4()
 
     st.markdown(
@@ -28,7 +43,28 @@ def inject_iframe_js_code(source: str) -> None:
         unsafe_allow_html=True,
     )
     
-def js_show_zeroheight_iframe(component_iframe_title: str, height: str = "auto"):
+def js_show_zeroheight_iframe(component_iframe_title: str, height: str = "auto") -> None:
+    """
+    Injects JavaScript code to dynamically set iframe height (located by title)
+
+    This function generates and injects JavaScript code that searches for
+    iframes with the given title and sets their height to the specified value.
+    The script attempts to find the iframes up to a maximum number of attempts,
+    and also listens for user interactions to reattempt setting the height.
+    
+    See https://github.com/streamlit/streamlit/issues/7376 
+    
+
+    Args:
+        component_iframe_title (str): The title attribute of the iframes to target.
+        height (str, optional): The height to set for the iframes. Defaults to "auto".
+
+    Notes:
+        - The JavaScript code will attempt to find the iframes every 250
+          milliseconds, up to a maximum of 20 attempts.
+        - If the iframes are found, their height will be set to the specified value.
+        - User interactions (e.g., click events) triggers a reattempt to set the height.
+    """
     source = f"""
     (function() {{
     var attempts = 0;