Upload 9 files

.gitattributes

@@ -0,0 +1,35 @@
+*.7z filter=lfs diff=lfs merge=lfs -text
+*.arrow filter=lfs diff=lfs merge=lfs -text
+*.bin filter=lfs diff=lfs merge=lfs -text
+*.bz2 filter=lfs diff=lfs merge=lfs -text
+*.ckpt filter=lfs diff=lfs merge=lfs -text
+*.ftz filter=lfs diff=lfs merge=lfs -text
+*.gz filter=lfs diff=lfs merge=lfs -text
+*.h5 filter=lfs diff=lfs merge=lfs -text
+*.joblib filter=lfs diff=lfs merge=lfs -text
+*.lfs.* filter=lfs diff=lfs merge=lfs -text
+*.mlmodel filter=lfs diff=lfs merge=lfs -text
+*.model filter=lfs diff=lfs merge=lfs -text
+*.msgpack filter=lfs diff=lfs merge=lfs -text
+*.npy filter=lfs diff=lfs merge=lfs -text
+*.npz filter=lfs diff=lfs merge=lfs -text
+*.onnx filter=lfs diff=lfs merge=lfs -text
+*.ot filter=lfs diff=lfs merge=lfs -text
+*.parquet filter=lfs diff=lfs merge=lfs -text
+*.pb filter=lfs diff=lfs merge=lfs -text
+*.pickle filter=lfs diff=lfs merge=lfs -text
+*.pkl filter=lfs diff=lfs merge=lfs -text
+*.pt filter=lfs diff=lfs merge=lfs -text
+*.pth filter=lfs diff=lfs merge=lfs -text
+*.rar filter=lfs diff=lfs merge=lfs -text
+*.safetensors filter=lfs diff=lfs merge=lfs -text
+saved_model/**/* filter=lfs diff=lfs merge=lfs -text
+*.tar.* filter=lfs diff=lfs merge=lfs -text
+*.tar filter=lfs diff=lfs merge=lfs -text
+*.tflite filter=lfs diff=lfs merge=lfs -text
+*.tgz filter=lfs diff=lfs merge=lfs -text
+*.wasm filter=lfs diff=lfs merge=lfs -text
+*.xz filter=lfs diff=lfs merge=lfs -text
+*.zip filter=lfs diff=lfs merge=lfs -text
+*.zst filter=lfs diff=lfs merge=lfs -text
+*tfevents* filter=lfs diff=lfs merge=lfs -text

README.md

@@ -0,0 +1,13 @@
+---
+title: Building Acoustics Analysis TestLab
+emoji: 📈
+colorFrom: indigo
+colorTo: pink
+sdk: streamlit
+sdk_version: 1.37.0
+app_file: app.py
+pinned: false
+license: mit
+---
+
+Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference

app.py

@@ -0,0 +1,52 @@
+# ─────────────────────────────────────────────────────────────────────────────
+# Building Acoustics Analysis Tool  ·  Streamlit 1.35
+# RT60 · Background-Noise · Speech-Intelligibility   
+# Version: V4-2025
+# Date: July 2025
+# ─────────────────────────────────────────────────────────────────────────────
+
+import streamlit as st
+from config import MAJOR_TABS, DEFAULTS
+from sections import (
+    section_instructions, section_initial_data, section_initial_checks,
+    section_acoustic_treatment, section_final_checks, section_faq,
+    nav_to, nav_buttons
+)
+from report import generate_docx
+
+# ── page config (unchanged) ────────────────────────────────────────────────
+st.set_page_config("Building Acoustics Analysis Tool", "🏫",
+                   layout="wide", initial_sidebar_state="expanded")
+
+# ── ensure session-state keys exist ────────────────────────────────────────
+for k, v in DEFAULTS.items():
+    st.session_state.setdefault(k, v)
+
+# ── sidebar navigation ─────────────────────────────────────────────────────
+with st.sidebar:
+    st.header("Navigation")
+    for tab in MAJOR_TABS:
+        st.button(tab, on_click=nav_to, args=(tab,))
+    st.markdown("---")
+    st.write("Version: V4-2025")
+    if st.session_state.major_tab == "Final Compliance Checks":
+        st.download_button("📥 Word Report",
+                           generate_docx(),
+                           "Acoustics_Report.docx",
+                           "application/vnd.openxmlformats-officedocument."
+                           "wordprocessingml.document")
+
+# ── router ─────────────────────────────────────────────────────────────────
+ROUTES = {
+    "Instructions": section_instructions,
+    "Initial Data Entry": section_initial_data,
+    "Initial Compliance Checks": section_initial_checks,
+    "Acoustic Treatment": section_acoustic_treatment,
+    "Final Compliance Checks": section_final_checks,
+    "FAQ / Help": section_faq,
+}
+ROUTES[st.session_state.major_tab]()
+
+# ── footer ─────────────────────────────────────────────────────────────────
+st.write("---")
+st.write("Developed by Dr Abdul-Manan Sadick · Deakin University · 2025")

config.py

@@ -0,0 +1,44 @@
+"""Global constants and initial session-state defaults."""
+from typing import List
+import pandas as pd
+
+FREQUENCIES: List[int] = [125, 250, 500, 1000, 2000, 4000]
+TOTAL_DOTS = 200
+AI_BANDS = {
+    (0.00, 0.24): "None",
+    (0.25, 0.40): "Fair",
+    (0.41, 0.60): "Good",
+    (0.61, 1.00): "Excellent",
+}
+MAJOR_TABS = [
+    "Instructions",
+    "Initial Data Entry",
+    "Initial Compliance Checks",
+    "Acoustic Treatment",
+    "Final Compliance Checks",
+    "FAQ / Help",
+]
+
+# ── Streamlit-session defaults ────────────────────────────────────────────
+DEFAULTS = dict(
+    major_tab=MAJOR_TABS[0],
+    # uploads / inputs
+    df_current_rt=None, df_existing_mat=None, room_volume=0.0,
+    df_background_noise=pd.DataFrame(columns=["Location", "dBA"]),
+    bn_input_loc="", bn_input_val=0.0,
+    df_spl=None,
+    # compliance params
+    rt_min=0.0, rt_max=0.0, bn_min=0.0, bn_max=0.0,
+    # multi-location AI dictionaries
+    dots_init_dict={}, ai_init_dict={},
+    dots_final_dict={}, ai_final_dict={},
+    # acoustic-treatment data
+    desired_rt_df=pd.DataFrame(
+        {"Frequency": FREQUENCIES, "Desired RT60": [0.01]*6}
+    ),
+    df_new_mat=None,
+    # derived absorption & figures
+    current_absorption={}, new_absorption={},
+    fig_rt_initial=None, fig_bn_initial=None,
+    fig_rt_final=None,  fig_bn_final=None,
+)

helpers.py

@@ -0,0 +1,72 @@
+"""Utility functions shared by all modules."""
+import io, re, numpy as np, pandas as pd
+import plotly.graph_objects as go
+import streamlit as st
+from config import FREQUENCIES, TOTAL_DOTS, AI_BANDS
+
+# ── misc helpers ───────────────────────────────────────────────────────────
+def slugify(txt: str) -> str:
+    return re.sub(r"[^0-9a-zA-Z_]+", "_", txt)
+
+def standardise_freq_cols(df: pd.DataFrame) -> pd.DataFrame:
+    m = {"125Hz": "125", "250Hz": "250", "500Hz": "500", "1000Hz": "1000",
+         "1KHz": "1000", "2KHz": "2000", "4KHz": "4000"}
+    df.columns = [m.get(str(c).replace(" Hz", "").replace("KHz", "000").strip(),
+                        str(c).strip()) for c in df.columns]
+    df.columns = pd.to_numeric(df.columns, errors="ignore")
+    return df
+
+def validate_numeric(df):                          # True if all numeric
+    return not df.empty and df.applymap(np.isreal).all().all()
+
+@st.cache_data(show_spinner=False)
+def read_upload(upload, *, header=0, index_col=None):
+    raw = upload.getvalue()
+    if upload.name.endswith(".csv"):
+        return pd.read_csv(io.BytesIO(raw), header=header, index_col=index_col)
+    return pd.read_excel(io.BytesIO(raw), header=header, index_col=index_col)
+
+def calc_abs_area(volume_m3, rt_s):
+    return float("inf") if rt_s == 0 else 0.16 * volume_m3 / rt_s
+
+# ── plotting helpers ───────────────────────────────────────────────────────
+def plot_rt_band(y_cur, y_min, y_max, title):
+    f = go.Figure()
+    f.add_trace(go.Scatter(x=FREQUENCIES, y=y_cur, mode="lines+markers",
+                 name="Current", marker_color="#1f77b4"))
+    f.add_trace(go.Scatter(x=FREQUENCIES, y=y_max, mode="lines",
+                 name="Max Std", line=dict(dash="dash", color="#ff7f0e")))
+    f.add_trace(go.Scatter(x=FREQUENCIES, y=y_min, mode="lines",
+                 name="Min Std", line=dict(dash="dash", color="#2ca02c"),
+                 fill="tonexty", fillcolor="rgba(44,160,44,0.15)"))
+    f.update_layout(template="plotly_white", title=title,
+                    xaxis_title="Frequency (Hz)",
+                    yaxis_title="Reverberation Time (s)",
+                    legend=dict(orientation="h", y=-0.2))
+    return f
+
+def plot_bn_band(x, y_meas, y_min, y_max, title):
+    f = go.Figure()
+    f.add_trace(go.Bar(x=x, y=y_meas, name="Measured",
+                       marker_color="#1f77b4", opacity=0.6))
+    f.add_shape(type="rect", x0=-.5, x1=len(x)-.5, y0=y_min, y1=y_max,
+                fillcolor="rgba(255,0,0,0.15)", line=dict(width=0), layer="below")
+    for y, c, lbl in [(y_max, "#ff0000", "Max Std"),
+                      (y_min, "#ff0000", "Min Std")]:
+        f.add_shape(type="line", x0=-.5, x1=len(x)-.5, y0=y, y1=y,
+                    line=dict(color=c, dash="dash"))
+        f.add_trace(go.Scatter(x=[None], y=[None], mode="lines",
+                               line=dict(color=c, dash="dash"),
+                               showlegend=True, name=lbl))
+    f.update_layout(template="plotly_white", title=title,
+                    xaxis_title="Location", yaxis_title="Sound Level (dBA)",
+                    legend=dict(orientation="h", y=-0.2))
+    return f
+
+# ── speech-intelligibility ─────────────────────────────────────────────────
+def articulation_index(dots: int):
+    ai = dots / TOTAL_DOTS
+    for (lo, hi), lbl in AI_BANDS.items():
+        if lo <= ai <= hi:
+            return ai, lbl
+    return ai, "Out of range"

report.py

@@ -0,0 +1,72 @@
+"""Generate the downloadable Word report."""
+import io, tempfile
+from docx import Document
+from docx.shared import Inches
+import streamlit as st
+from config import FREQUENCIES
+from helpers import calc_abs_area
+
+def generate_docx() -> bytes:
+    doc = Document()
+    doc.add_heading("Room Acoustics Analysis Report", 0)
+
+    # 1 ─ Input data
+    doc.add_heading("1  Input Data", 1)
+    doc.add_paragraph(f"Room volume: {st.session_state.room_volume:.2f} m³")
+
+    if st.session_state.df_current_rt is not None:
+        doc.add_heading("Current Reverberation Time", 2)
+        doc.add_paragraph(st.session_state.df_current_rt.to_string(index=False))
+
+    if st.session_state.df_existing_mat is not None:
+        doc.add_heading("Existing Materials – Coefficients & Areas", 2)
+        doc.add_paragraph(st.session_state.df_existing_mat.to_string(index=False))
+
+    if not st.session_state.df_background_noise.empty:
+        doc.add_heading("Background-Noise Measurements", 2)
+        doc.add_paragraph(st.session_state.df_background_noise.to_string(index=False))
+
+    if st.session_state.df_spl is not None:
+        doc.add_heading("Sound-Pressure Levels (SPL)", 2)
+        doc.add_paragraph(st.session_state.df_spl.to_string())
+
+    # 2 ─ Speech-intelligibility (Dots & AI)
+    doc.add_heading("2  Speech-Intelligibility (Dots & AI)", 1)
+
+    if st.session_state.dots_init_dict:
+        doc.add_heading("Initial Compliance Check", 2)
+        for loc, dots in st.session_state.dots_init_dict.items():
+            ai, interp = st.session_state.ai_init_dict.get(loc, (None, ""))
+            line = f"{loc}: Dots = {dots}"
+            if ai is not None:
+                line += f"  →  AI = {ai:.2f} ({interp})"
+            doc.add_paragraph(line)
+
+    if st.session_state.dots_final_dict:
+        doc.add_heading("Final Compliance Check", 2)
+        for loc, dots in st.session_state.dots_final_dict.items():
+            ai, interp = st.session_state.ai_final_dict.get(loc, (None, ""))
+            line = f"{loc}: Dots = {dots}"
+            if ai is not None:
+                line += f"  →  AI = {ai:.2f} ({interp})"
+            doc.add_paragraph(line)
+
+    # 3 ─ Figures
+    doc.add_heading("3  Figures", 1)
+
+    def _add(fig, caption):
+        if fig is None: return
+        with tempfile.NamedTemporaryFile(suffix=".png", delete=False) as tmp:
+            fig.write_image(tmp.name, scale=4)
+            doc.add_picture(tmp.name, width=Inches(6))
+            doc.paragraphs[-1].alignment = 1
+            doc.add_paragraph(caption, style="Caption")
+
+    _add(st.session_state.fig_rt_initial, "Fig 1  Initial RT60 vs Standard Range")
+    _add(st.session_state.fig_bn_initial, "Fig 2  Initial Background-Noise vs Standard Range")
+    _add(st.session_state.fig_rt_final,   "Fig 3  Final RT60 vs Standard Range")
+    _add(st.session_state.fig_bn_final,   "Fig 4  Final Background-Noise vs Standard Range")
+
+    buf = io.BytesIO()
+    doc.save(buf)
+    return buf.getvalue()

requirements.txt

@@ -0,0 +1,14 @@
+# Core web-app stack
+streamlit==1.35.0      
+plotly==5.20.0          
+kaleido==0.2.1          
+
+# Data analysis
+pandas==2.2.2
+numpy==1.26.4
+openpyxl==3.1.2         
+
+# Word-report generation
+python-docx==1.1.0
+
+altair<5

sections.py

@@ -0,0 +1,681 @@
+"""
+sections.py
+===========
+
+All Streamlit UI page/section functions for the Building Acoustics Analysis
+Tool.  No functional changes have been introduced.
+"""
+from __future__ import annotations
+
+# ── third-party ────────────────────────────────────────────────────────────
+import numpy as np
+import pandas as pd
+import plotly.graph_objects as go
+import streamlit as st
+
+# ── local imports ───────────────────────────────────────────────────────────
+from config import FREQUENCIES, MAJOR_TABS, TOTAL_DOTS
+from helpers import (
+    slugify,
+    standardise_freq_cols,
+    validate_numeric,
+    read_upload,
+    calc_abs_area,
+    plot_rt_band,
+    plot_bn_band,
+    articulation_index,
+)
+
+# ────────────────────────────────────────────────────────────────────────────
+# Navigation helpers (used by several sections)
+# ────────────────────────────────────────────────────────────────────────────
+def nav_to(tab: str) -> None:
+    """Switch the major tab in session-state."""
+    st.session_state.major_tab = tab
+
+
+def nav_buttons() -> None:
+    """Render ← / → buttons with explicit section names."""
+    idx = MAJOR_TABS.index(st.session_state.major_tab)
+    c1, _, c3 = st.columns([2, 6, 2])
+    if idx > 0:
+        c1.button(f"← {MAJOR_TABS[idx-1]}", on_click=nav_to,
+                  args=(MAJOR_TABS[idx-1],))
+    if idx < len(MAJOR_TABS) - 1:
+        c3.button(f"{MAJOR_TABS[idx+1]} →", on_click=nav_to,
+                  args=(MAJOR_TABS[idx+1],))
+
+# ────────────────────────────────────────────────────────────────────────────
+# Individual sections (exact logic preserved)
+# ────────────────────────────────────────────────────────────────────────────
+def section_instructions() -> None:
+    st.title("🔊 Building Acoustics Analysis Tool")
+
+    with st.expander("App Information", expanded=False):
+        st.write("""
+            - Welcome to the Building Acoustics Analysis Tool.
+            - This app was developed to help Deakin University Construction Management students complete a building acoustics assignment in SRT757 Building Systems and Environment.
+            - This app is intended for a retrofitting task and assumes that you have measured the current reverberation of the room to be assessed.
+            - The app helps to analyze and modify room reverberation times to fall within standard ranges using the Sabine equation.
+            - This app is intended for educational purposes only and should not be used for professional purposes.
+            """)
+
+    # Example DataFrames
+    df_current_reverberation_times = pd.DataFrame({
+        '125': [0.8], '250': [0.7], '500': [0.6],
+        '1000': [0.5], '2000': [0.4], '4000': [0.3]
+    })
+
+    df_existing_materials = pd.DataFrame({
+        'Material Name': ['Carpet', 'Curtain'],
+        'Area_No': [50, 30],
+        '125': [0.1, 0.2], '250': [0.15, 0.25], '500': [0.2, 0.3],
+        '1000': [0.3, 0.35], '2000': [0.4, 0.45], '4000': [0.5, 0.55]
+    })
+
+    df_new_materials = pd.DataFrame({
+        'Material Name': ['Acoustic Panel', 'Foam'],
+        'Area_No': [40, 20],
+        '125': [0.3, 0.25], '250': [0.35, 0.3], '500': [0.4, 0.35],
+        '1000': [0.45, 0.4], '2000': [0.5, 0.45], '4000': [0.6, 0.55]
+    })
+
+    df_sound_pressure_levels = pd.DataFrame({
+        'Location': ['Location 1', 'Location 2'],
+        '125': [60, 62], '250': [58, 59], '500': [55, 56],
+        '1000': [52, 53], '2000': [50, 51], '4000': [48, 49]
+    })
+
+    st.write("## Instructions")
+
+    st.markdown("""
+    Welcome to the **Building Acoustics Analysis Tool**. This educational application supports students in analyzing and improving room acoustics by addressing:
+    - **Reverberation Time (RT60)**
+    - **Background Noise**
+    - **Speech Intelligibility (Articulation Index)**
+
+    The tool is structured around Sabine's theory and common acoustic assessment standards, using six standard frequencies (125 Hz, 250 Hz, 500 Hz, 1000 Hz, 2000 Hz, and 4000 Hz). It is designed to help users diagnose and treat acoustic deficiencies by uploading and modifying material and noise-related inputs.
+
+    ⚠️ **Note:** This tool is intended for educational purposes and should not be used for professional certification or compliance without additional verification.
+
+    ### Reverberation Time (RT60)
+    RT60 represents the time required for a sound to decay by 60 dB after the source stops. An optimal RT60 enhances clarity and acoustic comfort:
+    - **Short RT60**: Suitable for classrooms, meeting rooms, and lecture halls.
+    - **Longer RT60**: More acceptable in concert halls and religious buildings.
+
+    #### RT60 Calculation – Sabine’s Equation
+    **RT60 = (0.16 × V) / A**
+
+    Where:
+    - `V` = Room volume (m³)
+    - `A` = Total absorption (m² Sabins)
+
+    **Example**:
+    If a 100 m³ room has total absorption of 10 m²:
+    **RT60 = (0.16 × 100) / 10 = 1.60 seconds**
+
+    ### Background Noise
+    Background noise refers to ambient sound levels in a room, typically measured in **dBA**. Excessive background noise can mask speech and reduce communication effectiveness, even in acoustically treated rooms.
+
+    The app allows users to enter measured **background noise levels** for one or more locations and compare them with recommended standard ranges. You can visualize these using bar plots and identify areas needing improvement.
+
+    - **Sources**: HVAC systems, outside traffic, or adjacent room activities.
+    - **Goal**: Maintain noise levels within acceptable limits (as defined by relevant standards).
+
+    ### Speech Intelligibility
+    Speech intelligibility is the measure of how clearly speech can be understood within a room. This tool uses the **Articulation Index (AI)** method:
+    - Based on “Dots Above a Curve” from sound pressure level data
+    - User inputs number of audible speech "dots" above noise thresholds
+    - AI is computed and interpreted (None, Fair, Good, Excellent)
+
+    Higher AI scores suggest better speech transmission. This measure is particularly important in educational, healthcare, and public spaces.
+
+    ### App Functionality
+    The app guides users through six key stages:
+    1. **Initial Data Entry** – Upload baseline acoustic data (RT60, materials, background noise, SPL).
+    2. **Initial Compliance Checks** – Review current RT60, noise levels, and speech intelligibility.
+    3. **Desired RT60** – Define preferred RT60 per frequency to guide treatment.
+    4. **Acoustic Treatment** – Add new materials to adjust absorption.
+    5. **Final Compliance Checks** – Evaluate impact on RT60, noise, and intelligibility.
+    6. **FAQ / Help** – Access help content and export a summary report.
+
+    ### Formatting Input Data
+
+    ⚠️ **Use CSV or Excel, following the formats shown below without.**
+
+    #### Current Reverberation Times
+    - **Format**: One row, column headers = frequencies
+    """)
+    st.write(df_current_reverberation_times)
+
+    st.markdown("""
+    #### Existing Materials – Absorption Coefficients and Areas
+    - **Format**: Material name, surface area, absorption coefficients
+    """)
+    st.write(df_existing_materials)
+
+    st.markdown("""
+    #### New Materials – Absorption Coefficients and Areas
+    - **Format**: Same structure as existing materials
+    """)
+    st.write(df_new_materials)
+
+    st.markdown("""
+    #### Sound Pressure Levels (SPL)
+    - **Format**: Location name in first column; SPLs at frequencies as columns
+    """)
+    st.write(df_sound_pressure_levels)
+
+    st.markdown("""
+    ### Navigation Summary
+
+    - **Instructions** – You are here. Read all information before starting.
+    - **Initial Data Entry** – Upload all your acoustic data. Room volume, RT60, background noise, and SPLs are required.
+    - **Initial Compliance Checks** – Visualize current RT60, compare background noise with limits, and assess initial speech intelligibility.
+    - **Desired RT60** – Define target reverberation levels per frequency. This guides treatment planning.
+    - **Acoustic Treatment** – Upload and experiment with new materials to modify absorption and reduce noise.
+    - **Final Compliance Checks** – Review the combined impact of old and new materials on RT60, noise, and speech clarity.
+
+    ### General Tips
+    - Keep filenames and headings clean and consistent.
+    - Use the six standard frequencies.
+    - Adjust materials iteratively to achieve compliance.
+    - Download your report after completing all sections.
+
+    For further clarification or examples, please consult the FAQ tab or contact your instructor.
+    """)
+    st.info("After reviewing the instructions, proceed to the **Initial Data Entry** tab.")
+
+    nav_buttons()
+
+
+# ---------------------------------------------------------------------------
+def section_initial_data() -> None:
+    st.title("🔊 Building Acoustics Analysis Tool")
+
+    with st.expander("App Information", expanded=False):
+        st.write("""
+            - This app is intended for educational purposes only and should not be used for professional purposes.
+        """)
+    
+    st.header("📥 Initial Data Entry")
+    t_rt, t_bn, t_si = st.tabs(
+        ["Reverberation Time", "Background Noise", "Speech Intelligibility"])
+
+    # ── RT60 + materials ───────────────────────────────────────────────────
+    with t_rt:
+
+        st.write('''The primary objective here is to provide all the initial input data needed to 
+        start RT60 analysis. See the 'Instructions' on the left for formatting information.''')
+
+        c1, c2 = st.columns(2)
+        u_rt = c1.file_uploader("Current RT60 data (CSV/XLSX)", type=["csv", "xlsx"])
+        if u_rt:
+            df = standardise_freq_cols(read_upload(u_rt))
+            st.session_state.df_current_rt = df if validate_numeric(df) else None
+
+        u_mat = c2.file_uploader("Existing materials (CSV/XLSX)",
+                                 type=["csv", "xlsx"])
+        if u_mat:
+            dfm = standardise_freq_cols(read_upload(u_mat))
+            st.session_state.df_existing_mat = (
+                dfm if validate_numeric(dfm.iloc[:, 2:]) else None
+            )
+
+        st.session_state.room_volume = st.number_input(
+            "Room volume [m³]",
+            value=st.session_state.room_volume,
+            min_value=0.0,
+            step=0.1,
+        )
+
+        # warnings
+        if st.session_state.df_current_rt is None:
+            st.warning("⚠️ Upload *Current RT60* data.")
+        if st.session_state.df_existing_mat is None:
+            st.warning("⚠️ Upload *Existing Materials* data.")
+        if st.session_state.room_volume == 0:
+            st.warning("⚠️ Enter a non-zero room volume.")
+
+        if st.session_state.df_current_rt is not None:
+            st.dataframe(st.session_state.df_current_rt, use_container_width=True)
+        if st.session_state.df_existing_mat is not None:
+            st.dataframe(st.session_state.df_existing_mat, use_container_width=True)
+
+    # ── Background noise ───────────────────────────────────────────────────
+    with t_bn:
+
+        st.write('''The primary objective here is to provide the initial input data needed to 
+        start background noise analysis. See the 'Instructions' on the left for formatting information''')
+        
+        c1, c2, c3 = st.columns([3, 2, 1])
+        st.session_state.bn_input_loc = c1.text_input(
+            "Location", st.session_state.bn_input_loc)
+        st.session_state.bn_input_val = c2.number_input(
+            "dBA", value=st.session_state.bn_input_val, min_value=0.0, step=0.1)
+
+        if c3.button("Add / Update"):
+            loc = st.session_state.bn_input_loc.strip()
+            if loc:
+                df = st.session_state.df_background_noise
+                if loc in df["Location"].values:
+                    df.loc[df["Location"] == loc, "dBA"] = st.session_state.bn_input_val
+                else:
+                    df.loc[len(df)] = [loc, st.session_state.bn_input_val]
+                st.session_state.df_background_noise = df
+
+        if st.session_state.df_background_noise.empty:
+            st.warning("⚠️ Enter at least one background-noise measurement.")
+
+        st.dataframe(st.session_state.df_background_noise, use_container_width=True)
+
+    # ── SPL upload ─────────────────────────────────────────────────────────
+    with t_si:
+
+        st.write('''The primary objective here is to provide the initial input data needed to 
+        start speech intelligibility analysis. See the 'Instructions' on the left for 
+        formatting information''')
+        
+        u = st.file_uploader("Current sound pressure level data (CSV/XLSX)", type=["csv", "xlsx"])
+        if u:
+            df = standardise_freq_cols(read_upload(u, header=0, index_col=0))
+            df.columns = [int(c) for c in df.columns]
+            st.session_state.df_spl = (
+                df if set(df.columns) >= set(FREQUENCIES) else None
+            )
+            # reset AI dicts on new upload
+            st.session_state.dots_init_dict, st.session_state.ai_init_dict = {}, {}
+            st.session_state.dots_final_dict, st.session_state.ai_final_dict = {}, {}
+
+        if st.session_state.df_spl is None:
+            st.warning("⚠️ Upload *SPL* data with columns 125–4000 Hz.")
+        else:
+            st.dataframe(st.session_state.df_spl, use_container_width=True)
+
+    nav_buttons()
+
+
+# ---------------------------------------------------------------------------
+def section_initial_checks() -> None:
+    st.title("🔊 Building Acoustics Analysis Tool")
+
+    with st.expander("App Information", expanded=False):
+        st.write("""
+            - This app is intended for educational purposes only and should not be used for professional purposes.
+        """)
+    
+    st.header("✅ Initial Compliance Checks")
+    st.write("""The purpose of initial complaince checks to verify if the acoustic properties
+    of the space complies with standards. If the space complies, acoustic treatment may not
+    be required. """)
+    t_rt, t_bn, t_si = st.tabs(
+        ["Reverberation Time", "Background Noise", "Speech Intelligibility"])
+
+    # early global warnings
+    if (st.session_state.df_current_rt is None or
+            st.session_state.df_existing_mat is None):
+        st.warning("⚠️ Current RT60 and/or Materials data missing "
+                   "(see *Initial Data Entry*).")
+    if st.session_state.df_background_noise.empty:
+        st.warning("⚠️ Background-noise data missing "
+                   "(see *Initial Data Entry*).")
+    if st.session_state.df_spl is None:
+        st.warning("⚠️ Sound pressure level (SPL) data missing (see *Initial Data Entry*).")
+
+    # ── RT60 check ─────────────────────────────────────────────────────────
+    with t_rt:
+        st.write("""Privide the min and max standard RT60 for your space type to complete 
+        initial RT60 compliance check.""")
+        c1, c2 = st.columns(2)
+        st.session_state.rt_min = c1.number_input(
+            "Min standard RT60 [s]", value=st.session_state.rt_min, min_value=0.0, step=0.01)
+        st.session_state.rt_max = c2.number_input(
+            "Max standard RT60 [s]", value=st.session_state.rt_max, min_value=0.0, step=0.01)
+
+        if st.session_state.rt_max <= st.session_state.rt_min:
+            st.warning("⚠️ Max RT60 must be greater than Min RT60.")
+
+        if st.session_state.df_existing_mat is not None:
+            @st.cache_data(show_spinner=False)
+            def _abs(df):
+                acc = {f: 0.0 for f in FREQUENCIES}
+                for _, r in df.iterrows():
+                    area = r[1]
+                    for f, coeff in zip(FREQUENCIES, r[2:]):
+                        acc[f] += coeff * area
+                return acc
+
+            st.markdown("""###### Sound absorption based initial matrials""")
+            st.session_state.current_absorption = _abs(
+                st.session_state.df_existing_mat)
+            st.dataframe(pd.DataFrame([st.session_state.current_absorption]),
+                         use_container_width=True)
+
+        if (st.session_state.df_current_rt is not None and
+                st.session_state.rt_max > st.session_state.rt_min):
+            y_cur = [float(st.session_state.df_current_rt.iloc[0][f])
+                     for f in FREQUENCIES]
+            fig = plot_rt_band(
+                y_cur,
+                [st.session_state.rt_min]*6,
+                [st.session_state.rt_max]*6,
+                "Initial RT60 vs Standard RT60 Range",
+            )
+            st.plotly_chart(fig, use_container_width=True)
+            st.session_state.fig_rt_initial = fig
+
+    # ── Background noise check ─────────────────────────────────────────────
+    with t_bn:
+        st.write("""Provide the min and max standard background noise for your space type to
+        complete complaince check.""")
+        c1, c2 = st.columns(2)
+        st.session_state.bn_min = c1.number_input(
+            "Min standard background noise [dBA]", value=st.session_state.bn_min, min_value=0.0, step=0.1)
+        st.session_state.bn_max = c2.number_input(
+            "Max standard background noise [dBA]", value=st.session_state.bn_max, min_value=0.0, step=0.1)
+
+        if st.session_state.bn_max <= st.session_state.bn_min:
+            st.warning("⚠️ Max background noise must be greater than Min background noise.")
+
+        df = st.session_state.df_background_noise
+        if (not df.empty and st.session_state.bn_max > st.session_state.bn_min):
+            fig = plot_bn_band(
+                df["Location"], df["dBA"],
+                st.session_state.bn_min, st.session_state.bn_max,
+                "Initial Background Noise vs Standard Background Noise Range",
+            )
+            st.plotly_chart(fig, use_container_width=True)
+            st.session_state.fig_bn_initial = fig
+
+    # ── Speech-intelligibility check ───────────────────────────────────────
+    with t_si:
+        col_text, col_img = st.columns([3,2])
+        with col_text:
+            st.write("""Manually plot the sound pressure values below on the dots graph 
+            (see Fig 1) and count the dots above the line for 
+            articluation index calculation below. You must plot a dot graph for each 
+            location in the sound pressure levels table below.""")
+
+            if st.session_state.df_spl is not None:
+                st.markdown("###### current sound pressure levels")
+                st.dataframe(st.session_state.df_spl, use_container_width=True)
+
+        with col_img:
+            st.image("dots_graph2.jpg", caption="Fig 1: Dots graph",
+             use_column_width=False)
+
+        if st.session_state.df_spl is not None:
+            # st.markdown("###### current sound pressure levels")
+            # st.dataframe(st.session_state.df_spl, use_container_width=True)
+            ai_rows = []
+            st.markdown("###### Articulation Index (AI) calculation")
+            for loc in st.session_state.df_spl.index:
+                key = slugify(f"dots_init_{loc}")
+                default = st.session_state.dots_init_dict.get(loc, 0)
+                dots = st.number_input(
+                    f"Dots above ({loc})", 0, TOTAL_DOTS,
+                    step=1, value=default, key=key)
+                st.session_state.dots_init_dict[loc] = dots
+                ai, interp = articulation_index(dots) if dots else (None, "")
+                st.session_state.ai_init_dict[loc] = (ai, interp)
+                ai_rows.append({
+                    "Location": loc,
+                    "Articulation Index (AI)": f"{ai:.2f}" if ai is not None else "",
+                    "Interpretation": interp,
+                })
+            st.dataframe(pd.DataFrame(ai_rows), use_container_width=True)
+
+    nav_buttons()
+
+# ---------------------------------------------------------------------------
+def section_acoustic_treatment() -> None:
+    st.title("🔊 Building Acoustics Analysis Tool")
+
+    with st.expander("App Information", expanded=False):
+        st.write("""
+            - This app is intended for educational purposes only and should not be used for professional purposes.
+        """)
+    
+    st.header("🛠 Acoustic Treatment")
+    tab_desired, tab_mat = st.tabs(["Desired RT60", "New Materials"])
+
+    # ── Desired RT60 entry ─────────────────────────────────────────────────
+    with tab_desired:
+
+        st.write('''At this point in the analysis, you would need to define your desired RT60, 
+        which would be used to calculate the desired sound absorption needed to achieve the 
+        desired RT60. Compare the total frequency values in the table below to the calculated current
+        room sound absorption on the Initial RT60 Compliance Check tab to inform your selection 
+        of new materials in the next step of the analysis''')
+
+        if st.session_state.rt_max == 0:
+            st.warning("⚠️ Define RT60 standard range in *Initial Compliance Checks* first.")
+
+        st.info("Enter the desired RT60 for each frequency.")
+        desired = {}
+        for freq in FREQUENCIES:
+            default = float(
+                st.session_state.desired_rt_df[
+                    st.session_state.desired_rt_df["Frequency"] == freq
+                ]["Desired RT60"].values[0]
+            )
+            val = st.number_input(
+                f"{freq} Hz", min_value=0.01, step=0.01,
+                value=default, key=f"des_rt_{freq}")
+            desired[freq] = val
+
+        st.session_state.desired_rt_df["Desired RT60"] = (
+            st.session_state.desired_rt_df["Frequency"].map(desired)
+        )
+
+        within = all(
+            st.session_state.rt_min <= v <= st.session_state.rt_max
+            for v in desired.values()
+        )
+        if within:
+            df_abs = pd.DataFrame([{
+                f: calc_abs_area(st.session_state.room_volume, v)
+                for f, v in desired.items()
+            }], index=["Required absorption"])
+            st.markdown("###### Sound absorption based on Desired RT60")
+            st.dataframe(df_abs, use_container_width=True)
+        else:
+            st.error("Each Desired RT60 must lie within the standard range.")
+
+        if st.session_state.room_volume == 0:
+            st.warning("⚠️ Enter a non-zero room volume (see *Initial Data Entry*).")
+
+    # ── New materials ──────────────────────────────────────────────────────
+    with tab_mat:
+
+        st.write("""The desired sound absorption calculated on the Desired RT60 tab is the target
+        sound absorption you are aiming to achieve. You now have to start working towards achieving
+        the target absorptions. Based on the differences between the desired sound absorptions 
+        (see Desired RT60 tab) and the calculated current room sound absorptions 
+        (see Initial RT60 Compliance Check tab), you would need to introduce new materials to either
+        increase or decrease sound absorption for some frequencies. Note that sound absorption 
+        coefficients of a material are not the same for all frequencies. Therefore, you need to 
+        strategically select your materials. You may need to repeat the material selection process
+        several times to ensure that the room passes the final RT60 compliance check. 
+        Your project brief may place limitations on the number of structural changes 
+        (like changing the wall or concrete floor) you are allowed to make. For a retrofit project, 
+        you can change non-structural elements like carpet and ceiling tiles. Additionally, you 
+        can introduce new materials like curtains.
+        """)
+
+        
+        u = st.file_uploader("New materials data (CSV/XLSX)", type=["csv", "xlsx"])
+        if u:
+            st.session_state.df_new_mat = standardise_freq_cols(read_upload(u))
+
+        if st.session_state.df_new_mat is None:
+            st.warning("⚠️ Upload or add at least one new material.")
+        else:
+            st.info("""You can add or delete rows and modify the values in the table below. 
+            Changes will be applied and will instantly impact sound absorption
+            and Final Compliance Checks.""")
+            
+            df_edit = st.data_editor(
+                st.session_state.df_new_mat, num_rows="dynamic",
+                use_container_width=True, key="edit_newmat")
+            st.session_state.df_new_mat = df_edit
+
+            new_abs = {f: 0.0 for f in FREQUENCIES}
+            for _, r in df_edit.iterrows():
+                area = r[1]
+                for f, coeff in zip(FREQUENCIES, r[2:]):
+                    new_abs[f] += coeff * area
+            st.session_state.new_absorption = new_abs
+            st.markdown("###### Sound absorption based on new materials")
+            st.dataframe(pd.DataFrame([new_abs], index=["New absorption"]),
+                         use_container_width=True)
+
+    nav_buttons()
+
+
+# ---------------------------------------------------------------------------
+def section_final_checks() -> None:
+    st.title("🔊 Building Acoustics Analysis Tool")
+
+    with st.expander("App Information", expanded=False):
+        st.write("""
+            - This app is intended for educational purposes only and should not be used for professional purposes.
+        """)
+    
+    st.header("🚦 Final Compliance Checks")
+    t_rt, t_bn, t_si = st.tabs(
+        ["Reverberation Time", "Background Noise", "Speech Intelligibility"])
+
+    combined = {
+        f: st.session_state.current_absorption.get(f, 0)
+           + st.session_state.new_absorption.get(f, 0)
+        for f in FREQUENCIES
+    }
+
+    # ── RT60 final check ───────────────────────────────────────────────────
+    with t_rt:
+        if st.session_state.room_volume == 0 or not combined:
+            st.warning("⚠️ Provide volume + materials, then run Acoustic Treatment.")
+        else:
+            new_rt = {f: calc_abs_area(st.session_state.room_volume, a)
+                      for f, a in combined.items()}
+            st.markdown("New RT60 values after acoustic treatment")
+            st.dataframe(pd.DataFrame([new_rt], index=["New RT60"]),
+                         use_container_width=True)
+
+            y_cur = ([float(st.session_state.df_current_rt.iloc[0][f])
+                      for f in FREQUENCIES]
+                     if st.session_state.df_current_rt is not None else [None]*6)
+
+            fig = plot_rt_band(
+                y_cur,
+                [st.session_state.rt_min]*6,
+                [st.session_state.rt_max]*6,
+                "Final RT60 vs Standard Range",
+            )
+            fig.add_trace(go.Scatter(
+                x=FREQUENCIES,
+                y=[new_rt[f] for f in FREQUENCIES],
+                mode="lines+markers",
+                name="New",
+                marker_color="#d62728",
+            ))
+            st.plotly_chart(fig, use_container_width=True)
+            st.session_state.fig_rt_final = fig
+
+    # ── Background noise final check ───────────────────────────────────────
+    with t_bn:
+        st.write("""When you apply acoustic treatment to a room, the noise reduction 
+        resulting from increased sound absorption will deacrease background noise.""")
+        df = st.session_state.df_background_noise
+        if df.empty or not combined:
+            st.warning("⚠️ Provide background-noise data and run Acoustic Treatment.")
+        else:
+            before = sum(st.session_state.current_absorption.values())
+            after = sum(combined.values())
+            if before == 0:
+                st.error("Existing absorption sum is zero.")
+            else:
+                nr = 10 * np.log10(after / before)
+                st.metric("Noise Reduction", f"{nr:.2f} dB", 
+                help="Noise reduction due to acoustic treatment" )
+                df_new = df.copy()
+                df_new["dBA"] = df_new["dBA"] - nr
+                fig = plot_bn_band(
+                    df_new["Location"], df_new["dBA"],
+                    st.session_state.bn_min, st.session_state.bn_max,
+                    "Final Background Noise vs Standard Range",
+                )
+                st.plotly_chart(fig, use_container_width=True)
+                st.session_state.fig_bn_final = fig
+
+    # ── AI final check ─────────────────────────────────────────────────────-
+    with t_si:
+        st.write("""When you apply acoustic treatment to a room, the noise reduction 
+        resulting from increased sound absorption will deacrease the sound pressure
+        levels used in calcuating AI""")
+        if st.session_state.df_spl is None or not combined:
+            st.warning("⚠️ Upload SPL data and run Acoustic Treatment first.")
+        else:
+            before = sum(st.session_state.current_absorption.values())
+            after = sum(combined.values())
+            nr_db = 10 * np.log10(after / before) if before else 0
+            df_new_spl = st.session_state.df_spl - nr_db
+            st.markdown("###### New sound pressure levels after acoustic treatment")
+            st.write("""For each location in the table below, plot the new sound pressure
+            levels on the dots graph, count dots above the line, and calculate AI below.""")
+            st.dataframe(df_new_spl, use_container_width=True)
+
+            st.markdown("Articulation Index (AI) calculation")
+            ai_rows = []
+            for loc in df_new_spl.index:
+                key = slugify(f"dots_final_{loc}")
+                default = st.session_state.dots_final_dict.get(loc, 0)
+                dots = st.number_input(
+                    f"Dots above ({loc})", 0, TOTAL_DOTS,
+                    step=1, value=default, key=key)
+                st.session_state.dots_final_dict[loc] = dots
+                ai, interp = articulation_index(dots) if dots else (None, "")
+                st.session_state.ai_final_dict[loc] = (ai, interp)
+                ai_rows.append({
+                    "Location": loc,
+                    "AI": f"{ai:.2f}" if ai is not None else "",
+                    "Interpretation": interp,
+                })
+            st.dataframe(pd.DataFrame(ai_rows), use_container_width=True)
+
+    nav_buttons()
+
+
+# ---------------------------------------------------------------------------
+def section_faq() -> None:
+    st.title("🔊 Building Acoustics Analysis Tool")
+
+    with st.expander("App Information", expanded=False):
+        st.write("""
+            - This app is intended for educational purposes only and should not be used for professional purposes.
+        """)
+    
+    st.header("❓ FAQ / Help")
+    faq_content = """
+    ### Frequently Asked Questions
+    **Q1: What should I do if the data upload fails?**
+    Ensure your file is in the correct format (CSV or Excel). Check that the column headings are consistent with the expected format (e.g., `125`, `250`, `500`, `1000`, `2000`, `4000` or `125Hz`, `250Hz`, `500Hz`, `1KHz`, `2KHz`, `4KHz`). Remove any extra rows or columns that do not contain relevant data.
+    **Q2: How do I interpret the RT60 values?**
+    RT60 values represent the time it takes for the sound to decay by 60 dB in a room. Lower RT60 values indicate faster sound decay and are preferable for environments where speech intelligibility is important. Higher RT60 values might be suitable for spaces intended for musical performances.
+    **Q3: Why is my calculated RT60 not within the standard range?**
+    This may occur if the room's current materials are not adequately absorbing sound. You may need to introduce new materials with higher absorption coefficients or increase the surface area of existing materials.
+    **Q4: What should I do if the app does not accept my frequency columns?**
+    The app standardizes frequency columns to numerical values (e.g., `125`, `250`) regardless of their initial format (e.g., `125Hz`, `125 Hz`). Ensure that the frequency values in your uploaded file are correctly formatted and consistent.
+    **Q5: How can I improve speech intelligibility in my room?**
+    To improve speech intelligibility, aim for a lower RT60 across the relevant frequencies, particularly in the range of 500 Hz to 4000 Hz. This can be achieved by adding more sound-absorbing materials, such as acoustic panels or curtains.
+    **Q6: How can I save my analysis results?**
+    You can download the PDF report, which includes all the data and graphs from your analysis. Click the "Download PDF Report" button at the end of your analysis to save the report to your device.
+    ### Troubleshooting Tips
+    - **Data Upload Issues**: If you encounter issues uploading data, double-check the format and structure of your file. Ensure the first row contains column headings and the data is organized as per the examples provided.
+    - **Unexpected Results**: If your analysis results seem incorrect, verify the accuracy of the input data, including the room volume and material properties. Incorrect input data can lead to erroneous calculations.
+    - **App Performance**: If the app is running slowly, consider optimizing your data size and complexity. Large datasets or highly detailed input may impact performance.
+    
+    """
+    st.markdown(faq_content)
+    nav_buttons()