How do I browse cell type contexts?

Click on "Browse Cell Types" in the navigation menu. You'll see a table listing all unique cell type contexts in the database, including cell type name, study, species, tissue, condition, and average specificity score.

What is a "cell type context"?

A cell type context is a unique combination of cell type, study, species, tissue, and condition. The same cell type (e.g., "Microglia") may appear multiple times if it's from different studies, species, or tissues.

What is the Average Specificity score?

The Average Specificity is calculated from the top 30 highest-scoring marker genes for that cell type context. It provides a summary measure of how well-defined the markers are for that specific context.

How do I view all markers for a cell type?

Click the "View Markers" button next to any cell type context in the Browse Cell Types page. This will redirect you to the Search page with filters pre-filled to show all markers for that specific context.

How do I search for specific markers?

Navigate to the "Search" page and use the filter dropdowns to narrow down results by:

• Gene: Search for a specific gene symbol
• Cell Type: Filter by cell type name
• Study/Publication: Filter by study identifier
• Species: Filter by species (e.g., Human, Mouse)
• Tissue: Filter by tissue type
• Condition: Filter by experimental condition
• Min. Specificity Score: Set a minimum threshold for specificity

You can combine multiple filters to narrow your search.

Why don't I see any results?

If no results appear, try:

• Using fewer filters to broaden your search
• Checking your gene symbol spelling (use uppercase)
• Lowering the minimum specificity score threshold
• Verifying that the combination of filters exists in the database

Can I download search results?

Yes! After performing a search, click the "Download Results" button at the top-right of the page. You will need to enter a valid invitation code to export your results as a CSV file.

What does the Analyze Genes tool do?

The Analyze Genes tool helps you infer potential cell types from a list of genes. Enter a comma-separated list of gene symbols, and the tool will search for these genes in the database and summarize potential cell type contexts based on matching genes and their specificity scores.

How do I use the Analyze Genes feature?

1. Navigate to the "Analyze Genes" page
2. Enter a comma-separated list of gene symbols in the text box
3. Optionally, add exclude filters to remove unwanted results
4. Click "Analyze Genes"
5. Review the ranked results showing potential cell type contexts

Tip: Try the example gene lists (Example 1, 2, or 3) to see how the tool works!

How are results ranked?

Results are ranked by:

1. Gene Count: Number of your input genes that match markers for that cell type context
2. Average Specificity Score: Average specificity of the matched genes

Cell type contexts with more matched genes and higher specificity scores appear at the top.

What are Exclude Filters?

Exclude filters let you remove unwanted results based on cell type name, study, species, or tissue. For example, if you only want human results, you can exclude "Mouse" from the species field.

Can I click on cell types in the results?

Yes! Cell type names in the results table are clickable. Clicking a cell type will redirect you to the Search page with filters pre-filled to show all markers for that specific cell type context.

What gene symbols should I use?

Use standard gene symbols (e.g., HUGO symbols for human genes). Gene symbols are case-insensitive but will be converted to uppercase for searching. Separate multiple genes with commas, spaces, semicolons, or line breaks.

Can I download analysis results?

Yes! Click the "Download Results" button after analyzing your gene list. You will need to enter a valid invitation code to export the results as a CSV file.

Is there an API available?

Yes! PIASOmarkerDB provides a RESTful API for programmatic access. You can query markers, cell types, genes, and studies using HTTP requests.

What API endpoints are available?

• GET /api/v1/markers - Query marker genes with filters
• GET /api/v1/cell-types - Get all cell type contexts
• GET /api/v1/genes - Get all unique genes
• GET /api/v1/studies - Get all studies with metadata

How do I use the API from Python?

We provide a Python client library for easy access. Install it and use as follows:

from piasomarkerdb import PIASOmarkerDBClient

# Initialize client
client = PIASOmarkerDBClient()

# Get markers for a specific gene
markers = client.get_markers(gene="CD3E")

# Get markers for a cell type
markers = client.get_markers(cell_type="T-cell")

# Get as pandas DataFrame
df = client.get_markers_df(gene="CD3E,CD19")

API Query Parameters

The /api/v1/markers endpoint supports these parameters:

• gene - Filter by gene symbol (comma-separated for multiple)
• cell_type - Filter by cell type (comma-separated for multiple)
• study - Filter by study/publication
• species - Filter by species
• tissue - Filter by tissue
• condition - Filter by condition
• min_score - Minimum specificity score
• max_score - Maximum specificity score
• limit - Maximum results (default: 1000, max: 10000)
• offset - Pagination offset
• format - Response format ('json' or 'csv')

Can I download the entire database?

Yes! Navigate to the "Download" page and click "Download All Data (CSV)" to export the complete PIASOmarkerDB dataset as a CSV file. You will need a valid invitation code to download.

What is an invitation code?

An invitation code is required to download data from PIASOmarkerDB. This helps us track usage and ensure data is used appropriately. Contact us to request an invitation code.

What format is the download?

All downloads are in CSV (Comma Separated Values) format, which can be opened in Excel, R, Python, or any spreadsheet/data analysis software.

What columns are included in the download?

Downloaded data includes:

• Cell Type
• Gene Symbol
• Specificity Score
• Study/Publication
• Species
• Tissue
• Condition

What browsers are supported?

PIASOmarkerDB works best on modern browsers including Chrome, Firefox, Safari, and Edge (latest versions).

What technology stack is used?

PIASOmarkerDB is built with:

• Backend: Python/Flask with PostgreSQL database
• Frontend: Bootstrap 5, jQuery, DataTables
• API: RESTful JSON API

How often is the database updated?

The database is updated periodically as new studies and datasets become available. Check the home page for the most recent statistics.

Can I contribute data to PIASOmarkerDB?

If you have marker gene data from published studies that you'd like to contribute, please contact Min Dai at dai@broadinstitute.org.

Who maintains PIASOmarkerDB?

PIASOmarkerDB is developed and maintained by the Gord Fishell Laboratory at Harvard Medical School and Broad Institute of MIT and Harvard.

How do I cite PIASOmarkerDB?

If you use PIASOmarkerDB in your research, please cite:

• PIASOmarkerDB website: https://piaso.org/markerdb
• PIASO toolkit: https://piaso.org
• Reference: Wu, S., Dai, M. et al. (2024). Pyramidal neurons proportionately alter the identity and survival of specific cortical interneuron subtypes. bioRxiv. https://doi.org/10.1101/2024.07.20.604399

Formal PIASOmarkerDB publication and citation information will be added when available.

How can I get help or report issues?

For questions, issues, or feedback, please contact:

Min Dai - dai@broadinstitute.org