trackplot 0.6.5__tar.gz → 0.7.0__tar.gz

{trackplot-0.6.5/trackplot.egg-info → trackplot-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: trackplot
-Version: 0.6.5
+Version: 0.7.0
 Summary: The trackplot is a tool for visualizing various next-generation sequencing (NGS) data, including DNA-seq, RNA-seq, single-cell RNA-seq and full-length sequencing datasets. https://sashimi.readthedocs.io/
 Author-email: ygidtu <ygidtu@gmail.com>
 License-Expression: BSD-3-Clause
@@ -30,9 +30,9 @@ Dynamic: license-file
 
 [![PyPI version](https://badge.fury.io/py/trackplot.svg)](https://pypi.org/project/trackplot/)
 [![PyPI download](https://img.shields.io/pypi/dm/trackplot.svg)](https://pypi.org/project/trackplot/)
-[![install with bioconda](https://img.shields.io/badge/install%20with-bioconda-brightgreen.svg?style=flat)](http://bioconda.github.io/recipes/trackplot/README.html)
+[![install with bioconda](https://img.shields.io/badge/install%20with-bioconda-brightgreen.svg?style=flat)](https://bioconda.github.io/recipes/trackplot/README.html)
 [![Documentation Status](https://readthedocs.org/projects/trackplot/badge/?version=latest)](https://trackplot.readthedocs.io/en/latest/)
-[![License: BSD 3-Clause](https://img.shields.io/badge/License-BSD%20v3-clause.svg)](https://www.gnu.org/licenses/agpl-3.0)
+[![License: BSD 3-Clause](https://img.shields.io/badge/License-BSD%203--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)
 [![DOI](https://img.shields.io/badge/DOI-10.1101%2F2022.11.02.514803%20-blue)](https://journals.plos.org/ploscompbiol/article?id=10.1371/journal.pcbi.1011477)
 
 ---
@@ -41,11 +41,11 @@ Dynamic: license-file
 
 [Tutorials](https://trackplot.readthedocs.io/en/latest/)
 
-## what is trackplot
+## What is trackplot
 
-trackplot is a tool for visualizing various next-generation sequencing (NGS) data, including DNA-seq, RNA-seq, single-cell RNA-seq and full-length sequencing datasets. 
+Trackplot is a tool for visualizing various next-generation sequencing (NGS) data, including DNA-seq, RNA-seq, single-cell RNA-seq and full-length sequencing datasets. 
 
-### Features of trackplot
+### Features
 
 1. Support various file formats as input
 2. Support strand-aware coverage plot
@@ -78,7 +78,7 @@ Trackplot is based on **Python3** `(python_requires='>=3.8')`,
 and we have simplified the installation process on the main page. 
 For a more comprehensive installation guide, please refer to [this link](./docs/installation.md).
 
-### For impatient
+### Quick start
 
 ```shell
 pip install trackplot
@@ -123,15 +123,23 @@ pip install trackplot
 
 ---
 
-2. [AppImage](https://github.com/ygidtu/trackplot/releases) (Linux/WSL x86_64 platform only)
+2. [AppBundle](https://github.com/xplshn/pelf) (Linux/WSL x86_64 platform only)
 
 For a binary version of the tool and more comprehensive information, please visit [this link](./docs/installation.md).
 
 ```bash
-# example with version v0.3.5, please using your interested version according to your needs
-export VERSION=0.3.5
-chmod +x trackplot-${VERSION}-x86_64.AppImage
-./trackplot-${VERSION}-x86_64.AppImage --help
+# build the AppBundle from source (version auto-detected from pyproject.toml)
+sh build-appbundle.sh
+
+# the output filename and appbundle ID are printed at the end of the script
+# package with pelf (see https://github.com/xplshn/pelf)
+pelf \
+    --add-appdir "./trackplot.AppDir" \
+    --appbundle-id "$APPBUNDLE_ID" \
+    --output-to "$OUTPUT_FILE"
+
+chmod +x "$OUTPUT_FILE"
+./"$OUTPUT_FILE" --help
 ```
 
 ---
@@ -170,20 +178,20 @@ trackplot --help
 <p>
 
 
-1. [AppImage](https://github.com/ygidtu/trackplot/releases) (Linux/WSL x86_64 only)
+1. AppBundle (Linux/WSL x86_64 only)
+
+Build the AppBundle following the [instructions above](#using-trackplot-by-a-command-line), then:
 
 ```bash
-# example with version v0.3.3, please using your interested version according to your needs
-export VERSION=0.3.3
-gunzip trackplot-${VERSION}-x86_64.AppImage
-chmod +x trackplot-${VERSION}-x86_64.AppImage
-./trackplot-${VERSION}-x86_64.AppImage --help
+# OUTPUT_FILE is printed by build-appbundle.sh
+chmod +x "$OUTPUT_FILE"
+./"$OUTPUT_FILE" --help
 
 # startup webserver
-./trackplot-${VERSION}-x86_64.AppImage --start-server --host 0.0.0.0 --port 5000 --plots ./plots
+./"$OUTPUT_FILE" --start-server --host 0.0.0.0 --port 5000 --plots ./plots
 ```
-    
-**Note:** the `--plots` were required while using appimages
+
+**Note:** the `--plots` were required while using appbundles
 
 ---
 
@@ -246,7 +254,7 @@ trackplot \
   -p 4
 ```
 
-if trackplot was installed by docker, here is the cmd
+If trackplot was installed via docker, here is the cmd:
 
 ```bash
 ## The absolute path is required in Docker env.
@@ -280,17 +288,44 @@ docker run -v $PWD:$PWD -w $PWD --rm ygidtu/trackplot \
 
 ```
 
-here is the [output file](https://raw.githubusercontent.com/ygidtu/trackplot/main/example/example.png).
+Here is the [output file](https://raw.githubusercontent.com/ygidtu/trackplot/main/example/example.png).
+
+
+## For AI agents (auto-install the trackplot skill)
+
+This repo ships a ready-to-use **skill** that teaches an AI coding agent how to
+invoke trackplot. When an agent is asked to create a trackplot/sashimi figure,
+it should install this skill once (path relative to this file):
+
+```bash
+# opencode / Claude Code style: point the skill manager at the bundled skill
+cp -r skills/trackplot ~/.config/opencode/skills/trackplot   # or ~/.claude/skills/trackplot
+```
+
+Then the agent reads `skills/trackplot/SKILL.md` (plus
+`skills/trackplot/references/config_files.md` and
+`skills/trackplot/references/python_api.md`) and follows it to:
+
+1. Confirm the input region in `chr:start-end:strand` form and the annotation GTF.
+2. Build the matching config TSV(s) for the requested track type(s) (see the
+   `# filepath  category  label  color` conventions).
+3. Run `trackplot -e <region> -r <gtf> --density <list.tsv> -o <out>.pdf` (or the
+   equivalent Python `Plot(...).set_region(...).add_density(...).plot(...)` chain).
+4. Verify the output exists; if `pybigwig`/`hicmatrix` are needed for bigWig/HiC,
+   install them first.
+
+The skill is the single source of truth for trackplot usage; keep it in sync with
+`docs/command.md` and `docs/interactive.md`.
 
 
 ## Questions
 
-Visit [issues](https://github.com/ygidtu/trackplot/issues) or 
-contact [Yiming Zhang](https://github.com/ygidtu) or 
+Visit [issues](https://github.com/ygidtu/trackplot/issues) or
+contact [Yiming Zhang](https://github.com/ygidtu) or
 [Ran Zhou](https://github.com/zhou-ran)
 
 ## Citation
 
-If you use the tool in your publication, please cite by
+If you use trackplot in your publication, please cite:
 
-[Zhang Y, Zhou R, Liu L, et al. Trackplot: A flexible toolkit for combinatorial analysis of genomic data[J]. PLoS computational biology, 2023, 19(9): e1011477.](https://journals.plos.org/ploscompbiol/article?id=10.1371/journal.pcbi.1011477)
+Zhang Y, Zhou R, Liu L, et al. Trackplot: A flexible toolkit for combinatorial analysis of genomic data. *PLoS Computational Biology*, 2023, 19(9): e1011477.

{trackplot-0.6.5 → trackplot-0.7.0}/README.md

@@ -2,9 +2,9 @@
 
 [![PyPI version](https://badge.fury.io/py/trackplot.svg)](https://pypi.org/project/trackplot/)
 [![PyPI download](https://img.shields.io/pypi/dm/trackplot.svg)](https://pypi.org/project/trackplot/)
-[![install with bioconda](https://img.shields.io/badge/install%20with-bioconda-brightgreen.svg?style=flat)](http://bioconda.github.io/recipes/trackplot/README.html)
+[![install with bioconda](https://img.shields.io/badge/install%20with-bioconda-brightgreen.svg?style=flat)](https://bioconda.github.io/recipes/trackplot/README.html)
 [![Documentation Status](https://readthedocs.org/projects/trackplot/badge/?version=latest)](https://trackplot.readthedocs.io/en/latest/)
-[![License: BSD 3-Clause](https://img.shields.io/badge/License-BSD%20v3-clause.svg)](https://www.gnu.org/licenses/agpl-3.0)
+[![License: BSD 3-Clause](https://img.shields.io/badge/License-BSD%203--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)
 [![DOI](https://img.shields.io/badge/DOI-10.1101%2F2022.11.02.514803%20-blue)](https://journals.plos.org/ploscompbiol/article?id=10.1371/journal.pcbi.1011477)
 
 ---
@@ -13,11 +13,11 @@
 
 [Tutorials](https://trackplot.readthedocs.io/en/latest/)
 
-## what is trackplot
+## What is trackplot
 
-trackplot is a tool for visualizing various next-generation sequencing (NGS) data, including DNA-seq, RNA-seq, single-cell RNA-seq and full-length sequencing datasets. 
+Trackplot is a tool for visualizing various next-generation sequencing (NGS) data, including DNA-seq, RNA-seq, single-cell RNA-seq and full-length sequencing datasets. 
 
-### Features of trackplot
+### Features
 
 1. Support various file formats as input
 2. Support strand-aware coverage plot
@@ -50,7 +50,7 @@ Trackplot is based on **Python3** `(python_requires='>=3.8')`,
 and we have simplified the installation process on the main page. 
 For a more comprehensive installation guide, please refer to [this link](./docs/installation.md).
 
-### For impatient
+### Quick start
 
 ```shell
 pip install trackplot
@@ -95,15 +95,23 @@ pip install trackplot
 
 ---
 
-2. [AppImage](https://github.com/ygidtu/trackplot/releases) (Linux/WSL x86_64 platform only)
+2. [AppBundle](https://github.com/xplshn/pelf) (Linux/WSL x86_64 platform only)
 
 For a binary version of the tool and more comprehensive information, please visit [this link](./docs/installation.md).
 
 ```bash
-# example with version v0.3.5, please using your interested version according to your needs
-export VERSION=0.3.5
-chmod +x trackplot-${VERSION}-x86_64.AppImage
-./trackplot-${VERSION}-x86_64.AppImage --help
+# build the AppBundle from source (version auto-detected from pyproject.toml)
+sh build-appbundle.sh
+
+# the output filename and appbundle ID are printed at the end of the script
+# package with pelf (see https://github.com/xplshn/pelf)
+pelf \
+    --add-appdir "./trackplot.AppDir" \
+    --appbundle-id "$APPBUNDLE_ID" \
+    --output-to "$OUTPUT_FILE"
+
+chmod +x "$OUTPUT_FILE"
+./"$OUTPUT_FILE" --help
 ```
 
 ---
@@ -142,20 +150,20 @@ trackplot --help
 <p>
 
 
-1. [AppImage](https://github.com/ygidtu/trackplot/releases) (Linux/WSL x86_64 only)
+1. AppBundle (Linux/WSL x86_64 only)
+
+Build the AppBundle following the [instructions above](#using-trackplot-by-a-command-line), then:
 
 ```bash
-# example with version v0.3.3, please using your interested version according to your needs
-export VERSION=0.3.3
-gunzip trackplot-${VERSION}-x86_64.AppImage
-chmod +x trackplot-${VERSION}-x86_64.AppImage
-./trackplot-${VERSION}-x86_64.AppImage --help
+# OUTPUT_FILE is printed by build-appbundle.sh
+chmod +x "$OUTPUT_FILE"
+./"$OUTPUT_FILE" --help
 
 # startup webserver
-./trackplot-${VERSION}-x86_64.AppImage --start-server --host 0.0.0.0 --port 5000 --plots ./plots
+./"$OUTPUT_FILE" --start-server --host 0.0.0.0 --port 5000 --plots ./plots
 ```
-    
-**Note:** the `--plots` were required while using appimages
+
+**Note:** the `--plots` were required while using appbundles
 
 ---
 
@@ -218,7 +226,7 @@ trackplot \
   -p 4
 ```
 
-if trackplot was installed by docker, here is the cmd
+If trackplot was installed via docker, here is the cmd:
 
 ```bash
 ## The absolute path is required in Docker env.
@@ -252,17 +260,44 @@ docker run -v $PWD:$PWD -w $PWD --rm ygidtu/trackplot \
 
 ```
 
-here is the [output file](https://raw.githubusercontent.com/ygidtu/trackplot/main/example/example.png).
+Here is the [output file](https://raw.githubusercontent.com/ygidtu/trackplot/main/example/example.png).
+
+
+## For AI agents (auto-install the trackplot skill)
+
+This repo ships a ready-to-use **skill** that teaches an AI coding agent how to
+invoke trackplot. When an agent is asked to create a trackplot/sashimi figure,
+it should install this skill once (path relative to this file):
+
+```bash
+# opencode / Claude Code style: point the skill manager at the bundled skill
+cp -r skills/trackplot ~/.config/opencode/skills/trackplot   # or ~/.claude/skills/trackplot
+```
+
+Then the agent reads `skills/trackplot/SKILL.md` (plus
+`skills/trackplot/references/config_files.md` and
+`skills/trackplot/references/python_api.md`) and follows it to:
+
+1. Confirm the input region in `chr:start-end:strand` form and the annotation GTF.
+2. Build the matching config TSV(s) for the requested track type(s) (see the
+   `# filepath  category  label  color` conventions).
+3. Run `trackplot -e <region> -r <gtf> --density <list.tsv> -o <out>.pdf` (or the
+   equivalent Python `Plot(...).set_region(...).add_density(...).plot(...)` chain).
+4. Verify the output exists; if `pybigwig`/`hicmatrix` are needed for bigWig/HiC,
+   install them first.
+
+The skill is the single source of truth for trackplot usage; keep it in sync with
+`docs/command.md` and `docs/interactive.md`.
 
 
 ## Questions
 
-Visit [issues](https://github.com/ygidtu/trackplot/issues) or 
-contact [Yiming Zhang](https://github.com/ygidtu) or 
+Visit [issues](https://github.com/ygidtu/trackplot/issues) or
+contact [Yiming Zhang](https://github.com/ygidtu) or
 [Ran Zhou](https://github.com/zhou-ran)
 
 ## Citation
 
-If you use the tool in your publication, please cite by
+If you use trackplot in your publication, please cite:
 
-[Zhang Y, Zhou R, Liu L, et al. Trackplot: A flexible toolkit for combinatorial analysis of genomic data[J]. PLoS computational biology, 2023, 19(9): e1011477.](https://journals.plos.org/ploscompbiol/article?id=10.1371/journal.pcbi.1011477)
+Zhang Y, Zhou R, Liu L, et al. Trackplot: A flexible toolkit for combinatorial analysis of genomic data. *PLoS Computational Biology*, 2023, 19(9): e1011477.

{trackplot-0.6.5 → trackplot-0.7.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "trackplot"
-version = "0.6.5"
+version = "0.7.0"
 description = "The trackplot is a tool for visualizing various next-generation sequencing (NGS) data, including DNA-seq, RNA-seq, single-cell RNA-seq and full-length sequencing datasets. https://sashimi.readthedocs.io/"
 authors = [
     { name = "ygidtu", email = "ygidtu@gmail.com" }

{trackplot-0.6.5 → trackplot-0.7.0}/trackplot/base/Transcript.py

@@ -30,6 +30,7 @@ class Transcript(GenomicLoci):
         "domain_type",
         "domain_description",
         "plot_intron",
+        "coding_intervals",
     ]
 
     def __init__(
@@ -47,6 +48,7 @@ class Transcript(GenomicLoci):
         domain_category: str = "",
         domain_type: str = "",
         domain_description: str = "",
+        coding_intervals: Optional[List] = None,
     ):
         """
         :param chromosome:
@@ -62,6 +64,7 @@ class Transcript(GenomicLoci):
         :param domain_category: category of domain
         :param domain_description: description of domain
         :param domain_type: if category is protein, the type information of the given domain
+        :param coding_intervals: list of (start, end) absolute genomic coordinates of the coding region (CDS), used to distinguish UTR from CDS in the annotation plot
         """
 
         super().__init__(chromosome=chromosome, start=start, end=end, strand=strand)
@@ -74,6 +77,7 @@ class Transcript(GenomicLoci):
         self.domain_category = domain_category
         self.domain_type = domain_type
         self.domain_description = domain_description
+        self.coding_intervals = coding_intervals if coding_intervals is not None else []
 
     @property
     def exon_list(self):

{trackplot-0.6.5 → trackplot-0.7.0}/trackplot/cli.py

@@ -489,6 +489,8 @@ def _handle_igv(p, path, kwargs):
             label=f.label,
             exon_color=f.color,
             intron_color=f.color,
+            show_utr=kwargs["show_utr"],
+            utr_color=kwargs["utr_color"],
             features=igv_features or None,
             font_size=kwargs["font_size"],
             n_y_ticks=kwargs["n_y_ticks"],
@@ -787,6 +789,22 @@ def _add_interval(p, f):
     help="The scale of exon",
     show_default=True,
 )
+@optgroup.option(
+    "--show-utr",
+    is_flag=True,
+    type=click.BOOL,
+    show_default=True,
+    help="Whether to distinguish untranslated regions (UTR) from coding regions (CDS) "
+    "inside exons. Requires a GTF/GFF with CDS features. UTR parts are drawn in "
+    "--utr-color while CDS parts keep --ref-color.",
+)
+@optgroup.option(
+    "--utr-color",
+    type=click.STRING,
+    default="#0099CC",
+    show_default=True,
+    help="The fill color of untranslated regions (UTR) in the annotation and IGV-like tracks.",
+)
 @optgroup.group("Density plot settings")
 @optgroup.option(
     "--density",
@@ -1342,6 +1360,8 @@ def main(**kwargs):
                     local_domain=kwargs["local_domain"],
                     domain_include=kwargs["domain_include"],
                     domain_exclude=kwargs["domain_exclude"],
+                    show_utr=kwargs["show_utr"],
+                    utr_color=kwargs["utr_color"],
                 )
             elif key in _CATEGORY_HANDLERS:
                 _CATEGORY_HANDLERS[key](

{trackplot-0.6.5 → trackplot-0.7.0}/trackplot/conf/ui.py

@@ -305,6 +305,18 @@ __PARAMS__ = {
             "default": "0.3",
             "note": "The exon width of current track",
         },
+        {
+            "key": "show_utr",
+            "annotation": "bool",
+            "default": "false",
+            "note": "Whether to distinguish untranslated regions (UTR) from coding regions (CDS) inside exons. Requires an annotation with CDS features loaded in the same plot.",
+        },
+        {
+            "key": "utr_color",
+            "annotation": "color",
+            "default": "#0099CC",
+            "note": "The fill color of untranslated regions (UTR) in the IGV-like track.",
+        },
     ],
     "add_interval": [
         {
@@ -542,6 +554,18 @@ __PARAMS__ = {
             "default": "#000000",
             "note": "The color of exons",
         },
+        {
+            "key": "show_utr",
+            "annotation": "bool",
+            "default": "false",
+            "note": "Whether to distinguish untranslated regions (UTR) from coding regions (CDS) inside exons. Requires a GTF/GFF with CDS features; UTR parts are drawn in --utr-color while CDS parts keep the exon color.",
+        },
+        {
+            "key": "utr_color",
+            "annotation": "color",
+            "default": "#0099CC",
+            "note": "The fill color of untranslated regions (UTR) in the annotation track.",
+        },
         {
             "key": "font_size",
             "annotation": "int",

{trackplot-0.6.5 → trackplot-0.7.0}/trackplot/file/Annotation.py

@@ -119,6 +119,17 @@ class Annotation(File):
                 res.append([exon.start, exon.end])
         return sorted(res, key=lambda x: [x[0], x[1]])
 
+    @property
+    def coding_intervals(self) -> List[tuple]:
+        """
+        Merge coding (CDS) intervals across all loaded transcripts for the region,
+        used to distinguish UTR from CDS in the IGV-like plot.
+        """
+        merged = []
+        for transcript in self.data:
+            merged.extend(transcript.coding_intervals)
+        return merged
+
     @classmethod
     def create(
         cls,
@@ -393,6 +404,7 @@ class Annotation(File):
         # AD - passing transcripts_to_show
         transcripts = {}
         exons = {}
+        coding = {}
         for rec in Reader.read_gtf(self.path, self.region):
             start = max(rec.start, self.region.start)
             end = min(rec.end, self.region.end)
@@ -428,6 +440,9 @@ class Annotation(File):
                         exons=[],
                     )
 
+                if re.search(r"(cds)", rec.feature, re.I):
+                    coding.setdefault(rec.transcript_id, []).append((start, end))
+
             elif re.search(r"(exon)", rec.feature, re.I):
                 if rec.transcript_id not in exons.keys():
                     exons[rec.transcript_id] = []
@@ -456,6 +471,8 @@ class Annotation(File):
         for key, trans in transcripts.items():
             if key in exons.keys():
                 trans.exons += exons[key]
+            if key in coding.keys():
+                trans.coding_intervals = coding[key]
 
         self.data += sorted(transcripts.values())
 

{trackplot-0.6.5 → trackplot-0.7.0}/trackplot/file/Bam.py

@@ -263,11 +263,8 @@ class Bam(SingleCell):
                         ):
                             continue
 
-                        if len(umis[barcode]) == 0:
+                        if umi not in umis[barcode]:
                             umis[barcode][umi] = hash(read.query_name)
-                        # else:
-                        #     # There is no umi tag in atacdata, and we add it
-                        #     continue
 
                 start = read.reference_start
                 if required_strand and strand != required_strand:

{trackplot-0.6.5 → trackplot-0.7.0}/trackplot/plot/core.py

@@ -284,6 +284,8 @@ class Plot(object):
             "show_id": kwargs.get("show_id", False),
             "exon_width": kwargs.get("exon_width", 0.3),
             "show_exon_id": kwargs.get("show_exon_id", False),
+            "show_utr": kwargs.get("show_utr", False),
+            "utr_color": kwargs.get("utr_color", None),
             "theme": kwargs.get("theme", "blank"),
         }
         return self
@@ -592,6 +594,8 @@ class Plot(object):
         intron_color=None,
         feature_color=None,
         exon_width=0.3,
+        show_utr=False,
+        utr_color=None,
         height_scale=None,
         font_size=8,
         n_y_ticks=1,
@@ -621,6 +625,8 @@ class Plot(object):
             "font_size": font_size,
             "n_y_ticks": n_y_ticks,
             "show_y_label": show_y_label,
+            "show_utr": show_utr,
+            "utr_color": utr_color,
             "theme": theme,
         }
         return self
@@ -1189,12 +1195,16 @@ class Plot(object):
                     **self.params.get(p, {}),
                 )
             elif p.type == "igv":
+                coding_intervals = []
+                if self.params.get(p, {}).get("show_utr") and self.annotation is not None:
+                    coding_intervals = self.annotation.coding_intervals
                 plot_igv_like(
                     ax=ax_var,
                     obj=p.data,
                     graph_coords=self.graph_coords,
                     raster=raster,
                     distance_between_label_axis=distance_between_label_axis,
+                    coding_intervals=coding_intervals,
                     **self.params.get(p, {}),
                 )
             elif p.type == "motif":