trackplot 0.6.6__tar.gz → 0.7.1__tar.gz

{trackplot-0.6.6/trackplot.egg-info → trackplot-0.7.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: trackplot
-Version: 0.6.6
+Version: 0.7.1
 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.6 → trackplot-0.7.1}/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.6 → trackplot-0.7.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "trackplot"
-version = "0.6.6"
+version = "0.7.1"
 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.6 → trackplot-0.7.1}/trackplot/base/Readder.py

@@ -136,20 +136,30 @@ class Reader(object):
                 yield read, __get_strand__(read, library=library)
 
     @classmethod
-    def read_gtf(cls, path: str, region: GenomicLoci, bed: bool = False):
+    def read_gtf(
+        cls,
+        path: str,
+        region: GenomicLoci,
+        bed: bool = False,
+        fmt: Optional[str] = None,
+    ):
+        if bed:
+            parser = pysam.asBed()
+        elif fmt == "gff":
+            parser = pysam.asGFF3()
+        else:
+            parser = pysam.asGTF()
         with pysam.TabixFile(path) as r:
             try:
                 iter_ = r.fetch(
                     region.chromosome,
                     region.start,
                     region.end,
-                    parser=pysam.asGTF() if not bed else pysam.asBed(),
+                    parser=parser,
                 )
             except ValueError:
                 try:
-                    iter_ = cls.__modify_chrom__(
-                        region, r, parser=pysam.asGTF() if not bed else pysam.asBed()
-                    )
+                    iter_ = cls.__modify_chrom__(region, r, parser=parser)
                 except ValueError as err:
                     logger.debug("please check the input region and gtf files")
                     logger.error(err)

{trackplot-0.6.6 → trackplot-0.7.1}/trackplot/base/Transcript.py

@@ -7,7 +7,7 @@ Changelog:
     1. remove attributes
 """
 
-from typing import List
+from typing import List, Optional
 
 from trackplot.base.GenomicLoci import GenomicLoci
 
@@ -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.6 → trackplot-0.7.1}/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.6 → trackplot-0.7.1}/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",