mirdip-client

Typed Python client and CLI for the mirDIP HTTP API.

• Project: Python client and CLI for mirDIP at http://ophid.utoronto.ca/mirDIP
• Use cases: Query microRNA–gene target predictions programmatically
• Interfaces: Python API (MirDIPClient) and CLI (mirdip)

Installation

pip install mirdip-client

To develop/test locally:

pip install -e .[dev,test]

Quickstart (Python)

from mirdip_client import MirDIPClient

client = MirDIPClient()  # defaults to http://ophid.utoronto.ca/mirDIP

# Unidirectional: search by gene symbols
resp = client.search_genes("AKAP17A,AKR1C2,APP", "Very High")
print(resp.results_size)
print(resp.results)  # Tab-delimited table

How mirDIP responses are structured

• The server returns a custom text payload, parsed into a MirDIPResponse object with:
  • raw_text: original server payload (string)
  • fields: parsed key/value pairs (dict)
  • Convenience properties:
    • generated_at, gene_symbols, micro_rnas, minimum_score, db_occurrences, sources, results_size, results
  • to_dataframe(): convenience helper to parse results into a pandas DataFrame.
• results is a single string containing a tab-delimited table (header + rows). Convert to pandas easily:

import pandas as pd
from io import StringIO

df = pd.read_csv(StringIO(resp.results), sep="\t")
# or simply
df = resp.to_dataframe()

Score classes

mirDIP uses 4 score classes, mapped internally to API values:

• "Very High" → 0
• "High" → 1
• "Medium" → 2
• "Low" → 3

Always pass one of the four strings exactly as shown.

---

Python API Reference

MirDIPClient

from mirdip_client import MirDIPClient
client = MirDIPClient(base_url="http://ophid.utoronto.ca/mirDIP", timeout=60.0)

• base_url: change only if targeting a different mirDIP server.
• timeout: request timeout in seconds.

Unidirectional search on genes: search_genes

resp = client.search_genes(gene_symbols: str, minimum_score: str)

• gene_symbols: comma-separated HUGO gene symbols (e.g., "AKAP17A,AKR1C2,APP").
• minimum_score: one of "Very High" | "High" | "Medium" | "Low".

What it does

• Queries mirDIP for predicted microRNA targets associated with the provided genes.
• Internally calls the mirDIP Http_U endpoint with genesymbol set and microrna left empty.

Example

resp = client.search_genes("AKAP17A,AKR1C2,APP,ZZZ3,MARK4,C17orf51", "Very High")
print(resp.generated_at)
print(resp.results_size)
print(resp.results)

Unidirectional search on microRNAs: search_micro_rnas

resp = client.search_micro_rnas(micro_rnas: str, minimum_score: str)

• micro_rnas: comma-separated microRNA identifiers (e.g., "hsa-miR-603,hsa-let-7a-3p").
• minimum_score: one of "Very High" | "High" | "Medium" | "Low".

What it does

• Queries mirDIP for predicted gene targets associated with the provided microRNAs.
• Internally calls the mirDIP Http_U endpoint with microrna set and genesymbol left empty.

Example

resp = client.search_micro_rnas(
    "hsa-miR-603, hsa-let-7a-3p, hsa-miR-625-5p, hsa-miR-7852-3p, hsa-miR-17-5p",
    "Very High",
)
print(resp.micro_rnas)
print(resp.results_size)
print(resp.results)

Bidirectional search: search_bidirectional

resp = client.search_bidirectional(
    gene_symbols: str,
    micro_rnas: str,
    minimum_score: str,
    sources: str,
    occurrences: str = "1",
)

• gene_symbols: comma-separated HUGO gene symbols.
• micro_rnas: comma-separated microRNA identifiers.
• minimum_score: one of "Very High" | "High" | "Medium" | "Low".
• sources: comma-separated list of source datasets to filter by. Examples include:
  • bitargeting_May_2021, BCmicrO, CoMeTa, Cupid, DIANA, miranda_May_2021, mirbase, mirCoX, mirmap_May_2021, mirzag, miRcode, miRDB_v6, miRTar2GO, MBStar, MirAncesTar, MirSNPInTarget, MirTar2, MiRNATIP, MultiMiTar, PACCMIT, PITA_May_2021, rnahybrid_May_2021, RNA22, TargetScan_v7_2
  • Use exact spelling.
• occurrences: minimum number of sources that must report a prediction (string number, allowed range typically "1" to "24").

What it does

• Queries mirDIP for predictions present in at least occurrences of the specified sources, intersecting both provided genes and microRNAs.
• Internally calls the mirDIP Http_B endpoint.

Example

resp = client.search_bidirectional(
    "AKAP17A,AKR1C2,APP,ZZZ3,MARK4,C17orf51",
    "hsa-miR-603,hsa-let-7a-3p,hsa-miR-625-5p,hsa-miR-7852-3p,hsa-miR-17-5p,hsa-miR-4321,hsa-miR-758-3p",
    "Very High",
    "bitargeting_May_2021, BCmicrO, CoMeTa, Cupid, DIANA, miranda_May_2021, mirbase, mirCoX, mirmap_May_2021, mirzag, miRcode, miRDB_v6, miRTar2GO, MBStar, MirAncesTar, MirSNPInTarget, MirTar2, MiRNATIP, MultiMiTar, PACCMIT, PITA_May_2021, rnahybrid_May_2021, RNA22, TargetScan_v7_2",
    "2",
)
print(resp.db_occurrences)
print(resp.sources)
print(resp.results_size)
print(resp.results)

Interpreting the MirDIPResponse

Available convenience properties:

• generated_at: timestamp of response creation
• gene_symbols: echo of input gene list (if provided)
• micro_rnas: echo of input microRNA list (if provided)
• minimum_score: echo of selected score class
• db_occurrences: echo of selected occurrences (bidirectional)
• sources: echo of selected sources (bidirectional)
• results_size: number of rows returned
• results: tab-delimited content (header + rows)
• to_dataframe(): returns a pandas DataFrame from the tab-delimited results string (requires pandas).

---

CLI usage

The CLI mirrors the Python methods.

Unidirectional search on genes

mirdip genes "AKAP17A,AKR1C2,APP" "Very High"

• Prints a tab-delimited table to stdout.
• Options: --base-url to override server, --timeout for request timeout.

Unidirectional search on microRNAs

mirdip micrornas "hsa-miR-603,hsa-let-7a-3p" "High"

Bidirectional search

mirdip bidirectional \
  "AKAP17A,AKR1C2" \
  "hsa-miR-603,hsa-let-7a-3p" \
  "Medium" \
  "TargetScan_v7_2, miRDB_v6" \
  2

Global options usable on any subcommand:

• --base-url URL (default http://ophid.utoronto.ca/mirDIP)
• --timeout SECONDS (default 60.0)

---

Examples

A full example script is provided at examples/example.py demonstrating all three queries and printing selected fields and the tab-delimited results.

---

Troubleshooting

• Ensure score strings are exact: "Very High" | "High" | "Medium" | "Low".
• occurrences must be a stringified integer within the valid range for the data snapshot (commonly "1"–"24").
• Network errors/timeouts: set a higher timeout or retry.
• The server response is not JSON; use resp.results or parse it into a DataFrame as shown above.

Contributing

See CONTRIBUTING.md for development, testing, and release instructions.

---

Citation

If you use this package or the mirDIP service in your work, please cite:

• Tokar T, Pastrello C, Rossos AEM, Abovsky M, Hauschild AC, Tsay M, Lu R, Jurisica I. mirDIP 4.1-integrative database of human microRNA target predictions. Nucleic Acids Res. 2018 Jan 4;46(D1):D360-D370. doi: 10.1093/nar/gkx1144. PubMed PMID: 29194489; PubMed Central PMCID: PMC5753284
• Shirdel EA, Xie W, Mak TW, Jurisica I, 2011 NAViGaTing the Micronome. Using Multiple MicroRNA Prediction Databases to Identify Signalling Pathway-Associated MicroRNAs. PLoS ONE 6(2): e17429. doi:10.1371/journal.pone.0017429