build files added

README.md

@@ -1,14 +1,63 @@
 ---
-title: Antibody Database
-emoji: 🦀
-colorFrom: yellow
-colorTo: yellow
+title: Antibody Database Dashboard
+emoji: 🔎
+colorFrom: blue
+colorTo: green
 sdk: gradio
-sdk_version: 5.49.0
-app_file: app.py
+sdk_version: 4.0.0
+app_file: dashboard.py
 pinned: false
 license: mit
-short_description: 'Interactive antibody database - filter, analyze, and export '
+short_description: Interactive antibody database - filter, analyze, and export 
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# 🧬 Antibody Database Dashboard
+
+An interactive web dashboard for exploring antibody sequence data using Gradio and Plotly. This dashboard allows users to filter antibody sequences by various criteria and visualize the data through interactive charts.
+
+## Features
+
+- **Interactive Filtering**: Filter sequences by VH/VL germline, B-cell type, disease, and sequence length
+- **Data Visualization**: 
+  - VH and VL germline distribution charts
+  - Length distribution histograms
+  - Year-wise sequence distribution
+- **Data Export**: Download filtered sequences as FASTA files
+- **Real-time Statistics**: View sequence counts and statistics
+
+## 🚀 Usage
+
+1. **Select Filters**:
+   - Choose VH and VL germlines from dropdowns
+   - Select B-cell type and disease
+   - Adjust sequence length sliders
+
+2. **Apply Filters**:
+   - Click "Apply Filters" to update the dashboard
+   - View filtered data in the table
+   - Explore visualizations
+
+3. **Export Data**:
+   - Download filtered sequences as FASTA files
+   - View sequence counts and statistics
+
+## 📋 Requirements
+
+- Python 3.11+
+- Required packages (see `requirements.txt`):
+  - `gradio>=4.0.0`
+  - `pandas>=1.5.0`
+  - `plotly>=5.0.0`
+  - `huggingface_hub>=0.16.0`
+  - `numpy>=1.21.0`
+
+## 🗂️ Project Structure
+
+```
+dashboard_learning/
+├── dashboard.py               # Main dashboard application
+├── utils.py                   # Utility functions for data processing
+├── requirements.txt           # Python dependencies
+└── README.md                  # This file
+```
+

app.py

@@ -0,0 +1,160 @@
+import gradio as gr
+import sqlite3
+import pandas as pd
+import plotly.express as px
+from utils import *
+from huggingface_hub import hf_hub_download
+
+db_path = hf_hub_download(
+    repo_id="hemantn/antibody-paired-sequences",
+    filename="antibody_data_year.db",
+    repo_type="dataset"
+)
+
+
+conn = sqlite3.connect(db_path, check_same_thread=False)
+
+#conn = sqlite3.connect('/data/hn533621/OAS/Paired_Data_Analysis/antibody_data_year.db', check_same_thread=False)
+all_df = pd.read_sql("SELECT * FROM antibody_data", conn)
+
+# Compute min / max for each column
+vh_min, vh_max = int(all_df["vh_length"].min()), int(all_df["vh_length"].max())
+vl_min, vl_max = int(all_df["vl_length"].min()), int(all_df["vl_length"].max())
+
+def apply_filters(dropdown_1, dropdown_2, dropdown_3, dropdown_4, slider_vh, slider_vl):
+    """
+    Build a query to filter the data based on the user's input
+    """
+    clauses = []
+    params = {}
+    if dropdown_1: clauses.append('v_call_heavy_first = :vh_germline');  params['vh_germline'] = dropdown_1
+    if dropdown_2: clauses.append('v_call_light_first = :vl_germline');  params['vl_germline'] = dropdown_2
+    if dropdown_3: clauses.append('BType = :btype');  params['btype'] = dropdown_3
+    if dropdown_4: clauses.append('Disease = :disease');  params['disease'] = dropdown_4
+    if slider_vh:
+       clauses.append("vh_length BETWEEN :vh_min AND :vh_max")
+       params["vh_min"] = 80
+       params["vh_max"] = slider_vh
+    if slider_vl:
+        clauses.append("vl_length BETWEEN :vl_min AND :vl_max")
+        params["vl_min"] = 80
+        params["vl_max"] = slider_vl
+
+    sql = "SELECT * FROM antibody_data"
+    if clauses:
+        sql += " WHERE " + " AND ".join(clauses)
+
+    df = pd.read_sql_query(sql, conn, params=params)
+    #print(df.columns)
+        # ---- Reorder and rename columns ----
+    # 1. Rename to your desired display names
+    rename_map = {
+        "BType": "BType",
+        "Disease": "Disease",
+        "v_call_heavy_first": "vcall_VH",
+        "v_call_light_first": "vcall_VL",
+        "vh_length": "VH_length",
+        "vl_length": "VL_length",
+        "sequence_alignment_aa_heavy": "VH",
+        "sequence_alignment_aa_light": "VL",
+        "Year": "Year",
+    }
+    df = df.rename(columns=rename_map)
+
+    # 2. Reorder the columns
+    desired_order = [
+        "BType",
+        "Disease",
+        "vcall_VH",
+        "vcall_VL",
+        "VH_length",
+        "VL_length",
+        "Year",
+        "VH",
+        "VL",
+    ]
+    # Only keep columns that actually exist (avoids errors if some missing)
+    df = df[[c for c in desired_order if c in df.columns]]
+    
+    total_rows = conn.execute("SELECT COUNT(*) FROM antibody_data").fetchone()[0]
+    #vcall_vh_bar = bar_vcall_vh(df, total_rows, dropdown_1)
+    year_bar = bar_year_count(df)
+    #vcall_vl_bar = bar_vcall_vl(df, total_rows, dropdown_2)
+    combined_vh_vl_bar = bar_vh_vl_combined(df, total_rows, dropdown_1, dropdown_2)
+    #disease_bar  = bar_disease_count(df, total_rows, dropdown_4)
+    #btype_bar = bar_btype_count(df, total_rows, dropdown_3)
+    vh_fig, vl_fig = hist_vh_vl_separate(df)
+    fasta_file = make_fasta_file(df)
+    total_sequences = 2*len(df)
+    return df.head(5), combined_vh_vl_bar, year_bar, vh_fig, vl_fig, fasta_file, total_sequences
+
+with gr.Blocks(theme=gr.themes.Ocean()) as demo:
+    gr.Markdown(
+        """
+        <h1 style='text-align:center; color:#3A7; margin-bottom:0.5em;'>🔎 Antibody Database Dashboard</h1>
+        <p style='text-align:center; color:gray;'>
+        Filter sequences, explore counts, and download custom FASTA files.
+        </p>
+        """
+    )
+
+    with gr.Row():
+        with gr.Column(scale=1):
+            dropdown_1 = gr.Dropdown(choices = [""] + sorted(all_df['v_call_heavy_first'].unique()), \
+                value = None, label = 'VH germline')
+            dropdown_2 = gr.Dropdown(choices = [""] + sorted(all_df['v_call_light_first'].unique()), \
+                value = None, label = 'VL germline')
+            dropdown_3 = gr.Dropdown(choices = [""] + sorted(all_df['BType'].unique()), \
+                value = None, label = 'B-Type')
+            dropdown_4 = gr.Dropdown(choices = [""] + sorted(all_df['Disease'].unique()), \
+                value = None, label = 'Disase')
+
+            slider_vh = gr.Slider(value=vh_max, minimum=vh_min, maximum=vh_max, step=1, label = 'VH length') 
+            slider_vl = gr.Slider(value=vl_max, minimum=vl_min, maximum=vl_max, step=1, label = 'VL length')  
+
+            button = gr.Button('Apply Filters', variant='primary')
+
+        with gr.Column(scale=2):
+            with gr.Row():
+                with gr.Column(scale=1):
+                      combined_vh_vl_bar = gr.Plot(label = 'VH and VL Germline')
+                with gr.Column(scale=1):
+                      vh_fig = gr.Plot(label = 'VH Length Distribution')
+            with gr.Row():
+                with gr.Column(scale=1):
+                      year_bar = gr.Plot(label = 'Year Wise Distribution')
+                with gr.Column(scale=1):
+                      vl_fig = gr.Plot(label = 'VL Length Distribution')
+
+    with gr.Row():
+        #with gr.Column(scale=0.3):
+            #gr.Plot(label= 'Yearwise distribution of antibodies')
+        with gr.Column(scale=1):
+            with gr.Row():
+                 with gr.Column(scale=2):
+                     df_out = gr.Dataframe()
+                 with gr.Column(scale=1):
+                     fasta_file = gr.File(label= 'Download Antibody Data Fasta file', interactive=False)
+
+                     with gr.Row():
+                        total_sequences = gr.Textbox(label= 'No of Sequences in Fasta file', value=0, interactive=False)
+                    
+    
+    slider_vh.input(update_vh, inputs=slider_vh, outputs=slider_vh, queue=False)
+    slider_vl.input(update_vl, inputs=slider_vl, outputs=slider_vl, queue=False)
+
+    inputs = [dropdown_1, dropdown_2, dropdown_3, dropdown_4, slider_vh, slider_vl]
+    #outputs = df,
+    #outputs = [plot_vh_germline, plot_vl_germline, plot_disease_count, plot_btype_count, \
+    #                plot_year_data, dataframe, download_fasta]
+    
+    button.click(
+        fn=apply_filters,
+        inputs = inputs,
+        outputs = [df_out, combined_vh_vl_bar, year_bar, vh_fig, vl_fig, fasta_file, total_sequences]
+    )
+
+if __name__ == '__main__':
+    demo.launch()
+
+    

requirements.txt

@@ -0,0 +1,5 @@
+gradio=5.48.0
+pandas>=1.5.0
+plotly=5.25.0
+huggingface_hub=0.29.3
+numpy=1.26.4

utils.py

@@ -0,0 +1,414 @@
+import pandas as pd
+import plotly.express as px
+import tempfile
+
+def update_vh(vh_len):
+    return vh_len
+def update_vl(vl_len):
+    return vl_len
+
+#def make_fasta_file(df: pd.DataFrame):
+#    if df.empty:
+#        return None
+#    lines = []
+#    i = 1
+#    for _, row in df.iterrows():
+#        header = f">{i}_{row['vcall_VH']}|{row['Disease']}"
+#        lines.append(header)
+#        lines.append(row['VH'])
+#        header = f">{i}_{row['vcall_VL']}|{row['Disease']}"
+#        lines.append(header)
+#        lines.append(row['VL'])
+#    tmp = tempfile.NamedTemporaryFile(delete=False, suffix=".fasta")
+#    tmp.write("\n".join(lines).encode())
+#    tmp.close()
+#    return tmp.name
+
+def make_fasta_file(df: pd.DataFrame):
+    """
+    Vectorized FASTA file creation - ~100x faster than loop-based approach.
+    Optimized for large datasets (1M+ sequences).
+    """
+    if df.empty:
+        return None
+    
+    import numpy as np
+    
+    # Create sequence IDs as a vector
+    n_seqs = len(df)
+    seq_ids = np.arange(1, n_seqs + 1)
+    
+    # Vectorized header creation using string concatenation
+    vh_headers = ">" + seq_ids.astype(str) + "_" + df['vcall_VH'].astype(str) + "|" + df['Disease'].astype(str) + "|VH"
+    vl_headers = ">" + seq_ids.astype(str) + "_" + df['vcall_VL'].astype(str) + "|" + df['Disease'].astype(str) + "|VL"
+    
+    # Interleave headers and sequences using numpy array indexing
+    fasta_content = np.empty((n_seqs * 4,), dtype=object)
+    fasta_content[0::4] = vh_headers  # VH headers at positions 0, 4, 8, ...
+    fasta_content[1::4] = df['VH'].astype(str)  # VH sequences at positions 1, 5, 9, ...
+    fasta_content[2::4] = vl_headers  # VL headers at positions 2, 6, 10, ...
+    fasta_content[3::4] = df['VL'].astype(str)  # VL sequences at positions 3, 7, 11, ...
+    
+    # Write to file in one operation (much faster than multiple writes)
+    tmp = tempfile.NamedTemporaryFile(mode='w', delete=False, suffix=".fasta", newline='')
+    tmp.write('\n'.join(fasta_content))
+    tmp.close()
+    return tmp.name
+
+
+def pie_vcall_vh(df: pd.DataFrame, total_raws: int, width: int = 500, height: int = 400) -> px.pie:
+
+    current_count = len(df)
+    remaining = total_raws - current_count
+    values = [current_count, remaining]
+    #labels = ['Selected', 'Remaining']
+    fig = px.pie(values=values)
+    fig.update_layout(width=width, height=height)
+    return fig
+
+def bar_vcall_vh(df: pd.DataFrame, total_rows: int, vh_germline: str,
+                 width: int = 500, height: int = 250) -> px.bar:
+    """
+    Horizontal bar chart showing Selected vs Remaining counts.
+
+    Parameters
+    ----------
+    df : pd.DataFrame
+        Filtered dataframe from your query.
+    total_rows : int
+        Total number of rows in the full database.
+    width, height : int
+        Size of the resulting figure in pixels.
+    """
+    current_count = len(df)
+    remaining = total_rows - current_count
+    
+    label_selected = vh_germline if vh_germline else "All Germlines"
+
+    plot_df = pd.DataFrame({
+        "Category": [label_selected, "Remaining"],
+        "Count": [current_count, remaining]
+    })
+
+    fig = px.bar(
+        plot_df,
+        x="Count",
+        y="Category",
+        orientation="h",         # horizontal bars
+        text="Count",            # show numbers on bars
+        color="Category",
+        color_discrete_map={
+            "Selected Germline": "#3A7",  # greenish
+            "Remaining": "#0000FF"           # gray #999
+        }
+    )
+
+    fig.update_layout(
+        width=width,
+        height=height,
+        showlegend=False,
+        plot_bgcolor="white",
+        xaxis_title="Number of Sequences",
+    )
+
+    return fig
+
+def bar_vcall_vl(df: pd.DataFrame, total_rows: int, vl_germline: str,
+                 width: int = 500, height: int = 250) -> px.bar:
+    """
+    Horizontal bar chart showing Selected vs Remaining counts.
+
+    Parameters
+    ----------
+    df : pd.DataFrame
+        Filtered dataframe from your query.
+    total_rows : int
+        Total number of rows in the full database.
+    width, height : int
+        Size of the resulting figure in pixels.
+    """
+    current_count = len(df)
+    remaining = total_rows - current_count
+    
+    label_selected = vl_germline if vl_germline else "All Germlines"
+
+    plot_df = pd.DataFrame({
+        "Category": [label_selected, "Remaining"],
+        "Count": [current_count, remaining]
+    })
+
+    fig = px.bar(
+        plot_df,
+        x="Count",
+        y="Category",
+        orientation="h",         # horizontal bars
+        text="Count",            # show numbers on bars
+        color="Category",
+        color_discrete_map={
+            "Selected Germline": "#3A7",  # greenish
+            "Remaining": "#0000FF"           # gray #999
+        }
+    )
+
+
+    fig.update_layout(
+        width=width,
+        height=height,
+        showlegend=False,
+        plot_bgcolor="white",
+        xaxis_title="Number of Sequences",
+    )
+
+    return fig
+
+def bar_disease_count(df: pd.DataFrame,
+                      total_rows: int,
+                      disease: str,
+                      width: int = 500,
+                      height: int = 250) -> px.bar:
+    """
+    Horizontal bar chart showing the count for the selected Disease
+    versus all remaining rows in the database.
+
+    Parameters
+    ----------
+    df : pd.DataFrame
+        Filtered dataframe from your query (the rows matching filters).
+    total_rows : int
+        Total number of rows in the full database.
+    disease : str
+        Disease name chosen in the UI (e.g., "SARS-COV-2").
+    width, height : int
+        Size of the resulting figure.
+    """
+    current_count = len(df)
+    remaining = total_rows - current_count
+
+    label_selected = disease if disease else "All Diseases"
+
+    plot_df = pd.DataFrame({
+        "Category": [label_selected, "Remaining"],
+        "Count": [current_count, remaining]
+    })
+
+    fig = px.bar(
+        plot_df,
+        x="Count",
+        y="Category",
+        orientation="h",
+        color="Category",
+        color_discrete_map={label_selected: "#d62728", "Remaining": "#999"}  # red & gray
+    )
+
+    # Remove all labels/legend for a clean look
+    fig.update_layout(
+        width=width,
+        height=height,
+        showlegend=False,
+        plot_bgcolor="white",
+    )
+
+    return fig
+
+def bar_btype_count(df: pd.DataFrame,
+                    total_rows: int,
+                    btype: str,
+                    width: int = 500,
+                    height: int = 250) -> px.bar:
+    """
+    Horizontal bar chart showing the count for the selected B-cell type
+    versus the remaining rows in the database.
+
+    Parameters
+    ----------
+    df : pd.DataFrame
+        Filtered dataframe from your query (rows matching filters).
+    total_rows : int
+        Total number of rows in the full database.
+    btype : str
+        B-cell type selected in the UI (e.g., "Memory-B-Cells").
+    width, height : int
+        Size of the figure in pixels.
+    """
+    current_count = len(df)
+    remaining = total_rows - current_count
+
+    label_selected = btype if btype else "All B-Types"
+
+    plot_df = pd.DataFrame({
+        "Category": [label_selected, "Remaining"],
+        "Count": [current_count, remaining]
+    })
+
+    fig = px.bar(
+        plot_df,
+        x="Count",
+        y="Category",
+        orientation="h",
+        color="Category",
+        color_discrete_map={label_selected: "#1f77b4",  # blue
+                            "Remaining": "#999"}        # gray
+    )
+
+    fig.update_layout(
+        width=width,
+        height=height,
+        showlegend=False,
+        plot_bgcolor="white",
+    )
+
+    return fig
+
+def hist_vh_vl_separate(df: pd.DataFrame,
+                    width: int = 500,
+                    height: int = 250) -> tuple[px.histogram, px.histogram]:
+     """
+     Returns two separate histograms: one for VH_length, one for VL_length.
+     """
+
+     vh_fig = px.histogram(
+         df,
+         x="VH_length",
+         nbins=40,
+         color_discrete_sequence=["#ff5c77"],  #blue
+         labels={"count": "Count"}
+     )
+     vh_fig.update_layout(width=width, height=height,
+                          plot_bgcolor="white",
+                          yaxis_title="Count"
+                          )
+ 
+     vl_fig = px.histogram(
+         df,
+         x="VL_length",
+         nbins=40,
+         color_discrete_sequence=["#00ffff"],  # VL color (red)
+         labels={"count": "Count"}
+     )
+     vl_fig.update_layout(width=width, height=height,
+                          plot_bgcolor="white",
+                          yaxis_title="Count"
+                          )
+ 
+     return vh_fig, vl_fig
+
+def bar_vh_vl_combined(
+    df: pd.DataFrame,
+    total_rows: int,
+    vh_germline: str | None,
+    vl_germline: str | None,
+    width: int = 500,
+    height: int = 250
+) -> px.bar:
+    """
+    Horizontal bar chart with three bars:
+      1. Selected VH germline count
+      2. Selected VL germline count
+      3. Remaining = (2 * total_rows) - VH_count - VL_count
+    """
+
+    # Count VH matches
+    if vh_germline:
+        vh_count = (df["vcall_VH"] == vh_germline).sum()
+    else:
+        vh_count = len(df)
+
+    # Count VL matches
+    if vl_germline:
+        vl_count = (df["vcall_VL"] == vl_germline).sum()
+    else:
+        vl_count = len(df)
+
+    # Remaining sequences = 2 * total_rows - VH_count - VL_count
+    remaining = (2 * total_rows) - (vh_count + vl_count)
+
+    plot_df = pd.DataFrame({
+        "Category": [
+            vh_germline if vh_germline else "All Germlines",
+            vl_germline if vl_germline else "All Germlines",
+            "Remaining"
+        ],
+        "Count": [vh_count, vl_count, remaining]
+    })
+
+    fig = px.bar(
+        plot_df,
+        x="Count",
+        y="Category",
+        orientation="h",
+        text="Count",
+        color="Category",
+        color_discrete_map={
+            (vh_germline if vh_germline else "All Germlines"): "#3A7",
+            (vl_germline if vl_germline else "All Germlines"): "#FF7F0E",
+            "Remaining": "#0000FF"
+        }
+    )
+
+    fig.update_layout(
+        width=width,
+        height=height,
+        showlegend=False,
+        plot_bgcolor="white",
+        xaxis_title="Number of Sequences",
+    )
+
+    return fig
+
+def bar_year_count(
+    df: pd.DataFrame,
+    width: int = 500,
+    height: int = 250
+) -> px.bar:
+    """
+    Horizontal bar chart of sequence counts per Year.
+
+    Parameters
+    ----------
+    df : pd.DataFrame
+        DataFrame that includes a 'Year' column.
+    width, height : int
+        Size of the figure.
+
+    Returns
+    -------
+    plotly.graph_objects.Figure
+    """
+    if "Year" not in df.columns:
+        raise ValueError("DataFrame must contain a 'Year' column.")
+
+    # Count sequences per year and sort descending
+    year_counts = 2 *df["Year"].value_counts().sort_index()
+
+    # Create a DataFrame for plotting
+    plot_df = pd.DataFrame({
+        'Year': year_counts.index.astype(str),
+        'Count': year_counts.values
+    })
+    
+    fig = px.bar(
+        plot_df,
+        x='Count',
+        y='Year',
+        orientation="h",
+        text='Count',
+        color="Year",                 # <─ use Year as the color key
+        color_discrete_sequence=px.colors.qualitative.Light24  # or any palette you like
+    )
+
+    fig.update_layout(
+        width=width,
+        height=height,
+        plot_bgcolor="white",
+        paper_bgcolor="white",
+        xaxis_title="Number of Sequences",
+        yaxis_title="Year",
+        showlegend=False
+    )
+    # Remove grid lines for a cleaner look
+    fig.update_xaxes(showgrid=False)
+    fig.update_yaxes(showgrid=False)
+
+    return fig
+
+