uprobe 0.1.0__tar.gz

uprobe-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 U-FISH Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

uprobe-0.1.0/MANIFEST.in

@@ -0,0 +1,3 @@
+include requirements.txt
+include requirements-dev.txt
+recursive-include uprobe *.ini *.yaml *.json *.html *.css *.js

uprobe-0.1.0/PKG-INFO

@@ -0,0 +1,73 @@
+Metadata-Version: 2.4
+Name: uprobe
+Version: 0.1.0
+Summary: Web server for U-Probe
+Home-page: https://github.com/UFISH-Team/U-Probe
+Author: Qian Zhang, Weize Xu
+Author-email: jshn2022@163.com, 
+License: MIT
+Keywords: FISH,Probe design
+Classifier: Development Status :: 3 - Alpha
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Intended Audience :: Science/Research
+Requires-Python: >=3.8, <4
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: pandas
+Requires-Dist: viennarna
+Requires-Dist: primer3-py
+Requires-Dist: pathos
+Requires-Dist: pyfaidx==0.5.9.5
+Requires-Dist: fire
+Requires-Dist: seqwalk
+Requires-Dist: pyyaml
+Requires-Dist: click
+Requires-Dist: intervaltree
+Requires-Dist: matplotlib
+Requires-Dist: plotly
+Requires-Dist: granian
+Requires-Dist: uvloop
+Requires-Dist: fire
+Requires-Dist: pyyaml
+Requires-Dist: python-jose
+Requires-Dist: passlib==1.7.4
+Requires-Dist: python-multipart
+Requires-Dist: bcrypt==3.2.2
+Requires-Dist: fastapi>=0.135.0
+Requires-Dist: uvicorn
+Requires-Dist: python-dotenv
+Provides-Extra: dev
+Requires-Dist: pip; extra == "dev"
+Requires-Dist: setuptools; extra == "dev"
+Requires-Dist: wheel; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Requires-Dist: ipdb; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
+Requires-Dist: flake8; extra == "dev"
+Requires-Dist: pyqt5<5.13; extra == "dev"
+Requires-Dist: pyqtwebengine<5.13; extra == "dev"
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license
+Dynamic: license-file
+Dynamic: provides-extra
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+See https://github.com/UFISH-Team/U-Probe

uprobe-0.1.0/README.md

@@ -0,0 +1,298 @@
+<h1 align="center">
+  <img src="./assets/uprobe.svg" alt="uprobe logo" height="80" align="absmiddle"> Universal Agentic Probe Design Platform
+</h1>
+<br>
+
+[![License](https://img.shields.io/github/license/UFISH-Team/U-Probe)](https://github.com/UFISH-Team/U-Probe/blob/main/LICENSE)
+[![Python Version](https://img.shields.io/badge/python-3.7+-blue)](https://www.python.org/downloads/)
+[![Documentation](https://img.shields.io/badge/docs-latest-blue.svg)](https://ufish-team.github.io/uprobe-official/)
+[![Website](https://img.shields.io/badge/Website-Official-green.svg)](https://ufish-team.github.io/uprobe-official/)
+
+**U-Probe** is a universal and agentic probe design platform tailored for imaging-based spatial-omics. It overcomes the architectural limitations of existing tools and lowers the expertise barrier by combining an innovative declarative configuration system with LLM-based AI agents.
+
+Whether you are designing standard probes for established protocols or developing entirely novel architectures, U-Probe provides a comprehensive, automated workflow from target sequence extraction to rigorous thermodynamic filtering.
+
+## Features
+
+- **Universal Probe Architecture**: Features a declarative configuration system and a directed acyclic graph (DAG)-based assembly engine. Easily design arbitrary and complex multi-part probe structures (e.g., DNA-FISH, smFISH, MERFISH, seqFISH, $\pi$-FISH, MiP-seq, RCA) without modifying any source code.
+- **Agentic AI Workflow**: Integrates hierarchical LLM-based AI agents (via PantheonOS) for conversational design. Users can describe experimental goals in plain language or provide scRNA-seq data, and the agents will autonomously construct configurations, select parameters, and execute the design pipeline.
+- **Comprehensive Quality Filtering**: Automatically computes and filters candidates based on GC content, melting temperature, secondary structure stability (via ViennaRNA), off-target mapping (via Bowtie2), and k-mer frequency (via Jellyfish).
+- **End-to-End Automation**: Streamlines the entire process from target sequence extraction to advanced post-processing, including overlap removal and equal spacing for tiling designs.
+- **Extensible API & Web UI**: Offers a clean Python API for programmatic integration, a command-line interface, and an interactive web server for visual workflow management and result analysis.
+
+## Installation
+
+U-Probe can be easily installed via pip. We recommend using a virtual environment (like conda or venv).
+
+### Install via pip (Recommended)
+
+```bash
+pip install uprobe
+```
+
+### Install from source (For development)
+
+```bash
+git clone https://github.com/UFISH-Team/U-Probe.git
+cd U-Probe
+pip install -e .
+```
+
+### Using conda environment
+
+```bash
+git clone https://github.com/UFISH-Team/U-Probe.git
+cd U-Probe
+conda env create -f environments.yaml
+conda activate uprobe
+pip install .
+```
+
+## Usage Guide
+
+U-Probe provides flexible ways to use the tool: **Command Line Interface (CLI)**, **Python API**, and an **Interactive Web UI**. 
+
+Before starting, ensure you have prepared two YAML configuration files:
+1. **`genomes.yaml`**: Defines genome paths (FASTA, GTF, etc.).
+2. **`protocol.yaml`**: Defines probe design parameters.
+
+### 1. Command Line Interface (CLI)
+
+The CLI is perfect for running tasks quickly in the terminal or shell scripts.
+
+#### 🤖 AI Smart Assistant 
+U-Probe includes an interactive AI Agent powered by Pantheon. You can design probes through natural language conversation without writing YAML files manually.
+
+```bash
+uprobe agent
+```
+
+#### 🌐 Start Web Server 
+U-Probe now comes with a built-in web server and UI for an intuitive visual experience.
+
+```bash
+# Start in development mode (default)
+uprobe server --host 127.0.0.1 --port 8000
+
+# Start in production mode with multiple workers
+uprobe server --env production --host 0.0.0.0 --port 8000 --workers 4
+```
+
+#### 🌟 Complete Workflow (Recommended)
+To run the entire pipeline from genome index construction to final probe generation in one go:
+
+```bash
+uprobe run -p protocol.yaml -g genomes.yaml -o ./results --threads 10
+```
+
+#### 🔧 Step-by-Step Execution
+For advanced users who need intermediate results or custom workflows, you can execute each step individually:
+
+```bash
+# 1. Build genome index
+uprobe build-index -p protocol.yaml -g genomes.yaml -t 10
+
+# 2. Validate target genes against the GTF file
+uprobe validate-targets -p protocol.yaml -g genomes.yaml
+
+# 3. Extract target region sequences
+uprobe generate-targets -p protocol.yaml -g genomes.yaml -o ./results
+
+# 4. Construct initial probes from target sequences
+uprobe construct-probes -p protocol.yaml -g genomes.yaml --targets ./results/target_sequences.csv -o ./results
+
+# 5. Post-process probes (add attributes, filter, sort)
+uprobe post-process -p protocol.yaml -g genomes.yaml --probes ./results/constructed_probes.csv -o ./results
+
+# 6. Generate visual analysis report
+uprobe generate-report -p protocol.yaml -g genomes.yaml --probes ./results/probes_*.csv -o ./results
+```
+
+### 2. Python API (Ideal for Backend Integration)
+
+If you are developing a web backend or data analysis pipeline, we recommend directly using `UProbeAPI`. It returns Pandas DataFrames, making it easy to process further.
+
+```python
+import uprobe
+from pathlib import Path
+
+# Initialize API
+api = uprobe.UProbeAPI(
+    protocol_config=Path("protocol.yaml"),
+    genomes_config=Path("genomes.yaml"),
+    output_dir=Path("./results")
+)
+
+# --- Method 1: Complete Workflow ---
+df_final = api.run_workflow(threads=10)
+
+# --- Method 2: Step-by-Step Execution ---
+api.build_genome_index(threads=10)
+api.validate_targets()
+df_targets = api.generate_target_seqs()
+df_probes = api.construct_probes(df_targets)
+
+import pandas as pd
+df_combined = pd.concat([df_targets, df_probes], axis=1)
+df_final = api.post_process_probes(df_combined)
+
+# Generate HTML/PDF report
+api.generate_report(df_final)
+```
+
+## Configuration Details
+
+U-Probe relies on two main configuration files to run. Here is a breakdown of how to structure them.
+
+### 1. `genomes.yaml`
+This file maps a genome name to its corresponding file paths. It tells U-Probe where to find the reference genome and annotation files, and which aligner indices to build.
+
+```yaml
+# Example genomes.yaml
+GRCh38:
+  fasta: "/path/to/GRCh38.fasta"
+  gtf: "/path/to/GRCh38.gtf"
+  align_index:
+    - bowtie2
+    - blast
+  jellyfish: false  
+```
+
+### 2. `protocol.yaml`
+This is the core configuration file that defines all parameters for a specific probe design run. It is highly customizable.
+
+```yaml
+# Example protocol.yaml snippet
+name: my_rna_probe_design
+genome: GRCh38
+targets:
+  - CD4
+
+extracts:
+  target_region:
+    source: exon  # genome / exon / CDS / UTR
+    length: 30
+    overlap: 15
+
+# Define how genes map to specific barcodes
+encoding:
+  CD4:
+    BC1: ACGAGCCTTCCA
+    BC2: CGGTAATGGACT
+
+# Define the structure of your probes
+probes:
+  probe_1:
+    template: "{part1}{part2}"
+    parts:
+      part1:
+        expr: "rc(target_region[0:20])"
+      part2:
+        template: "CC{barcode1}TGCGTCTATTT{barcode2}TAGTGGAGCCT"
+        parts:
+          barcode1:
+            expr: "encoding[target]['BC1']"
+          barcode2:
+            expr: "encoding[target]['BC2']"
+  probe_2:
+    template: "{part1}AGGCTCCACTA"
+    parts:
+      part1:
+        expr: "rc(target_region[-10:])"
+
+attributes:
+  # target region attributes
+  target_gcContent:
+    target: target_region
+    type: gc_content
+  target_tm:
+    target: target_region
+    type: annealing_temperature
+
+# Define filtering and sorting criteria
+post_process:
+  filters:
+    target_tm:
+      condition: target_tm >= 37 & target_tm <= 47
+  sorts:
+    is_ascending: 
+     - target_gc
+    is_descending: 
+     - target_foldScore
+
+remove_overlap:
+  location_interval: 0
+
+# Define what attributes to include in the final report
+summary:
+  report_name: rna_report   # rna_report / dna_report
+  attributes:
+    - target_foldScore
+    - target_gc
+```
+
+#### Key Sections in `protocol.yaml`:
+- **`name` & `genome`**: Basic metadata. The `genome` must match a key in your `genomes.yaml`.
+- **`targets`**: A list of target gene names or IDs you want to design probes for.
+- **`extracts`**: Parameters for extracting target sequences. The `source` can be `genome`, `exon`, `CDS`, or `UTR`. You can also define the sliding window `length` and `overlap`.
+- **`encoding`**: Mapping of specific genes to custom barcodes or identifiers (e.g., assigning `BC1` and `BC2` to `CD4`).
+- **`probes`**: The core of the design, powered by a **Directed Acyclic Graph (DAG)** architecture. This allows for complex, modular probe construction where parts and probes can reference each other.
+  - **`template`**: Construct sequences using placeholders (e.g., `{part1}{part2}`).
+  - **`expr`**: Apply Python-like expressions. You can use built-in functions like `rc()` (reverse complement), slice sequences (`[0:20]`), or fetch from the `encoding` map (`encoding[target]['BC1']`).
+  - **DAG References**: Because of the DAG structure, subsequent probes or parts can dynamically reference the sequences of previously defined probes/parts in their expressions.
+- **`attributes`**: Define the biochemical or physical properties you want to calculate for specific targets or probe parts. Available attribute types include:
+  - `gc_content`: Calculates the GC ratio of the sequence.
+  - `annealing_temperature`: Calculates the melting temperature (Tm) using Primer3.
+  - `fold_score`: Calculates the RNA folding minimum free energy (MFE) using ViennaRNA (lower is more stable).
+  - `self_match`: Calculates the potential for self-dimerization.
+  - `mapped_sites`: Aligns the sequence to the genome (via Bowtie2) and counts off-target mapped sites.
+  - `mapped_genes`: Counts the number of unique genes the sequence aligns to (via Bowtie2).
+  - `kmer_count`: Counts k-mer occurrences in the genome (via Jellyfish) to evaluate specificity.
+- **`post_process`**: Define strict `filters` (e.g., Tm ranges) based on the calculated attributes, and `sorts` to rank the best probes (ascending or descending).
+- **`remove_overlap`**: Control the spacing between probes on the target sequence. `location_interval: 0` ensures probes do not overlap.
+- **`summary`**: Define the `report_name` (e.g., `rna_report` or `dna_report`) and the specific `attributes` you want to visualize and output in the final report.
+
+For more detailed examples and advanced configurations, please refer to the [`tests/data/*.yaml`](https://github.com/UFISH-Team/U-Probe/tree/main/tests/data "Click to visit here") directory.
+
+## Community & Support
+
+- 📖 **Documentation**: [uprobe.readthedocs.io](https://uprobe.readthedocs.io/)
+- 💬 **GitHub Discussions**: [Ask questions and share ideas](https://github.com/UFISH-Team/U-Probe/discussions)
+- 🐛 **Bug Reports**: [GitHub Issues](https://github.com/UFISH-Team/U-Probe/issues)
+- 🚀 **Contributing**: See our [contributing guide](https://uprobe.readthedocs.io/en/latest/contributing.html)
+
+## Citation
+
+If you use U-Probe in your research, please cite our paper (or software):
+
+```bibtex
+@software{uprobe2026,
+  title={U-Probe: Universal Probe Design Tool},
+  author={Zhang, Qian and Xu, Weize and Cai, Huaiyuan},
+  year={2025},
+  url={https://github.com/UFISH-Team/U-Probe},
+  version={1.0.0}
+}
+```
+*(Note: Update the citation format with actual journal details once published.)*
+
+## License
+
+U-Probe is released under the [MIT License](LICENSE). See the `LICENSE` file for details.
+
+## Acknowledgments
+
+We thank the bioinformatics community for valuable feedback during development, and the authors of the following tools that U-Probe integrates:
+
+- [PantheonOS](https://github.com/aristoteleo/PantheonOS) - The multi-agent framework powering our AI agent design
+- [Bowtie2](http://bowtie-bio.sourceforge.net/bowtie2/) - Fast and memory-efficient sequence alignment
+- [BLAST+](https://blast.ncbi.nlm.nih.gov/) - Sequence similarity search  
+- [MMseqs2](https://github.com/soedinglab/MMseqs2) - Ultra-fast and sensitive sequence search and clustering
+- [Jellyfish](https://github.com/gmarcais/Jellyfish) - Fast k-mer counting
+- [ViennaRNA](https://www.tbi.univie.ac.at/RNA/) - RNA secondary structure prediction
+- [Primer3](https://primer3.org/) - Primer and probe design algorithms
+- [FastAPI](https://fastapi.tiangolo.com/) & [Vue.js](https://vuejs.org/) - Powering our interactive Web UI
+
+
+
+

uprobe-0.1.0/requirements-dev.txt

@@ -0,0 +1,11 @@
+pip
+setuptools
+wheel
+twine
+ipdb
+pytest
+pytest-cov
+pytest-asyncio
+flake8
+pyqt5 < 5.13
+pyqtwebengine < 5.13

uprobe-0.1.0/requirements.txt

@@ -0,0 +1,25 @@
+numpy
+pandas
+viennarna
+primer3-py
+pathos
+pyfaidx==0.5.9.5
+fire
+seqwalk
+pyyaml
+click
+intervaltree
+matplotlib
+plotly
+granian
+uvloop
+
+fire
+pyyaml
+python-jose
+passlib==1.7.4
+python-multipart
+bcrypt==3.2.2
+fastapi>=0.135.0
+uvicorn
+python-dotenv

uprobe-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

uprobe-0.1.0/setup.py

@@ -0,0 +1,88 @@
+from setuptools import setup, find_packages
+import re
+
+
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.7",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "License :: OSI Approved :: MIT License",
+    "Intended Audience :: Science/Research",
+]
+
+
+keywords = [
+    'FISH', 'Probe design',
+]
+
+
+URL = "https://github.com/UFISH-Team/U-Probe"
+
+
+def get_version():
+    with open("uprobe/__init__.py") as f:
+        for line in f.readlines():
+            m = re.match(r"__version__\s*=\s*['\"]([^'\"]+)['\"]", line)
+            if m:
+                return m.group(1)
+        raise IOError("Version information can not found.")
+
+
+def get_long_description():
+    return f"See {URL}"
+
+
+def get_requirements_from_file(filename):
+    requirements = []
+    with open(filename) as f:
+        for line in f.readlines():
+            line = line.strip()
+            if len(line) == 0:
+                continue
+            if line and not line.startswith('#'):
+                requirements.append(line)
+    return requirements
+
+
+def get_install_requires():
+    reqs = get_requirements_from_file('requirements.txt')
+    return reqs
+
+
+packages_for_dev = get_requirements_from_file("requirements-dev.txt")
+requires_dev = packages_for_dev
+
+
+setup(
+    name='uprobe',
+    author='Qian Zhang, Weize Xu',
+    author_email='jshn2022@163.com, ',
+    version=get_version(),
+    license='MIT',
+    description='Web server for U-Probe',
+    long_description=get_long_description(),
+    keywords=keywords,
+    url=URL,
+    packages=find_packages(),
+    include_package_data=True,
+    zip_safe=False,
+    classifiers=classifiers,
+    install_requires=get_install_requires(),
+    extras_require={
+        'dev': requires_dev,
+    },
+    python_requires='>=3.8, <4',
+    entry_points={
+        'console_scripts': [
+            'uprobe = uprobe.core.cli:main',
+            'u-probe = uprobe.core.cli:main',
+        ],
+    },
+)

uprobe-0.1.0/tests/test_custom.py

@@ -0,0 +1,53 @@
+import pytest
+from pathlib import Path
+
+from uprobe.gen.probe import construct_probes 
+from uprobe.workflow import parse_yaml, check_protocol_yaml
+from uprobe.gen.probe import DAG
+
+HERE = Path(__file__).parent
+
+target_region="ATGAAGGCCTGCCGGTTATGAAGGCCTGCCGGTTATGAAG"
+gene_id="gene1" 
+encoding_dict = {
+    "gene1": {
+        "BC2": "AAAATTTTTTTTAAGCA",
+        "BC3": "ATTTATTGCGATTTGGC"
+    },
+    "g42115": {
+            "BC2": "AAAATTTTTTTTAAGCA",
+            "BC3": "GGTTTTTTTTTTTTTTT"
+    }
+}
+context = {
+    "target_region": target_region,
+    "gene_id": gene_id,
+    "encoding": encoding_dict,
+}
+
+'''
+def test_probe_dependencies():
+    config = parse_yaml(HERE / "data" / "probes.yaml")
+    #check_protocol_yaml(config)
+    workdir = HERE / "data" / "probe_custom_test"
+    workdir.mkdir(parents=True, exist_ok=True)
+    
+    dag = DAG()
+    dag.from_config(config, workdir)
+    print("dag.nodes:",[node.name for node in dag.nodes])
+    probe_1 = dag.get_node_by_name("probe_1")
+    assert len(probe_1.deps) == 2
+    print("probe_1.deps names:",[dep.name for dep in probe_1.deps])
+    probe_1_part1 = dag.get_node_by_name("probe_1.part1")
+    print("probe_1.part1.deps names:", [dep.name for dep in probe_1_part1.deps] if probe_1_part1 else "Node not found")
+    print("probe_1.part1.external_deps:", probe_1_part1.external_deps if probe_1_part1 else "Node not found")
+    dag.run(context=context)
+'''
+
+def test_construct_probes():
+    config = parse_yaml(HERE / "data" / "probes.yaml")
+    workdir = HERE / "data" / "probe_custom"
+    workdir.mkdir(parents=True, exist_ok=True)
+    construct_probes(workdir, config, context)
+
+