User Guide & Tutorial

Comprehensive guide for using the cEpiNets Browser to explore gene regulatory networks and visualize genomic interactions.

Performance Notice

Unfiltered searches can be very slow and may not produce expected results. We strongly recommend using filter conditions for all searches.

  • DO NOT use "All Conditions" or "All States" for searches - this will be very slow
  • ALWAYS select at least one Condition filter for better performance
  • In Plot Browser, use Distance Scope to limit range (avoid selecting "All")
  • Unfiltered searches query the entire database, which can be extremely slow and may not return results as expected

Best Practice: Start with a specific Condition. If you need multiple conditions, perform separate searches for better performance and more reliable results.

Quick Start Guide

1. Network Browser

  1. Navigate to the Network page
  2. Select a Condition (required - do not use "All")
  3. Optionally select a State filter
  4. Choose search type: Gene, CRE, or TF
  5. Enter your search term (e.g., "SORL1" for a gene)
  6. Click Search to visualize the network

2. Plot Browser (IGV)

  1. Navigate to the Plot Browser page
  2. Select a Condition (required to see TF Binding Sites)
  3. Optionally select a State filter
  4. Set Distance Scope (default: ±50 kb, avoid "All")
  5. Enter a gene name in Search Term
  6. Click Search to load tracks and navigate to the genomic region

Network Browser Tutorial

Search Functionality

The Network Browser supports three search types, each returning different network structures:

  • Gene Search: Returns the complete regulatory network (Gene → CRE → TF)
  • CRE Search: Returns all Genes and TFs connected to the specified CRE
  • TF Search: Returns all CREs and Genes regulated by the specified transcription factor

Note: The searched node type will be displayed larger in the visualization.

Filter Options

Condition Filter (Required):

  • Select a specific experimental condition (e.g., "AD", "SORL1KO")
  • Do not use "All Conditions" - this will be very slow and may not produce expected results
  • If you need multiple conditions, perform separate searches

State Filter (Optional):

  • Filter by chromatin state: active, repressed, poised, or bivalent
  • Can be combined with Condition filter for more specific results

Important: After changing any filter, you must click the Search button again. The system does not automatically update.

Network Graph Interactions

  • Hover over nodes to view details and highlight connected edges
  • Click nodes to view detailed information in the sidebar
  • Drag nodes to reposition them
  • Scroll to zoom in/out (labels appear at 180% zoom or higher)
  • Drag on empty space to pan the view
  • Toggle "Show CRE Labels" to show/hide CRE node labels

Node Sizing: Node size is dynamically adjusted based on the number of connections (degree). Nodes with more connections appear larger, helping identify key network hubs.

Table View

The table view is always available below the network graph and displays:

  • Gene-CRE-TF-Context relationships in tabular format
  • Sortable columns for easy data exploration
  • Search functionality to filter results
  • Automatically used when networks exceed visualization limits (500 nodes or 1000 edges)

Network Size Limits

Networks with more than 500 nodes or 1000 edges will automatically display a warning and switch to table view. Use Condition and State filters to reduce network size.

Plot Browser (IGV) Tutorial

Gene Search and Navigation

The Plot Browser automatically navigates to the genomic location of searched genes:

  • Enter a gene name (e.g., "SORL1", "APP") in the Search Term field
  • The browser automatically navigates to the gene's TSS (transcription start site) region
  • Requirement: The gene must have genome-level annotation (TSS coordinates)
  • Pseudogenes or non-coding RNAs without TSS coordinates will show an error
  • Recommend searching for protein-coding genes

Track Loading and Management

Track Loading Order:

  1. RefSeq Genes - Default gene annotation track (always loaded)
  2. GWAS Variants - Disease-associated variant sites (loaded if region is not 'all')
  3. Interactions - CRE-Gene interaction arcs (condition-specific)
  4. TF Binding Sites - Transcription factor binding sites (only if Condition is selected)

Critical: You must select a Condition to see TF Binding Sites track. Without a condition, only CRE regions and Interactions will be displayed.

Distance Scope Filtering

Distance Scope controls which CRE-Gene interactions are displayed based on distance from the gene TSS:

  • Default: ±50 kb (recommended for most analyses)
  • Options: ±50 kb, ±100 kb, ±200 kb, or All
  • Distance is calculated from CRE midpoint to gene TSS
  • Avoid "All" - This can be very slow and may not load properly

Important: After changing Distance Scope, you must click the Search button again. The IGV browser will not automatically reload tracks.

Filter Behavior

Critical Understanding:

After changing any filter (Condition, State, or Distance Scope), you must:

  1. Ensure your Search Term is entered or confirmed
  2. Click the Search button
  3. Wait for the IGV browser to reload tracks

The system does not automatically update. This design prevents frequent automatic reloading that could impact performance.

Track Display Logic

  • CRE Regions: Only CREs with TF binding in the selected condition are displayed
  • Interactions: Only interactions under the selected condition are shown
  • TF Binding Sites: Only displayed when a Condition is selected
  • If a CRE has no TF binding in the selected condition, it will not appear even if it has a LINK relationship with the gene

Interactive Features

  • Use the IGV toolbar to zoom, pan, and navigate
  • Click on tracks to view detailed information
  • Use the search box in IGV to jump to specific genomic coordinates
  • Track legend at the bottom shows all currently loaded tracks
  • Click "Clear results" to remove all dynamically loaded tracks

Limitations and Considerations

Network Visualization Limits

  • Maximum 500 nodes or 1000 edges for graph visualization
  • Networks exceeding these limits automatically switch to table view
  • Table view is always available and supports sorting and searching
  • Use Condition and State filters to reduce network size

Plot Browser Limitations

  • Condition selection is required to display TF Binding Sites
  • Genes must have genome coordinates (TSS) to use Plot Browser
  • Only CREs with TF binding in the selected condition are displayed
  • Distance Scope changes require clicking Search button to take effect

Data Range

  • Experimental Conditions: 22 conditions available (AD, CD33, CLU-CRISPR, HIV-ACTvsLAT, HIVlatent, INPP5D, SORL1A528T, SORL1KO, TREM2KO, TREM2R47H, WTC11-IFN, iPSC-coculture, iPSC-xenot12d, iPSC-xenot7d, iPSC-xenot8w, and more)
  • Chromatin States: active, repressed, poised, bivalent
  • Genome Version: hg38 (human reference genome)

Performance Considerations

  • Important: Unfiltered searches can be very slow and may not produce expected results - always use filter conditions
  • DO NOT use "All" for searches - this queries the entire database and will be extremely slow
  • Large network queries may take longer - use filter conditions to improve performance
  • In Plot Browser, Distance Scope set to "All" may load very slowly or fail - use specific ranges (±50kb, ±100kb, ±200kb)
  • Always select at least one Condition filter for better performance and reliable results

Browser Compatibility

  • Recommended: Modern browsers (Chrome, Firefox, Safari, Edge)
  • IGV.js requires WebGL support
  • Use the latest browser version for best performance

Interaction Notes

  • All filter changes require clicking the Search button again
  • Plot Browser Distance Scope changes require re-searching
  • Network Browser Condition/State changes require re-searching
  • The system does not automatically update - this prevents performance issues from frequent reloading

Frequently Asked Questions

Why is the network graph not displaying?

  • Check if the network size exceeds limits (500 nodes or 1000 edges)
  • If exceeded, use the table view to explore the data
  • Try using Condition or State filters to narrow results

Why are TF Binding Sites not showing in Plot Browser?

  • You must select a Condition to display TF Binding Sites track
  • Check if a Condition is selected and click Search again
  • Without a Condition, only CRE regions and Interactions are displayed

Why don't changes appear after modifying filters?

  • After changing any filter, you must click the Search button
  • The system does not automatically update - manual search is required
  • This design prevents performance issues from automatic reloading

How can I narrow search results?

  • Must use Condition filter: Select a specific experimental condition (do not select "All")
  • Use State filter to select specific chromatin states
  • In Plot Browser, use Distance Scope to limit genomic range (do not select "All")
  • These filters not only narrow results but also improve performance and reliability

Why is there no result after searching for a gene?

  • Check if the gene name is correct (case-sensitive)
  • Verify the gene exists in the database
  • For Plot Browser, ensure the gene has genome coordinates (TSS)
  • Try searching for a protein-coding gene instead

What should I do if tracks fail to load?

  • Check your network connection
  • Verify your browser supports WebGL
  • Try refreshing the page or clearing browser cache
  • Ensure you have selected a Condition (for TF Binding Sites)

Best Practices

Search Strategy

  • Always start with a specific Condition - never use "All Conditions"
  • If you need multiple conditions, perform separate searches
  • Use State filters to further narrow results when needed
  • In Plot Browser, use Distance Scope to limit range (avoid "All")

Performance Optimization

  • Always use at least one filter (Condition) for better performance
  • Combine Condition and State filters for more specific queries
  • Use Distance Scope in Plot Browser to limit genomic regions
  • If a network is too large, use filters before searching

Workflow Tips

  • Set your filters before entering the search term
  • Remember to click Search after changing any filter
  • Use table view for large networks or data export
  • Clear results before starting a new search to avoid confusion

Need Help?

For additional questions or suggestions, please contact us via the project's issue tracker or repository.