Start a session and obtain the session_id that EVERY other tool on this server requires.

WHEN TO USE THIS TOOL: Call this ONCE at the beginning of a conversation, before any other mcp-genelab tool. Also call it again whenever a tool replies that the session is unknown or expired.

WHY: This server runs as a single shared process serving many users at once. The session id is the only thing that keeps YOUR output directory and YOUR generated plots (retrievable via fetch_plot, get_save_script and the plot://{session_id}/{filename} resource) separate from everyone else's. It is an opaque bearer token — treat it as private to this conversation and never guess one.

LIFETIME: A session expires after a period of inactivity (default 60 min) or an absolute maximum age (default 8 h), whichever comes first. Expired sessions drop their plots; regenerate them under a new session.

RETURNS: A short message containing session_id: <token>. Extract the token and pass it as the session_id argument on every subsequent call.

End a session immediately, discarding its output-directory setting and all plots it holds. Optional — sessions also expire on their own. Call it when the user is done, to free server memory promptly. After this, a new create_session() is needed before further tool calls.

Re-fetch the PNG bytes of a plot previously generated IN THIS SESSION.

WHEN TO USE THIS TOOL: Call this when you need the canonical PNG bytes for a plot that's already been generated. Common cases:

• The inline image in the original plot tool response was corrupted or didn't render in the client.

• You need the bytes for a downstream step (e.g. embedding in a transcript, saving to a side file, base64-encoding for an external API).

• The user asked to see the plot again without re-running the analysis.

WHAT THIS TOOL DOES NOT DO: It does NOT re-render the plot. It returns the same bytes that were registered when the plot was originally generated. If the underlying data has changed, re-run the plot tool itself (create_volcano_plot, create_venn_diagram); don't expect fetch_plot to pick up new data.

EQUIVALENT RESOURCE URI: This tool returns the same bytes that resources/read would return for plot://<session_id>/<filename>. Use whichever path your client supports better — resources for clients that render them well, this tool for clients that don't.

REGISTRY BOUNDS: Each session holds its last 8 plots (FIFO eviction). Older plots, and plots from other or expired sessions, return a clear "not in registry" error and need to be regenerated by re-running the source plot tool under the current session.

List all nodes, their attributes and their relationships to other nodes in the neo4j database. If this fails with a message that includes "Neo.ClientError.Procedure.ProcedureNotFound" suggest that the user install and enable the APOC plugin.

Configure the output directory for files generated in THIS SESSION.

WHEN TO USE THIS TOOL: Call this tool at the START of a session (right after create_session), before any tool that produces a downloadable file (create_volcano_plot, create_venn_diagram, or any tool that emits a CSV). The path you specify is where the user wants finished files to end up on THEIR OWN local machine.

WHAT IT DOES: Stores the provided path string in the server's session-scoped state (keyed on your session_id — other sessions cannot see or change it). Every subsequent file-producing tool in this session uses this path:

• As the user-facing save location shown in the response summary.

• As the default target path in the save guidance emitted with every plot.

• If the server is running locally (stdio transport), the server ALSO writes the file directly to this path.

IMPORTANT — DEPLOYMENT REALITY: When this MCP server is deployed remotely (ECS Fargate or any other container service), it runs in a container whose filesystem is NOT reachable from the user's machine. The server CANNOT write a file directly to the user's local disk over the network — no MCP server in a container can. The path you set here is a suggestion that propagates through the response in three ways, any of which lets the user save the file locally: (a) The plot is returned inline as ImageContent and renders in any MCP client that displays images (Claude Desktop, Cursor, Cline, Claude.ai web, ChatGPT, Gemini, etc.). The user can right-click and "Save Image As" — most clients default to the user's Downloads folder, which is usually what was asked for. (b) The path you set appears in the save guidance in the response. LLM clients with local filesystem access (Claude Code, Cursor, Cline, Claude Desktop with a filesystem MCP server) can write the file at exactly this path, re-fetching the canonical bytes via fetch_plot or the plot:// resource if needed. (c) Users without LLM-mediated filesystem access can save the inline image or the inline CSV text themselves.

VALIDATION: The path is stored as-is (the server does not verify it exists on the user's machine — it has no way to do so from inside a container). If you pass a relative path or an obviously malformed string the server will accept it; the failure will surface when the user tries to save the file locally.

Return the currently-configured output directory for this session.

Returns the path previously set by set_output_directory in the same session, or a note explaining that no path has been set yet (and how to set one).

Return guidance for saving a plot generated in THIS SESSION to the user's local filesystem.

WHEN TO USE THIS TOOL: Call this only when the user explicitly asks for save guidance for a specific plot — for example, "how do I save the volcano plot to my Downloads folder?" or "I can't right-click — give me another way to save the plot." By default plot tools (create_volcano_plot, create_venn_diagram) return only a SHORT save hint to keep response sizes manageable. The detailed save options are delivered on demand via this tool, so they don't burn conversation context unless the user actually wants them.

HOW IT WORKS: Each plot tool registers the PNG bytes of the plot it generated in the calling session's registry (up to the last 8 plots; older entries are evicted FIFO). Calling this tool with the plot's suggested filename returns a markdown block with three save options:

• Option A (right-click save on the inline image)

• Option B (ask your LLM client to save via filesystem access, optionally re-fetching the canonical bytes through fetch_plot or the plot:// resource if the inline image was corrupted)

• Option C (fetch the canonical PNG bytes via resources/read on the plot://<session_id>/ URI for clients that support MCP resources)

The response itself contains no PNG bytes — only references to the plot:// resource URI and the fetch_plot tool, both of which deliver the bytes through a separate request.

LISTING AVAILABLE PLOTS: Call this tool with no filename argument to list the filenames of all plots currently held in this session's registry. Useful when the user asks for save guidance but doesn't remember which plot they want.

FALLBACK Cypher executor. Use this ONLY when no specialist tool covers the question.

DO NOT call this tool when the question matches one of these patterns — call the named tool instead, EVEN IF you think Cypher would be more flexible:

• "up/down-regulated genes", "DEGs", "differential expression", "log2fc rankings", "top N up/downregulated genes for assay X" → find_differentially_expressed_genes(assay_id=...)

• "hyper/hypo-methylated regions", "DMRs", "methylation_diff", "hypermethylated promoter regions", "all DMRs passing q<0.05", pooling methylation across replicate assays → find_differentially_methylated_regions(assay_id=...)

• "differentially abundant organisms", DESeq2/ANCOM-BC abundance, "increased/decreased abundance for assay X" → find_differentially_abundant_organisms(assay_id=...)

• study metadata, what assays a study has, study factors/materials, project title, description, host organism/strain → get_study_info(study_id=...)

• factor-pair → assay-id resolution (e.g. "give me the assay for Space Flight,Carcass vs Ground Control,Carcass in OSD-48") → select_assays(study_id=..., selection=...)

• "what groups / conditions / control and experimental (treatment) groups are in study X", "what comparisons does OSD-48 have", "which factors were compared" — any question about the groups a study contains, even with no factor pair named → select_assays(study_id=...) (list mode; omit selection)

• common DEGs/DMRs/DA organisms across multiple assays, intersections → find_common_differentially_expressed_genes(assay_ids=[...]) → find_common_differentially_methylated_regions(assay_ids=[...]) → find_common_differentially_abundant_organisms(assay_ids=[...])

• DE genes overlapping DM regions, expression-methylation coupling, classical epigenetic silencing analysis → find_common_de_genes_overlapping_dm_regions(...)

• listing nodes / properties / relationships in the KG → get_neo4j_schema(), get_node_metadata(), get_relationship_metadata()

If you only have a study identifier and need assay IDs, call select_assays or get_study_info FIRST; do not write Cypher to discover assay IDs.

The specialist tools return formatted markdown tables AND an inline CSV side-channel that this query tool does not produce. Falling back to query for the categories above also loses the parallel multi-query execution, the method-aware significance filtering (DESeq2 adj_p_value vs. ANCOM-BC q_value), the region-vs-gene aggregation, and the MethylationRegion location filter plumbing the specialists already implement correctly.

Only call this tool for ad-hoc Cypher that the specialist tools cannot express: schema exploration, custom multi-hop traversals, exotic aggregations, or one-off counts the specialists don't expose.

OUTPUT FORMAT - CRITICAL: The response begins with a total_rows: N header followed by rows: and then the JSON array of records. When reporting counts to the user (e.g. "how many hypermethylated regions are there"), ALWAYS use total_rows, NEVER count rows visible in the JSON array. Large results may be truncated by the MCP transport and stored to a side-file, leaving only a partial preview of the array — but the total_rows count is computed server-side from the materialized result before any truncation and is always accurate. For aggregate queries (RETURN count(*)) total_rows will be 1 and the count itself lives in the row's count(*) field.

EDGE PROPERTIES - CRITICAL: Many relationships in this knowledge graph have properties stored as edge attributes (data ON the relationship itself).

MEASURED_DIFFERENTIAL_EXPRESSION_ASmMG: log2fc, adj_p_value, group_mean_1, group_stdev_1, group_mean_2, group_stdev_2 MEASURED_DIFFERENTIAL_METHYLATION_ASmMR: methylation_diff, q_value, group_mean_1, group_stdev_1, group_mean_2, group_stdev_2 MEASURED_DIFFERENTIAL_ABUNDANCE_ASmO: log2fc, lnfc, q_value, adj_p_value, group_mean_1, group_stdev_1, group_mean_2, group_stdev_2

ABUNDANCE EDGE - METHOD-AWARE FIELDS (CRITICAL for correct queries): The MEASURED_DIFFERENTIAL_ABUNDANCE_ASmO edge stores different fields depending on which differential analysis method produced the row. Use log2fc (not lnfc) for direction and ranking, since it is populated for BOTH methods:

• DESeq2 edges: log2fc populated, lnfc = null, adj_p_value populated, q_value = null

• ANCOM-BC edges: log2fc populated, lnfc populated, adj_p_value = null, q_value populated

To filter by significance in a method-agnostic way, OR both fields together: WHERE r.log2fc > 0 AND ( (r.adj_p_value IS NOT NULL AND r.adj_p_value <= 0.05) OR (r.q_value IS NOT NULL AND r.q_value <= 0.05) )

Filtering on r.lnfc > 0 will silently drop every DESeq2 row because Cypher's null > 0 evaluates to null and fails the WHERE clause. If you want to use lnfc as an ANCOM-BC-specific magnitude filter alongside log2fc-based direction, write the clause defensively: AND (r.lnfc IS NULL OR abs(r.lnfc) >= 0.5) This applies the lnfc threshold only to rows where lnfc is populated (ANCOM-BC) and leaves DESeq2 rows untouched.

RELATIONSHIP DIRECTIONS (always use directed arrows in queries): (Assay)-[:MEASURED_DIFFERENTIAL_EXPRESSION_ASmMG]->(MGene) (Assay)-[:MEASURED_DIFFERENTIAL_METHYLATION_ASmMR]->(MethylationRegion) (Assay)-[:MEASURED_DIFFERENTIAL_ABUNDANCE_ASmO]->(Organism) (MGene)-[:METHYLATED_IN_MGmMR]->(MethylationRegion) (Study)-[:PERFORMED_SpAS]->(Assay) (Mission)-[:CONDUCTED_MIcS]->(Study)

NODE PROPERTIES - CRITICAL (use EXACTLY these property names, no others exist): MGene: identifier, symbol, name, organism, taxonomy MethylationRegion: identifier, name, chromosome, start, end, in_promoter, in_exon, in_intron, dist_to_feature Assay: identifier, name, technology, measurement, differential_analysis_method, factors_1, factors_2, material_1, material_2, material_id_1, material_id_2, material_name_1, material_name_2, factor_space_1, factor_space_2 Study: identifier, name, project_title, project_type, description, organism, taxonomy, host_organism, host_strain Mission: identifier, name, flight_program, space_program, start_date, end_date Organism: identifier, name

COMMON PROPERTY NAME MISTAKES - NEVER USE THESE: WRONG: mg.gene_symbol RIGHT: mg.symbol WRONG: mg.gene_name RIGHT: mg.name WRONG: g.gene_symbol RIGHT: g.symbol WRONG: g.gene_name RIGHT: g.name

Get metadata for all nodes from MetaNode nodes in the knowledge graph.

Get descriptions of properties of all relationships in the knowledge graph.

USE THIS TOOL (not the query tool) for any study-metadata question: "what assays does study X have", "tell me about OSD-267", project title, description, host organism, missions, factor space, or any inventory of a study's assays. Falling back to query for these reproduces the work this tool already does and loses the formatted markdown + inline CSV side-channel.

Return detailed information about a study, including its assays with their technology and measurement types.

This tool queries the GeneLab KG for:

1. Study metadata (name, project title, description, organism, etc.)

2. All assays for the study with their technology, measurement type, differential analysis method, factors, and materials

3. Associated missions

For example, OSD-267 should return that it has both 16S and ITS amplicon sequencing data.

USE THIS TOOL (not the query tool) for ANY question about the groups a study contains, and to resolve a factor-pair condition into the matching assay identifier(s):

• "What groups / conditions / control and experimental (treatment) groups are in OSD-48?", "which comparisons or factors does this study have?", "what was compared against what?" — call with just study_id (list mode). The numbered factor menu it returns IS the list of groups: each entry is one experimental group (a set of factor values such as "Space Flight,Carcass"), and each assay is a comparison of two such groups (condition 1 vs condition 2, e.g. experimental vs control). Never use query for this.

• "Give me the assay for Space Flight,Carcass vs Ground Control,Carcass" — call with study_id and selection to resolve that factor pair (e.g. "2,1") into assay identifier(s).

Falling back to query for this category loses the numbered factor menu, the per-match technology/measurement/method columns, and the next-step suggestions this tool emits.

List and select assays for a study and render the response in markdown format.

First call (selection=None):

• If study_id missing, prompt for one (e.g., 'OSD-253').

• Build a list of unique factor arrays across all assays.

• Return a numbered menu as a markdown table.

Second call (selection='i,j,k,l,...,m,n'):

• Pairs consecutive indices: (i,j), (k,l), ..., (m,n)

• Must provide an even number of indices

• For each pair, returns the matching assay(s) with technology, measurement, differential analysis method, and material columns so the assistant can pick the right assay for a downstream question (e.g., RNA-Seq for DE genes, WGBS for DM regions, amplicon for organism abundance) WITHOUT issuing a follow-up Cypher query.

USE THIS TOOL (not the query tool) for any "up/down-regulated genes", "DEGs", or "differential expression" question for a single assay.

The query tool can express the same Cypher, but using it for this category loses the formatted markdown tables, the inline CSV side-channel, the proper adj_p_value handling, and the parallel execution of the count queries this tool already provides correctly.

Return the top-N up- and down-regulated genes for a given assay_id.

This tool runs two queries on the GeneLab KG:

1. Top-N upregulated genes (log2fc > 0, adj_p_value <= adj_p_threshold, highest log2fc first)

2. Top-N downregulated genes (log2fc < 0, adj_p_value <= adj_p_threshold, lowest log2fc first)

Returning all passing rows: Pass top_n=None to return ALL rows that pass the filters rather than a top-N ranking. Use this when the user asks for "all significantly up/downregulated genes" or wants the complete filtered set as CSV.

Results include gene symbol, gene name, log2 fold change, adjusted p-value, and group means and standard deviations for each condition.

USE THIS TOOL (not the query tool) for any "hyper/hypo-methylated regions", "DMRs", or "differential methylation" question — including all-rows requests, promoter/exon/intron-filtered methylation queries, and pooling methylation across replicate assays. Falling back to query for this category reproduces the work this tool already does (proper IS-NOT-NULL guards, gene-symbol join, parallel count queries, location filtering, deterministic CSV emission) and loses the formatted markdown

• inline CSV side-channel.

Return hyper- and hypo-methylated regions for one or more assays.

This tool runs two queries on the GeneLab KG:

1. Hypermethylated regions (methylation_diff > methylation_diff_threshold, q_value <= q_value_threshold, highest first)

2. Hypomethylated regions (methylation_diff < -methylation_diff_threshold, q_value <= q_value_threshold, lowest first)

Pooling across assays: Pass a list to assay_id to pool results across multiple methylation assays (the Cypher uses a.identifier IN $assay_ids). Common use case: a study has 2+ methylation assays representing replicate runs of the same comparison, and the user wants the combined evidence rather than per-assay tables. The output adds an assay_id column so each row's source is visible.

Returning all passing rows: Pass top_n=None to return ALL rows that pass the filters rather than a top-N ranking. Use this when the user asks for "all hypermethylated promoter regions" or wants the complete filtered set as CSV. To keep the response readable when the full set is large, the inline markdown table is capped at the first 100 rows and a note is shown; the CSV contains every row.

MethylationRegion location filters (in_promoter, in_exon, in_intron, dist_to_feature_max) are applied DURING the Cypher query. This means when a user asks for "top hypermethylated regions in the promoter", pass in_promoter=True and the tool will correctly rank within the promoter universe. Do NOT post-filter the unfiltered top-N — that produces wrong results because regions outside the filter (e.g. non-promoter regions) occupy slots in the unfiltered top-N and displace correctly-ranked filtered regions. Multiple filters combine with AND, so in_promoter=True with in_intron=False returns promoter regions that are not intronic.

WHEN TO USE THIS TOOL vs. direct Cypher via the query tool: Use THIS tool for any "hyper/hypo methylated regions" question, including pooled-across-assays, all-passing-rows, and filter-by-location variants. It produces formatted markdown tables AND an inline CSV that the user can save directly. Falling back to direct Cypher loses the formatted output and the CSV.

USE THIS TOOL (not the query tool) for any "differentially abundant organisms", DESeq2/ANCOM-BC abundance, or "increased/decreased abundance" question for a single assay.

The query tool can express the same Cypher, but using it for this category loses the formatted markdown tables, the inline CSV side-channel, the method-aware significance filtering (DESeq2 adj_p_value vs. ANCOM-BC q_value), and the safe lnfc handling that avoids silently dropping DESeq2 rows (where lnfc IS NULL would fail a naive lnfc > 0 filter).

Return the top-N organisms with increased and decreased differential abundance for a given assay_id.

Direction (increase vs. decrease) and ranking use log2fc, which is populated for BOTH DESeq2 and ANCOM-BC abundance edges in the GeneLab KG. log2fc is therefore used as the universal direction/ordering field and as the default magnitude filter.

The lnfc property is only populated for ANCOM-BC edges (DESeq2 leaves it null). It is returned in the result for reference and can be used as an additional magnitude filter via the lnfc_threshold parameter. log2fc is the direction filter because it is populated for both DESeq2 and ANCOM-BC rows; using lnfc for direction would null-filter every DESeq2 row out of the result.

Significance filtering is method-aware:

• DESeq2 edges populate adj_p_value (not q_value); the adj_p_threshold applies.

• ANCOM-BC edges populate q_value (not adj_p_value); the q_value_threshold applies. Each row is kept if its populated significance field meets the matching threshold.

Magnitude filtering:

• log2fc_threshold (default 0.0) applies to every row, since log2fc is populated for both methods.

• lnfc_threshold (default None = no filter) is method-aware: when set, it requires |lnfc| >= lnfc_threshold on rows where lnfc is populated. Rows where lnfc is null (i.e., DESeq2 rows) are not affected by this filter. Set lnfc_threshold to a positive number to add an ANCOM-BC-specific magnitude filter on top of log2fc.

This tool runs two queries on the GeneLab KG:

1. Top-N organisms with increased abundance (log2fc > log2fc_threshold, significance and optional lnfc filters met, highest log2fc first)

2. Top-N organisms with decreased abundance (log2fc < -log2fc_threshold, significance and optional lnfc filters met, lowest log2fc first)

Results include organism name, log2fc, lnfc, q-value, adj-p-value, and group means and standard deviations.

USE THIS TOOL (not the query tool) for any "common DEGs across assays", "genes upregulated in BOTH assays", "shared up/downregulated genes", or any cross-assay DE intersection question. Falling back to query for this category reproduces the per-assay fetch + inner-join logic this tool already does correctly (parallel fetches via the driver's connection pool, |log2fc| > threshold filtering, separate up vs. down intersections) and loses the formatted markdown tables, the inline CSV side-channel, and the assay-reference legend.

Find common differentially expressed genes across multiple assays.

This function:

1. Takes a list of assay IDs as input (2 or more)

2. Gets ALL genes with |log2fc| > threshold for each assay

3. Inner joins among the upregulated genes and among the downregulated genes

4. Returns a markdown table with columns: gene, assay_1, assay_2, ..., assay_n showing log2fc values

USE THIS TOOL (not the query tool) for any "common DMRs across assays", "genes hypermethylated in BOTH assays", "shared hyper/hypomethylated regions", or any cross-assay methylation intersection question — including promoter/exon/intron-filtered and distance-bounded variants. Falling back to query for this category reproduces the per-assay fetch + inner-join logic this tool already does correctly (parallel fetches, MethylationRegion location filtering applied during the Cypher so the common set reflects the filtered universe, methylation_diff/q_value thresholds, separate hyper vs. hypo intersections) and loses the formatted markdown + inline CSV side-channel and the assay-reference legend.

Find common differentially methylated genes across multiple assays.

This function:

1. Takes a list of assay IDs as input (2 or more)

2. Gets ALL genes associated with differentially methylated regions for each assay, applying the methylation_diff threshold, q_value threshold, and any MethylationRegion location filters (in_promoter, in_exon, in_intron, dist_to_feature_max)

3. Inner joins among hypermethylated genes and among hypomethylated genes

4. Returns markdown tables showing common genes and their methylation_diff values

Use the location filter parameters rather than post-filtering — they are applied during the Cypher query so the common gene set reflects the filtered universe correctly.

USE THIS TOOL (not the query tool) for any "common differentially abundant organisms across assays", "organisms increased in BOTH assays", "shared abundance signals across methods" (e.g. DESeq2 vs ANCOM-BC concordance), or any cross-assay abundance intersection question. Falling back to query for this category reproduces the per-assay fetch + inner-join logic this tool already does correctly (parallel fetches, method-aware significance filtering, lnfc handling that doesn't drop DESeq2 rows, separate increased vs. decreased intersections) and loses the formatted markdown + inline CSV side-channel and the assay-reference legend.

Find common differentially abundant organisms across multiple assays.

Useful for comparing results from different analysis methods (e.g., DESeq2 vs ANCOM-BC 1 vs ANCOM-BC 2) to identify organisms consistently detected as differentially abundant.

Direction (increase vs. decrease) and ranking use log2fc, which is populated for BOTH DESeq2 and ANCOM-BC edges in the GeneLab KG. log2fc is therefore the universal magnitude filter (log2fc_threshold); lnfc is ANCOM-BC-only and would null-filter every DESeq2 row if used for direction.

Significance filtering is method-aware:

• DESeq2 edges populate adj_p_value (not q_value); the adj_p_threshold applies.

• ANCOM-BC edges populate q_value (not adj_p_value); the q_value_threshold applies. Each row is kept if its populated significance field meets the matching threshold.

Magnitude filtering:

• log2fc_threshold (default 0.0) applies to every row, since log2fc is populated for both methods.

• lnfc_threshold (default None = no filter) is method-aware: when set, it requires |lnfc| >= lnfc_threshold on rows where lnfc is populated. Rows where lnfc is null (i.e., DESeq2 rows) are not affected by this filter.

This function:

1. Takes a list of assay IDs as input (2 or more)

2. Gets ALL organisms passing the magnitude and method-aware significance filters for each assay

3. Inner joins among increased and among decreased abundance organisms

4. Returns markdown tables showing common organisms and their log2fc values

USE THIS TOOL (not the query tool) for any "expression-methylation coupling", "classical epigenetic silencing", "DE genes that are also DM", "downregulated genes with promoter hypermethylation", or any cross-type intersection between differential expression and differential methylation. Falling back to query for this category reproduces the four-quadrant intersection logic this tool already does correctly (parallel DE+DM fetches across DIFFERENT assays, pooled-methylation aggregation when multiple methylation assays are passed as a list, MethylationRegion location filtering on the DM side, up_hyper/up_hypo/down_hyper/down_hypo direction categorization) and loses the four-quadrant markdown summary and the inline combined CSV.

Find differentially expressed genes that overlap with differentially methylated regions.

This cross-analysis tool:

1. Gets DE genes from the expression assay (filtered by log2fc and adj_p thresholds)

2. Gets genes associated with DM regions from the methylation assay(s) (filtered by methylation_diff, q_value, and any MethylationRegion location filters: in_promoter, in_exon, in_intron, dist_to_feature_max). If methylation_assay_id is a list, the methylation evidence is POOLED across the listed assays before the intersection — a gene is treated as hypermethylated if it passes the threshold in ANY of the pooled assays.

3. Finds the intersection (genes that are BOTH differentially expressed AND differentially methylated)

4. Reports the overlap categorized by direction (up+hyper, up+hypo, down+hyper, down+hypo)

For the classical epigenetic-silencing question — promoter hypermethylation reducing expression — pass in_promoter=True. When a study has replicate methylation assays (e.g. OSD-48 has two methylKit assays for the same Space Flight vs. Ground Control comparison), pass them as a list to capture the combined methylation evidence on the methylation side of the intersection.

Create a volcano plot for differential data from the given assay.

Works for three differential measurement types:

• 'expression': -[MEASURED_DIFFERENTIAL_EXPRESSION_ASmMG]-> MGene x = log2fc, y = -log10(adj_p_value), labels = gene symbol Magnitude filter: log2fc_threshold (default 1.0 = 2-fold)

• 'methylation': -[MEASURED_DIFFERENTIAL_METHYLATION_ASmMR]-> MethylationRegion x = methylation_diff, y = -log10(q_value), labels = gene symbol (joined via METHYLATED_IN_MGmMR back to MGene for labeling) Magnitude filter: methylation_diff_threshold (default 10.0 = 10%)

• 'abundance': -[MEASURED_DIFFERENTIAL_ABUNDANCE_ASmO]-> Organism x = log2fc, y = -log10(significance), labels = organism name Magnitude filter: log2fc_threshold (default 1.0 = 2-fold) Significance is method-aware: DESeq2 rows use adj_p_value, ANCOM-BC rows use q_value.

Points are colored by significance:

• Red: positive direction (upregulated / hypermethylated / increased)

• Blue: negative direction (downregulated / hypomethylated / decreased)

• Gray: not significant

Returns a markdown summary, an inline PNG image (if small enough), and the saved file path. Designed to handle assays with thousands of features without timing out.

Create Venn diagrams comparing differential data between 2 or 3 assays.

Supports multiple data types:

• 'expression': Compares differentially expressed genes (upregulated/downregulated by log2fc)

• 'methylation': Compares differentially methylated genes (hypermethylated/hypomethylated by methylation_diff)

• 'abundance': Compares differentially abundant organisms (increased/decreased by log2fc; works for both DESeq2 and ANCOM-BC)

• 'expression_methylation': Cross-comparison showing directional overlaps between differentially expressed genes from one assay and differentially methylated genes from another assay (2-way only)

Creates side-by-side Venn diagrams showing:

• Left: Positive direction (upregulated / hypermethylated / increased abundance)

• Right: Negative direction (downregulated / hypomethylated / decreased abundance)

For 'expression_methylation' mode, this tool computes FOUR directional overlaps so the user can see which kind of expression–methylation coupling is happening. By default (direction_pair='all') it renders all four as a 2x2 grid:

• Hypermethylated + Downregulated (classical epigenetic silencing — promoter methylation reducing expression)

• Hypomethylated + Upregulated (loss of methylation enabling expression)

• Hypermethylated + Upregulated (less canonical; e.g. gene-body methylation activating expression)

• Hypomethylated + Downregulated (less canonical; non-classical) If the user names a specific pairing (e.g. "create a Venn of hypermethylated and downregulated genes"), pass direction_pair='hyper_down' to render just that one. The summary always reports the size of all four overlaps, regardless of which subset is rendered.

Methylation region location filters (for data_type='methylation' and the methylation side of 'expression_methylation'):

• in_promoter, in_exon, in_intron: each accepts True (include only regions where this flag is true), False (exclude regions where this flag is true), or None (no filter). Multiple filters combine with AND. For example, in_promoter=True alone restricts to promoter-overlapping regions; in_promoter=True with in_intron=False restricts to promoter regions that are NOT intronic.

• dist_to_feature_max: when set, include only regions whose distance to the nearest gene feature is <= this value (in bp). Useful for narrowing to regions tightly associated with gene bodies. dist_to_feature on the MethylationRegion node is the bp distance from the region to the nearest annotated feature. These filters apply during the Cypher query — they reduce the set of methylation regions BEFORE the overlap computation, so each gene set is the genes that have at least one methylation region passing all the filters and the magnitude/significance criteria.

Significance filtering:

• 'expression' and 'expression_methylation' (expression side): adj_p_value <= adj_p_threshold (default 0.05).

• 'methylation' and 'expression_methylation' (methylation side): q_value <= q_value_threshold (default 0.05).

• 'abundance' is method-aware: DESeq2 rows are filtered by adj_p_threshold, ANCOM-BC rows by q_value_threshold.

Magnitude filtering for 'abundance':

• log2fc_threshold applies to every row (log2fc is populated for both methods).

• lnfc_threshold (optional) adds an ANCOM-BC-specific |lnfc| filter; DESeq2 rows (lnfc IS NULL) pass through.

Returns a link to the plot and summary statistics.

Clean a Mermaid class diagram by removing unwanted elements.

    This tool removes:
    - All note statements that would render as unreadable yellow boxes
    - Empty curly braces from class definitions (handles both single-line and multi-line)
    - Strings after newline characters (e.g., truncates "ClassName

extra" to "ClassName")

    Args:
        mermaid_content: The raw Mermaid class diagram content
        
    Returns:
        Cleaned Mermaid content with note statements, empty braces, and post-newline strings removed
    

Prompt for creating a chat transcript in markdown format with user prompts and Claude responses.

Prompt for visualizing the knowledge graph schema using a Mermaid class diagram.