RILseq-analysis 1.0.0__tar.gz

rilseq_analysis-1.0.0/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: RILseq_analysis
+Version: 1.0.0
+Requires-Dist: pandas
+Requires-Dist: seaborn
+Requires-Dist: matplotlib
+Requires-Dist: matplotlib-venn
+Requires-Dist: numpy
+Requires-Dist: openpyxl
+Requires-Dist: pyyaml

rilseq_analysis-1.0.0/README.md

@@ -0,0 +1,405 @@
+# RILseq-analysis
+
+Python package for downstream analysis of **RILseq** datasets.
+
+The package provides tools for merging RIL-seq results from multiple libraries and performing comparative and visualization analyses of RNA-RNA interactions. It is designed to facilitate the analysis of significant chimeric interactions generated by the RILseq pipeline.
+
+## Features
+
+RILseq-analysis provides command-line tools for:
+
+* Merging significant interactions from multiple RILseq libraries into a unified Excel workbook.
+* Comparing RNA-RNA interactions between experimental conditions using Venn diagrams.
+* Generating Circos plots for visualization of RNA-RNA interaction networks.
+* Generating bar plots showing RNA annotation percentages.
+* Generating heatmaps showing the RNA annotations of the two components of the chimeras.
+* Quantifying and visualizing sRNA representation among S-chimeras and RILseq and RNAseq read counts.
+* Counting the number of libraries in which each RNA-RNA interaction is detected and enaming columns in the resulting S-chimeras workbook.
+
+---
+
+## Installation
+
+The package can be installed directly from GitHub:
+
+```bash
+pip install git+https://github.com/Reut-Wasserman/RILseq-analysis.git
+```
+
+
+### Requirements
+
+The package is written in Python and uses packages including:
+
+* pandas
+* numpy
+* matplotlib
+* seaborn
+* matplotlib-venn
+* openpyxl
+* PyYAML
+
+Some analyses also require **R** and the **RCircos** R package.
+
+---
+
+# Configuration
+
+Most commands require a YAML configuration file.
+
+The configuration file should contain the following keys:
+
+```yaml
+base_path: "base_path"
+
+annotation_path: "annotation_path"
+
+rna_types_excel: "rna_types_excel"
+
+experiments:
+  - "experiment1"
+  - "experiment2"
+
+replicates:
+  - "_I"
+  - "_II"
+
+chr_dic:
+  "chrI": "organism1 name"
+  "chrII": "organism2 name"
+
+chr_len:
+  "chrI": chromosome1_length
+  "chrII": chromosome2_length
+```
+
+### Configuration fields
+
+| Key               | Description                                                                               |
+| ----------------- | ----------------------------------------------------------------------------------------- |
+| `base_path`       | Directory containing the `sig_interactions.txt` and `all_counts_table.txt` files.         |
+| `annotation_path` | Path to the GFF annotation file used in the RILseq pipeline.                             |
+| `rna_types_excel` | Path to an Excel file containing RNA annotations.                                         |
+| `experiments`     | List of experiment names.                                                                 |
+| `replicates`      | List of replicate suffixes/names.                                                         |
+| `chr_dic`         | Dictionary mapping chromosome names in the annotation file to names displayed in figures. |
+| `chr_len`         | Dictionary containing chromosome lengths in base pairs.                                   |
+
+### RNA annotation Excel file
+
+The Excel file specified by `rna_types_excel` should contain the following sheets:
+
+* `sRNA`
+* `oRNA`
+* `rRNA`
+* `tRNA`
+
+Each sheet should contain a `Name` column listing the corresponding RNA names.
+
+---
+
+# Workflow
+
+A typical downstream analysis consists of the following steps:
+
+1. Create a configuration file.
+2. Merge results from multiple RIL-seq libraries.
+3. Compare conditions using Venn diagrams.
+4. Generate Circos input files and plots.
+5. Generate annotation bar plots and heatmaps.
+6. Generate sRNA percentage plots.
+7. Count the number of libraries supporting each interaction.
+
+The commands can also be run independently when only a subset of the analyses is required.
+
+---
+
+# Commands
+
+## 1. Merge RIL-seq results
+
+Merge significant interactions from multiple libraries into a unified Excel workbook.
+
+```bash
+merge-results config_path file_names
+```
+
+### Arguments
+
+* `config_path` — path to the YAML configuration file.
+* `file_names` — path to a tab-separated file containing two columns:
+
+  1. significant-interactions file name
+  2. corresponding experiment name as defined in the YAML configuration.
+
+For example:
+
+```text
+unified_Hfq_lambda_60_example_sig_interactions.txt    Hfq_lambda_60
+unified_Hfq_lambda_30_example_sig_interactions.txt    Hfq_lambda_30
+Hfq_lambda_30_I_example_sig_interactions.txt          Hfq_lambda_30_I
+Hfq_lambda_30_II_example_sig_interactions.txt         Hfq_lambda_30_II
+Hfq_lambda_60_I_example_sig_interactions.txt          Hfq_lambda_60_I
+Hfq_lambda_60_II_example_sig_interactions.txt         Hfq_lambda_60_II
+```
+
+By default, annotation information is included in the output.
+
+To exclude the annotations column:
+
+```bash
+merge-results config_path file_names --no-annotations
+```
+
+### Output
+
+The command produces a unified Excel workbook containing the interactions from the specified libraries.
+
+---
+
+## 2. Compare conditions using Venn diagrams
+
+Generate Venn diagrams comparing chimeric interactions between pairs of conditions. RNA1/RNA2 orientation is ignored when determining whether two chimeras represent the same interaction.
+
+```bash
+chimeras-venn config_path conditions_pairs
+```
+
+`conditions_pairs` is a comma-separated list of condition pairs. Conditions within each pair are separated by `-`.
+
+For example:
+
+```bash
+chimeras-venn config_path "Hfq_30-Hfq_lambda_30,Hfq_60-Hfq_lambda_60"
+```
+
+A separate Venn diagram is generated for each pair.
+
+By default, all S-chimeras are included. To restrict the analysis to specific chromosomes, use --chr to provide list of chromosomes separated by a comma.
+
+```bash
+chimeras-venn config_path "Hfq_30-Hfq_lambda_30" --chr chrI,chrII
+```
+
+---
+
+## 3. Generate Circos plots
+
+The `circos-plot` command generates the input files required for visualization of RNA-RNA interactions using circos_plot.R script.
+
+```bash
+circos-plot plot_type config_path
+```
+
+Two plot types are available:
+
+### `two_genomes_half_circle`
+
+Generates a plot in which each genome occupies half of the circle.
+
+### `two_genomes_real_proportions`
+
+Generates a plot in which each genome is represented proportionally to its actual length.
+
+### Optional parameters
+
+#### `--mark_step1`
+
+Interval between scale marks on the first chromosome.
+
+Default:
+
+```text
+200000
+```
+
+Used only with `two_genomes_real_proportions`.
+
+#### `--mark_step2`
+
+Interval between scale marks on the second chromosome.
+
+Default:
+
+```text
+48500
+```
+
+Used only with `two_genomes_real_proportions`.
+
+#### `--genes`
+
+Restrict the plot to chimeras involving specific genes.
+
+Genes should be provided as a string separated by underscores.
+
+For example:
+
+```bash
+--genes "geneA_geneB_geneC"
+```
+
+#### `--present_chr`
+
+Present the chimeras of the given chromosome only.
+
+For example:
+
+```bash
+--present_chr chrII
+```
+
+If this option is not provided, interactions involving both chromosomes are included.
+
+### Generating the Circos figures
+
+The `circos-plot` command generates the input CSV files. The final Circos plots are generated using the circos_plot.R script in the `R/` directory. Users can open the script, modify the parameters according to their dataset, and run it directly using R or RStudio.
+
+---
+
+## 4. Generate annotation plots
+
+Generate annotation percentage bar plots and RNA1/RNA2 annotation heatmaps.
+
+```bash
+annotations-graphs config_path
+```
+
+The command uses the RNA annotation information specified by `rna_types_excel` and the merged RIL-seq results.
+
+The generated figures summarize the annotation composition of the RNA-RNA interactions.
+
+---
+
+## 5. Generate sRNA percentage plots
+
+Generate bar plots showing the representation of sRNAs among S-chimeras and RILseq and RNAseq read counts.
+
+```bash
+sRNAs-percent config_path sRNAs_number
+```
+
+### Arguments
+
+* `config_path` — path to the YAML configuration file.
+* `sRNAs_number` — number of sRNAs to display in the bar plots.
+
+For example:
+
+```bash
+sRNAs-percent config_path 15
+```
+
+### RNA-seq normalization
+
+Optionally, RNAseq counts can be provided:
+
+```bash
+sRNAs-percent config_path 15 --RNAseq_counts RNAseq_counts.txt
+```
+
+When RNA-seq counts are provided, an additional graph is generated showing the percentage of sRNAs according to their RNAseq representation.
+
+---
+
+## 6. Count supporting libraries
+
+Calculate the number of libraries in which each RNA-RNA interaction is detected.
+
+```bash
+libraries-num config_path
+```
+
+The command also renames columns in the S-chimeras workbook.
+
+**Warning:** Renaming the columns may break compatibility with other analysis scripts. Run this command only when the resulting workbook will not be used as input for scripts that depend on the original column names.
+
+---
+
+# Example Dataset
+
+Example files are provided to facilitate validation of the workflow.
+
+The example dataset contains a small subset of a complete RILseq dataset and can be used to verify that the analysis commands produce the expected output.
+
+The example files correspond to the output generated during the downstream RILseq analysis workflow and can be used to reproduce the example figures.
+
+A typical validation workflow is:
+
+```bash
+merge-results config.yaml file_names.txt
+
+chimeras-venn config.yaml "Hfq_lambda_30-Hfq_lambda_60"
+
+circos-plot two_genomes_half_circle config.yaml
+
+annotations-graphs config.yaml
+
+sRNAs-percent config.yaml 5
+
+libraries-num config.yaml
+```
+
+---
+
+# Input Files
+
+Depending on the analysis, the package uses the following input files:
+
+### `sig_interactions.txt`
+
+Significant RNA-RNA interactions generated by the RILseq analysis pipeline for each library.
+
+### `all_counts_table.txt`
+
+Counts table (reads per gene for all libraries) generated by the RILseq analysis pipeline.
+
+### GFF annotation file
+
+The annotation file used by the RILseq pipeline.
+
+### RNA annotation Excel file
+
+An Excel file containing RNA names grouped into:
+
+```text
+sRNA
+oRNA
+rRNA
+tRNA
+```
+
+### RNA-seq counts
+
+Optional RNAseq counts used by `sRNAs-percent` to compare sRNA representation with RNA abundance.
+
+---
+
+# Output
+
+Depending on the command, the package generates:
+
+* Unified Excel workbooks containing results from multiple libraries.
+* Venn diagrams comparing experimental conditions.
+* Circos plots and Intermediate files.
+* Annotation percentage bar plots.
+* RNA1/RNA2 annotation heatmaps.
+* sRNA percentage bar plots.
+* Tables containing the number of supporting libraries for each interaction.
+
+
+# RILseq
+
+This package is intended for **downstream analysis** of RILseq results and does not perform the upstream processing of raw sequencing data.
+
+For upstream RIL-seq processing, see the original RIL-seq computational pipeline:
+
+https://github.com/asafpr/RILseq
+
+---
+
+# Citation
+
+If you use `RILseq-analysis` in your work, please cite the corresponding RILseq study and the original RILseq methodology.
+
+---

rilseq_analysis-1.0.0/RILseq_analysis.egg-info/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: RILseq_analysis
+Version: 1.0.0
+Requires-Dist: pandas
+Requires-Dist: seaborn
+Requires-Dist: matplotlib
+Requires-Dist: matplotlib-venn
+Requires-Dist: numpy
+Requires-Dist: openpyxl
+Requires-Dist: pyyaml

rilseq_analysis-1.0.0/RILseq_analysis.egg-info/SOURCES.txt

@@ -0,0 +1,20 @@
+README.md
+pyproject.toml
+RILseq_analysis.egg-info/PKG-INFO
+RILseq_analysis.egg-info/SOURCES.txt
+RILseq_analysis.egg-info/dependency_links.txt
+RILseq_analysis.egg-info/entry_points.txt
+RILseq_analysis.egg-info/requires.txt
+RILseq_analysis.egg-info/top_level.txt
+RILseq_analysis_package/__init__.py
+RILseq_analysis_package/annotations_graphs.py
+RILseq_analysis_package/chimeras_venn_diagram.py
+RILseq_analysis_package/circos_plot.py
+RILseq_analysis_package/extract_genes_by_chr.py
+RILseq_analysis_package/generate_and_edit_RILseq_xslx.py
+RILseq_analysis_package/sRNAs_percent.py
+RILseq_analysis_package/utils.py
+RILseq_analysis_package/cli/__init__.py
+RILseq_analysis_package/cli/add_number_of_libraries_cli.py
+RILseq_analysis_package/cli/circos_plot_cli.py
+RILseq_analysis_package/cli/merge_results_cli.py

rilseq_analysis-1.0.0/RILseq_analysis.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

rilseq_analysis-1.0.0/RILseq_analysis.egg-info/entry_points.txt

@@ -0,0 +1,8 @@
+[console_scripts]
+annotations-graphs = RILseq_analysis_package.annotations_graphs:main
+chimeras-venn = RILseq_analysis_package.chimeras_venn_diagram:main
+circos-plot = RILseq_analysis_package.cli.circos_plot_cli:main
+filter-genes = RILseq_analysis_package.extract_genes_by_chr:main
+libraries-num = RILseq_analysis_package.cli.add_number_of_libraries_cli:main
+merge-results = RILseq_analysis_package.cli.merge_results_cli:main
+sRNAs-percent = RILseq_analysis_package.sRNAs_percent:main

rilseq_analysis-1.0.0/RILseq_analysis.egg-info/requires.txt

@@ -0,0 +1,7 @@
+pandas
+seaborn
+matplotlib
+matplotlib-venn
+numpy
+openpyxl
+pyyaml

rilseq_analysis-1.0.0/RILseq_analysis.egg-info/top_level.txt

@@ -0,0 +1 @@
+RILseq_analysis_package

rilseq_analysis-1.0.0/RILseq_analysis_package/annotations_graphs.py

@@ -0,0 +1,185 @@
+import pandas as pd
+import os
+import seaborn as sns
+import matplotlib.pyplot as plt
+from RILseq_analysis_package.utils import get_annotation, get_RNA_types, load_config
+import argparse
+
+
+
+def get_gene_annotation(gene, genes, tRNAs, sRNAs, oRNAs):
+    if gene in tRNAs:
+        return "tRNA"
+    if gene in sRNAs:
+        return "sRNA"
+    if gene in oRNAs:
+        return "oRNA"
+    if "3UTR" in gene:
+        return "3UTR"
+    if "5UTR" in gene:
+        return "5UTR"
+    if "AS" in gene:
+        return "AS"
+    if "IGR" in gene:
+        return "IGR"
+    if "IGT" in gene:
+        return "IGT"
+    if gene in genes:
+        return "CDS"
+    return "unknown"
+
+
+def get_RNAs_types(rna_types_excel):
+    sRNAs = set(get_RNA_types("sRNA", rna_types_excel))
+    tRNAs = set(get_RNA_types("tRNA", rna_types_excel))
+    oRNAs = set(get_RNA_types("oRNA", rna_types_excel))
+    return sRNAs, tRNAs, oRNAs
+
+
+def RNA1_RNA2_annotations(chr_dic, base_path, experiments, rna_types_excel, annotation_path, chimeras_or_fragments, chrom=None):
+    """
+    Creates heatmaps of the chimeras annotations, with and without the annotations numbers.
+    :param chimeras_or_fragments: if "chimeras" create the heatmaps according to the amount of chimeras. Else, according
+    to the amount of fragments.
+    :param chrom: if None, create the heatmaps base on the chimeras between the two chromosomes. Else, create the heatmaps
+     base on the chimeras of the given chromosome.
+    """
+    genes = get_annotation(annotation_path, chromosome=chrom, separate_id_name=True)["name"].values.tolist()
+    sRNAs, tRNAs, oRNAs = get_RNAs_types(rna_types_excel)
+    if chrom:
+        dir_ = chr_dic[chrom] + "_annotation"
+    else:
+        dir_ = "_".join(chr_dic.values()) + "_annotation"
+    output_path = os.path.join(base_path, dir_)
+    if not os.path.exists(output_path):
+        os.makedirs(output_path)
+    for experiment in experiments:
+        df = pd.read_excel(os.path.join(base_path, "RILseq_unified_results.xlsx"), sheet_name=experiment)
+        if chrom is not None:
+            df = df[(df["RNA1 chromosome"] == chrom) & (df["RNA2 chromosome"] == chrom)]
+        else:
+            chr1, chr2 = chr_dic.keys()
+            df = df[((df["RNA1 chromosome"] == chr1) & (df["RNA2 chromosome"] == chr2)) |
+                    ((df["RNA1 chromosome"] == chr2) & (df["RNA2 chromosome"] == chr1))]
+        df["RNA1_annotation"] = df["RNA1 name"].apply(get_gene_annotation, genes=genes, tRNAs=tRNAs, sRNAs=sRNAs, oRNAs=oRNAs)
+        df["RNA2_annotation"] = df["RNA2 name"].apply(get_gene_annotation, genes=genes, tRNAs=tRNAs, sRNAs=sRNAs, oRNAs=oRNAs)
+        options = ["3UTR", "5UTR", "CDS", "AS", "IGR", "sRNA", "tRNA", "IGT"] #"oRNA"
+
+        if chimeras_or_fragments == "chimeras":
+            df["i"] = df.index
+            df = df[["RNA1_annotation", "RNA2_annotation", "i"]]
+            small_df = df.groupby(["RNA1_annotation", "RNA2_annotation"]).count()
+            small_df_pairs = small_df.index
+            amount = small_df["i"].values
+        else:
+            df = df[["RNA1_annotation", "RNA2_annotation", "interactions"]]
+            small_df = df.groupby(["RNA1_annotation", "RNA2_annotation"]).sum()
+            small_df_pairs = small_df.index
+            amount = small_df["interactions"].values
+        dic = {}
+        for i in range(len(amount)):
+            dic[small_df_pairs[i]] = amount[i]
+        results = pd.DataFrame(0, index=options, columns=options)
+        for option1 in options:
+            for option2 in options:
+                if (option1, option2) in small_df_pairs:
+                    results.loc[option2, option1] = dic[(option1, option2)]
+        for annot in [True, False]:
+            plt.figure()
+            sns.heatmap(results, annot=annot, cmap='Blues', fmt=".6g", annot_kws={"size": 8})
+            plt.xlabel("RNA1")
+            plt.ylabel("RNA2")
+            with_annot = "with_annot" if annot else "without_annot"
+            plt.savefig(os.path.join(output_path, f"{experiment}_{chimeras_or_fragments}_{with_annot}.png"))
+
+
+def get_RNAs_type_fractions(df, options, chimeras_or_fragments):
+    """
+    :param df: chimeras data-frame
+    :param options: the annotations
+    :param chimeras_or_fragments: if "chimeras" calculate the fraction according to the amount of chimeras. Else, according
+    to the amount of fragments.
+    :return: a list of the fraction of each annotation
+    """
+    if df.empty:
+        return [0] * len(options)
+    amount_dic = {i:0 for i in options}
+    for RNA in "12":
+        small_df = df[[f"RNA{RNA}_annotation", "interactions"]]
+        small_df = small_df.groupby([f"RNA{RNA}_annotation"])
+        if chimeras_or_fragments == "chimeras":
+            small_df = small_df.count()
+        elif chimeras_or_fragments == "fragments":
+            small_df = small_df.sum()
+        indexes = small_df.index
+        for index in indexes:
+            amount_dic[index] += small_df["interactions"][index]
+    amount_list = [amount_dic[i] for i in options]
+    amount_sum = sum(amount_list)
+    return [i/amount_sum for i in amount_list]
+
+
+def chimeras_annotations(chr_dic, experiments, base_path, annotation_path, rna_types_excel, chimeras_or_fragments):
+    """
+    Creates a bar plot of the annotation fraction for within and between chromosomes for each time point.
+    :param chimeras_or_fragments: if "chimeras" create the bar plot according to the amount of chimeras. Else, according
+    to the amount of fragments.
+    """
+    genes = get_annotation(annotation_path, separate_id_name=True)["name"].values.tolist()
+    sRNAs, tRNAs, oRNAs = get_RNAs_types(rna_types_excel)
+    options = ["3UTR", "sRNA", "CDS", "5UTR", "IGR", "AS", "tRNA", "oRNA", "IGT"]
+    final_dic = {}
+    chr1, chr2 = chr_dic.keys()
+    chr1_name = chr_dic[chr1]
+    chr2_name = chr_dic[chr2]
+    for experiment in experiments:
+        df = pd.read_excel(os.path.join(base_path, "RILseq_unified_results.xlsx"), sheet_name=experiment)
+        df["RNA1_annotation"] = df["RNA1 name"].apply(get_gene_annotation, genes=genes, tRNAs=tRNAs, sRNAs=sRNAs, oRNAs=oRNAs)
+        df["RNA2_annotation"] = df["RNA2 name"].apply(get_gene_annotation, genes=genes, tRNAs=tRNAs, sRNAs=sRNAs, oRNAs=oRNAs)
+        chr1_df = df[(df["RNA1 chromosome"] == chr1) & (df["RNA2 chromosome"] == chr1)]
+        chr2_df = df[(df["RNA1 chromosome"] == chr2) & (df["RNA2 chromosome"] == chr2)]
+        chr1_chr2 = df[((df["RNA1 chromosome"] == chr1) & (df["RNA2 chromosome"] == chr2)) |
+                           ((df["RNA1 chromosome"] == chr2) & (df["RNA2 chromosome"] == chr1))]
+        if chimeras_or_fragments == "chimeras":
+            chr1_amount = chr1_df.shape[0]
+            chr1_chr2_amount = chr1_chr2.shape[0]
+            chr2_amount = chr2_df.shape[0]
+        else:
+            chr1_amount = chr1_df["interactions"].sum()
+            chr1_chr2_amount = chr1_chr2["interactions"].sum()
+            chr2_amount = chr2_df["interactions"].sum()
+        final_dic[f"{chr1_name}-{chr1_name} {experiment} ({chr1_amount})"] = get_RNAs_type_fractions(chr1_df, options, chimeras_or_fragments)
+        final_dic[f"{chr1_name}-{chr2_name} {experiment} ({chr1_chr2_amount})"] = get_RNAs_type_fractions(chr1_chr2, options, chimeras_or_fragments)
+        final_dic[f"{chr2_name}-{chr2_name} {experiment} ({chr2_amount})"] = get_RNAs_type_fractions(chr2_df, options, chimeras_or_fragments)
+    df = pd.DataFrame.from_dict(final_dic, orient="index", columns=options)
+    df = df[df.columns[(df != 0).any()]]
+    fig = plt.figure()
+    h = df.plot(kind="bar", linewidth=0, stacked=True, grid=False, cmap="tab20c")
+    plt.subplots_adjust(bottom=0.35, right=0.7)
+    plt.xticks(rotation=-45, ha='left')
+    handles, labels = h.get_legend_handles_labels()
+    plt.legend(handles[::-1], labels[::-1], loc=(1.1, 0))
+    plt.tight_layout()
+    plt.savefig(os.path.join(base_path, f"{chimeras_or_fragments}_annotation_fractions.png"))
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Create annotation heatmaps and annotation fraction plots for RIL-seq chimeras and fragments.")
+
+    parser.add_argument("config", help="Path to the YAML configuration file.")
+
+    args = parser.parse_args()
+    config = load_config(args.config)
+
+    for type_ in ("fragments", "chimeras"):
+        for chrom in config["chr_dic"].keys():
+            RNA1_RNA2_annotations(config["chr_dic"], config["base_path"], config["experiments"], config["rna_types_excel"], config["annotation_path"], type_, chrom)
+        RNA1_RNA2_annotations(config["chr_dic"], config["base_path"], config["experiments"], config["rna_types_excel"], config["annotation_path"], type_)
+
+        chimeras_annotations(config["chr_dic"], config["experiments"], config["base_path"], config["annotation_path"], config["rna_types_excel"], type_)
+
+
+
+
+
+