cellmaps-utils 0.6.0__tar.gz → 0.7.0__tar.gz

{cellmaps_utils-0.6.0 → cellmaps_utils-0.7.0}/HISTORY.rst

@@ -2,6 +2,13 @@
 History
 =======
 
+0.7.0 (2025-03-05)
+------------------
+
+* Add ``compute_hierarchy_robustness`` method to ``HierarchyDiff`` class to assess the robustness of a hierarchy
+  based on Jaccard similarity across multiple alternative hierarchies.
+
+
 0.6.0 (2025-02-05)
 ------------------
 

{cellmaps_utils-0.6.0 → cellmaps_utils-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: cellmaps_utils
-Version: 0.6.0
+Version: 0.7.0
 Summary: Contains utilities needed by Cell Maps tools
 Home-page: https://github.com/idekerlab/cellmaps_utils
 Author: Cell Maps team
@@ -145,6 +145,13 @@ This package was created with Cookiecutter_ and the `audreyr/cookiecutter-pypack
 History
 =======
 
+0.7.0 (2025-03-05)
+------------------
+
+* Add ``compute_hierarchy_robustness`` method to ``HierarchyDiff`` class to assess the robustness of a hierarchy
+  based on Jaccard similarity across multiple alternative hierarchies.
+
+
 0.6.0 (2025-02-05)
 ------------------
 

{cellmaps_utils-0.6.0 → cellmaps_utils-0.7.0}/cellmaps_utils/__init__.py

@@ -4,6 +4,6 @@
 
 __author__ = 'Cell Maps team'
 __email__ = 'tools@cm4ai.org'
-__version__ = '0.6.0'
+__version__ = '0.7.0'
 __repo_url__ = 'https://github.com/idekerlab/cellmaps_utils'
 __description__ = 'Contains utilities needed by Cell Maps tools'

cellmaps_utils-0.7.0/cellmaps_utils/hierdiff.py

@@ -0,0 +1,142 @@
+import logging
+
+import numpy as np
+import pandas as pd
+from ndex2.cx2 import RawCX2NetworkFactory, CX2Network
+
+logger = logging.getLogger(__name__)
+
+
+class HierarchyDiff:
+    """
+    A class to compare two hierarchies in CX2 (HCX)
+    """
+
+    def __init__(self):
+        """
+        Constructor
+        """
+        pass
+
+    @staticmethod
+    def _calculate_jaccard(setA, setB):
+        """
+        Calculate the Jaccard similarity between two sets.
+
+        The Jaccard similarity is defined as |A ∩ B| / |A ∪ B|.
+
+        :param setA: First set.
+        :type setA: set
+        :param setB: Second set.
+        :type setB: set
+        :return: The Jaccard similarity index.
+        :rtype: float
+        """
+        overlap = len(setA.intersection(setB))
+        union = len(setA.union(setB))
+        return overlap / union if union > 0 else 0
+
+    def _hierarchy_overlap(self, ref_hierarchy, alt_hierarchy):
+        """
+        Computes a  Jaccard similarity between nodes in two CX2Network hierarchies.
+        For each node in the alternative hierarchy, it calculates the Jaccard index with each node in
+        the reference hierarchy.
+
+        :param ref_hierarchy: The reference hierarchy to compare against.
+        :type ref_hierarchy: ndex2.cx2.CX2Network
+        :param alt_hierarchy: The alternative hierarchy being compared.
+        :type alt_hierarchy: ndex2.cx2.CX2Network
+        :return: A DataFrame of pass/fail (1/0) based on Jaccard similarity.
+        :rtype: pandas.DataFrame
+        """
+        ref_nodes = ref_hierarchy.get_nodes()
+        nodes = alt_hierarchy.get_nodes()
+
+        # Prepare a DataFrame to hold JI values
+        ji_df = pd.DataFrame(index=list(nodes.keys()), columns=list(ref_nodes.keys()), dtype=float)
+
+        for node_id, node_obj in nodes.items():
+            ont_comp_genes = set(node_obj.get('v', {}).get('CD_MemberList', '').split())
+            for ref_node_id, ref_node_obj in ref_nodes.items():
+                comp_genes = set(ref_node_obj.get('v', {}).get('CD_MemberList', '').split())
+                ji_df.at[node_id, ref_node_id] = self._calculate_jaccard(ont_comp_genes, comp_genes) \
+                    if ont_comp_genes and comp_genes else 0
+
+        return ji_df
+
+    def compute_hierarchy_robustness(self, ref_hierarchy, alt_hierarchies, ji_thre=0.4):
+        """
+        Computes a robustness score for each node in a reference hierarchy based on its structural overlap
+        across multiple alternative hierarchies. The overlap is measured using the Jaccard Index (JI),
+        and a threshold that determines if a node is considered to have sufficient overlap in a given
+        alternative hierarchy (values above the threshold are set to 1, while values below are set to 0).
+        The higher the overlap across the alternative hierarchies, the higher the robustness score.
+
+        robustness = (# hierarchies where JI > ji_thre) / (total number of alternative hierarchies)
+
+        :param ref_hierarchy: The reference hierarchy whose nodes' robustness is computed.
+        :type ref_hierarchy: ndex2.cx2.CX2Network or dict (raw CX2)
+        :param alt_hierarchies: A list of alternative hierarchies to compare against.
+        :type alt_hierarchies: list[ndex2.cx2.CX2Network or dict]
+        :param ji_thre: The Jaccard threshold used to determine overlap.
+        :type ji_thre: float
+        :return: The reference hierarchy with an added 'robustness' attribute for each node.
+        :rtype: ndex2.cx2.CX2Network
+        """
+        factory = RawCX2NetworkFactory()
+        ref_hier = ref_hierarchy if isinstance(ref_hierarchy, CX2Network) else factory.get_cx2network(ref_hierarchy)
+        alt_hiers = []
+        for hier in alt_hierarchies:
+            alt_hiers.append(hier if isinstance(hier, CX2Network) else factory.get_cx2network(hier))
+        r_hier = pd.DataFrame(index=list(ref_hier.get_nodes().keys()))
+        r_hier['robustness'] = [0] * len(r_hier)
+        for hierarchy in alt_hiers:
+            ji_df = self._hierarchy_overlap(ref_hier, hierarchy)
+            # Make a "pass/fail" matrix: 0 if JI <= threshold, 1 otherwise
+            pass_fail_df = (ji_df > ji_thre).astype(int)
+            maxs = pass_fail_df.max(axis=0)
+            r_hier.loc[pass_fail_df.columns, 'robustness'] += np.array(maxs).astype(int)
+        r_hier['robustness'] /= len(alt_hiers)
+        for node_id, robustness in r_hier['robustness'].to_dict().items():
+            ref_hier.add_node_attribute(node_id, 'robustness', robustness)
+
+        return ref_hier
+
+    def compare_hierarchies(self, hierarchy_a=None, hierarchy_b=None):
+        """
+        Compare two hierarchies in CX2 format by calculating Jaccard overlaps and
+        assigning a 'robustness' (overlap) score to each node in the first hierarchy.
+
+        :param hierarchy_a: The first (reference) hierarchy to compare.
+        :type hierarchy_a: ndex2.cx2.CX2Network
+        :param hierarchy_b: The second (alternative) hierarchy to compare against.
+        :type hierarchy_b: ndex2.cx2.CX2Network
+        :return: The first hierarchy with an added 'robustness' node attribute.
+        :rtype: ndex2.cx2.CX2Network
+        """
+        ji_df = self._hierarchy_overlap(hierarchy_a, hierarchy_b)
+        maxs = ji_df.max(axis=0)
+        node_overlap_scores = maxs.to_dict()
+
+        # Add nodes annotate nodes in hierarchy_a robustness scores
+        for node_id, data in hierarchy_a.get_nodes().items():
+            score = node_overlap_scores.get(node_id, 0)
+            hierarchy_a.add_node_attribute(node_id, 'robustness', score)
+
+        return hierarchy_a
+
+    def compare_hierarchies_from_files(self, hierarchy_a_path=None, hierarchy_b_path=None):
+        """
+        Compare two hierarchies from files then calculating overlap-based scores.
+
+        :param hierarchy_a_path: Path to the first (reference) hierarchy file.
+        :type hierarchy_a_path: str
+        :param hierarchy_b_path: Path to the second (alternative) hierarchy file.
+        :type hierarchy_b_path: str
+        :return: The first hierarchy (from hierarchy_a_path) with added robustness scores.
+        :rtype: ndex2.cx2.CX2Network
+        """
+        factory = RawCX2NetworkFactory()
+        hierarchy_a = factory.get_cx2network(hierarchy_a_path)
+        hierarchy_b = factory.get_cx2network(hierarchy_b_path)
+        return self.compare_hierarchies(hierarchy_a, hierarchy_b)

{cellmaps_utils-0.6.0 → cellmaps_utils-0.7.0}/cellmaps_utils.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: cellmaps_utils
-Version: 0.6.0
+Version: 0.7.0
 Summary: Contains utilities needed by Cell Maps tools
 Home-page: https://github.com/idekerlab/cellmaps_utils
 Author: Cell Maps team
@@ -145,6 +145,13 @@ This package was created with Cookiecutter_ and the `audreyr/cookiecutter-pypack
 History
 =======
 
+0.7.0 (2025-03-05)
+------------------
+
+* Add ``compute_hierarchy_robustness`` method to ``HierarchyDiff`` class to assess the robustness of a hierarchy
+  based on Jaccard similarity across multiple alternative hierarchies.
+
+
 0.6.0 (2025-02-05)
 ------------------
 

{cellmaps_utils-0.6.0 → cellmaps_utils-0.7.0}/cellmaps_utils.egg-info/SOURCES.txt

@@ -35,11 +35,18 @@ cellmaps_utils.egg-info/top_level.txt
 docs/Makefile
 docs/authors.rst
 docs/cellmaps_utils.rst
+docs/cm4ai_data_release.rst
 docs/conf.py
 docs/contributing.rst
+docs/cx2_to_hcx_conversion.rst
+docs/ddot_converters.rst
 docs/devbranches.rst
 docs/developer.rst
+docs/hidef_converters.rst
+docs/hierarchical_networks.rst
+docs/hierarchy_robustness.rst
 docs/history.rst
+docs/in_project.rst
 docs/index.rst
 docs/installation.rst
 docs/integrationtesting.rst
@@ -48,6 +55,7 @@ docs/modules.rst
 docs/newrelease.rst
 docs/outputs.rst
 docs/pypircfile.rst
+docs/upload_to_ndex.rst
 docs/usage.rst
 docs/versioningscheme.rst
 docs/_build/html/_static/file.png

cellmaps_utils-0.7.0/docs/cm4ai_data_release.rst

@@ -0,0 +1,273 @@
+Cell Maps for AI Data Release
+------------------------------
+
+This section describes how to generate a new `CM4AI`_ data release. The
+intended audience is for data generation sites and anyone interested in knowing
+how the datasets on `CM4AI`_ site are created.
+
+There are four steps to the data release:
+
+1) Each individual dataset must be run through ``cellmaps_utilscmd.py XX``
+   command to generate `RO-Crate`_ directories.
+
+2) These `RO-Crate`_ directories must be compressed
+
+3) ``cellmaps_utilscmd.py rocratetable`` must be given these compressed `RO-Crate`_ files to generate table
+
+4) Compressed `RO-Crate`_ files must be uploaded to `CM4AI`_
+
+5) The table generated must be sent to admin of `CM4AI`_ site so they can load it and
+   display the new data release
+
+
+1) Perturbation/CRISPR data release (step 1 above)
+===================================================
+
+The command line tool ``cellmaps_utilscmd.py crisprconverter`` takes a  `h5ad`_ file
+and copies that file along with other meta data files into a `RO-Crate`_ suitable
+for persistance to `FAIRSCAPE`_ and ultimately publication on `CM4AI`_
+
+The example below generates a `RO-Crate`_ directory under the ``0.1alpha`` folder using
+`h5ad`_ file named ``foo.h5ad`` passed in via the ``--h5ad`` flag
+
+.. code-block::
+
+    echo "completely fake h5ad file" > foo.h5ad
+
+    cellmaps_utilscmd.py -vv crisprconverter 0.1alpha --h5ad foo.h5ad --author 'Mali Lab' \
+                         --name 'CRISPR' --organization_name 'Mali Lab' \
+                         --project_name CM4AI --release '0.1 alpha' --treatment untreated \
+                         --dataset 4channel --cell_line KOLF2.1J --gene_set chromatin \
+                         --tissue undifferentiated --num_perturb_guides 6 \
+                         --num_non_target_ctrls 109 --num_screen_targets 108
+
+
+Example contents generated by above command:
+
+.. code-block::
+
+    0.1alpha/
+    └── cm4ai_chromatin_kolf2.1j_undifferentiated_untreated_crispr_4channel_0.1_alpha
+        ├── perturbation.h5ad
+        ├── dataset_info.json
+        ├── readme.txt
+        └── ro-crate-metadata.json
+
+.. note::
+
+    Invoke ``cellmaps_utilscmd.py crisperconverter -h`` for usage information
+
+.. warning::
+
+    This tool does not currently validate .h5ad, but when it does the above example
+    will fail
+
+1) Affinity Purification Mass Spectrometry (AP-MS) data release
+============================================================================
+
+The command line tool ``cellmaps_utilscmd.py apmsconverter`` consumes one or more `tsv`_ files
+that are combined and stored into a `RO-Crate`_ suitable
+for persistance to `FAIRSCAPE`_ and ultimately publication on `CM4AI`_
+
+The example below generates a `RO-Crate`_ directory under the ``0.1alpha`` folder using
+`tsv`_ file named ``DNMT3A.tsv`` that is passed in via the ``--inputs`` flag
+
+
+.. code-block::
+
+    echo -ne 'Bait\tPrey\tPreyGene.x\tSpec\tSpecSum\tAvgSpec\tNumReplicates.x\t' > DNMT3A.tsv
+    echo -ne 'ctrlCounts\tAvgP.x\tMaxP.x\tTopoAvgP.x\tTopoMaxP.x\tSaintScore.x\t' >> DNMT3A.tsv
+    echo -e 'logOddsScore\tFoldChange.x\tBFDR.x\tboosted_by.x' >> DNMT3A.tsv
+    echo -ne 'DNMT3A\tO00422\tSAP18_HUMAN\t6|7|8|10\t31\t7.75\t4\t0|0|0|0|0|0|0|0\t' >> DNMT3A.tsv
+    echo -e '1\t1\t1\t1\t1\t13.51\t77.5\t0\tNA' >> DNMT3A.tsv
+    echo -ne 'DNMT3A\tO00571\tDDX3X_HUMAN\t3|7|11|9\t30\t7.5\t4\t0|1|3|3|0|0|0|0\t' >> DNMT3A.tsv
+    echo -e '0.99\t1\t0.99\t1\t0.99\t3.63\t8.57\t0\tNA' >> DNMT3A.tsv
+
+    cellmaps_utilscmd.py apmsconverter 0.1alpha --inputs DNMT3A.tsv \
+                         --author 'Krogan Lab' --name 'AP-MS' \
+                         --organization_name 'Krogan Lab' --project_name 'CM4AI' \
+                         --release '0.1 alpha' --treatment untreated \
+                         --cell_line 'MDA-MB-468' --gene_set 'chromatin'
+
+Example contents generated by above command:
+
+.. code-block::
+
+    0.1alpha/
+    └── cm4ai_chromatin_mda-mb-468_untreated_apms_0.1_alpha
+        ├── apms.tsv
+        ├── dataset_info.json
+        ├── readme.txt
+        └── ro-crate-metadata.json
+
+.. note::
+
+    Invoke ``cellmaps_utilscmd.py apmsconverter -h`` for usage information
+
+
+1) Size Exclusion Chromatography with Mass Spectrometry (SEC-MS) data release
+==========================================================================================
+
+TODO
+
+
+1) Immunofluorescent Image (IFImage) data release
+==================================================================
+
+The command line tool ``cellmaps_utilscmd.py ifconverter`` consumes a  `csv`_ file
+that contains image links and other information to download and stored into a `RO-Crate`_ suitable
+for persistance to `FAIRSCAPE`_ and ultimately publication on `CM4AI`_
+
+The example below generates a `RO-Crate`_ directory under the ``0.1alpha`` folder using
+`csv`_ file named ``example.csv`` that is passed in via the ``--inputs`` flag
+
+
+.. code-block::
+
+    # be sure to download this file: https://github.com/idekerlab/cellmaps_utils/raw/main/examples/iftool/example.csv
+    # and name it example.csv
+    wget https://github.com/idekerlab/cellmaps_utils/raw/main/examples/iftool/example.csv
+
+    cellmaps_utilscmd.py ifconverter 0.1alpha --input example.csv \
+                         --author 'Lundberg Lab' --name 'IF images' \
+                         --organization_name 'Lundberg Lab' --project_name 'CM4AI' \
+                         --release '0.1 alpha' --treatment paclitaxel \
+                         --cell_line 'MDA-MB-468' --gene_set 'chromatin'
+
+Example contents generated by above command:
+
+.. code-block::
+
+    0.1alpha/
+    └── cm4ai_chromatin_mda-mb-468_paclitaxel_ifimage_0.1_alpha
+        ├── antibody_gene_table.tsv
+        ├── blue
+        │   └── B2AI_1_Paclitaxel_C1_R1_z01_blue.jpg
+        ├── dataset_info.json
+        ├── green
+        │   └── B2AI_1_Paclitaxel_C1_R1_z01_green.jpg
+        ├── readme.txt
+        ├── red
+        │   └── B2AI_1_Paclitaxel_C1_R1_z01_red.jpg
+        ├── ro-crate-metadata.json
+        └── yellow
+            └── B2AI_1_Paclitaxel_C1_R1_z01_yellow.jpg
+
+.. note::
+
+    Invoke ``cellmaps_utilscmd.py ifconverter -h`` for usage information
+
+2) Compress `RO-Crate`_ from step one
+=========================================
+
+In this step the `RO-Crate`_ directories are compressed into files.
+
+.. note::
+
+    The code fragment below assumes all `RO-Crate`_ directories were put into ``0.1alpha``
+    directory.
+
+.. code-block::
+
+    # assuming all RO-Crates above were put into 0.1alpha directory
+    cd 0.1alpha
+
+    for Y in `find . -name "*_*" -maxdepth 1 -type d` ; do
+      echo $Y
+      tar -cz $Y > ${Y}.tar.gz
+    done
+
+If examples above were run then the ``0.1alpha`` directory will look like this:
+
+.. code-block::
+
+    .
+    ├── cm4ai_chromatin_kolf2.1j_undifferentiated_untreated_crispr_4channel_0.1_alpha
+    ├── cm4ai_chromatin_kolf2.1j_undifferentiated_untreated_crispr_4channel_0.1_alpha.tar.gz
+    ├── cm4ai_chromatin_mda-mb-468_paclitaxel_ifimage_0.1_alpha
+    ├── cm4ai_chromatin_mda-mb-468_paclitaxel_ifimage_0.1_alpha.tar.gz
+    ├── cm4ai_chromatin_mda-mb-468_untreated_apms_0.1_alpha
+    └── cm4ai_chromatin_mda-mb-468_untreated_apms_0.1_alpha.tar.gz
+
+3) Run ``cellmaps_utilscmd.py rocratetable`` on `RO-Crate`_ files
+===================================================================
+
+In this step, the `RO-Crate`_ files are examined and a table is generated
+that can be sent to the `CM4AI`_ site admin to show the new data release
+
+.. note::
+
+    The code fragment below assumes all `RO-Crate`_ directories were put into ``0.1alpha``
+    directory.
+
+.. code-block::
+
+    # assuming all RO-Crates above were put into 0.1alpha directory
+    # along with gzip files
+
+    cd 0.1alpha
+
+    cellmaps_utilscmd.py rocratetable table --downloadurlprefix 'https://cm4ai.org/Data/' --rocrates `/bin/ls | grep -v ".gz"`
+
+
+The above command will create a directory named ``table`` and within that directory
+will be a `tsv`_ file named ``data.tsv``
+
+.. code-block::
+
+    table
+    └── data.tsv
+
+
+Contents of `tsv`_ ``data.tsv`` file:
+
+.. code-block::
+
+    FAIRSCAPE ARK ID	Date	Version	Type	Cell Line	Tissue	Treatment	Gene set	Generated By Software	Name	Description	KeywordDownload RO-Crate Data Package	Download RO-Crate Data Package Size MB	Generated By Software	Output Dataset	Responsible Lab
+    d4d80b1d-8d49-4204-8c0d-209c5b9ccdf2:cm4ai_chromatin_kolf2.1j_undifferentiated_untreated_crispr_4channel_0.1_alpha	2024-04-29	0.1 alpha	Data	KOLF2.1J	undifferentiated	untreated	chromatin		CRISPR	CM4AI 0.1 alpha KOLF2.1J untreated CRISPR undifferentiated 4channel chromatin	CM4AI,0.1 alpha,KOLF2.1J,untreated,CRISPR,undifferentiated,4channel,chromatin	https://cm4ai.org/Data/cm4ai_chromatin_kolf2.1j_undifferentiated_untreated_crispr_4channel_0.1_alpha.tar.gz	1	Mali Lab
+    134e01c8-90ea-457d-9e6e-ca046ecc860f:cm4ai_chromatin_mda-mb-468_paclitaxel_ifimage_0.1_alpha	2024-04-29	0.1 alpha	Data	MDA-MB-468	breast; mammary gland	paclitaxel	chromatin		IF images	CM4AI 0.1 alpha MDA-MB-468 paclitaxel IF microscopy images breast; mammary gland chromatin	CM4AI,0.1 alpha,MDA-MB-468,paclitaxel,IF microscopy,images,breast; mammary gland,chromatin	https://cm4ai.org/Data/cm4ai_chromatin_mda-mb-468_paclitaxel_ifimage_0.1_alpha.tar.gz	1	Lundberg Lab
+    7240c7d7-327c-423c-834d-1e99ab8a417b:cm4ai_chromatin_mda-mb-468_untreated_apms_0.1_alpha	2024-04-29	0.1 alpha	Data	MDA-MB-468	breast; mammary gland	untreated	chromatin		AP-MS	CM4AI 0.1 alpha MDA-MB-468 untreated breast; mammary gland AP-MS edgelist chromatin	CM4AI,0.1 alpha,MDA-MB-468,untreated,breast; mammary gland,AP-MS edgelist,chromatin	https://cm4ai.org/Data/cm4ai_chromatin_mda-mb-468_untreated_apms_0.1_alpha.tar.gz	1			Krogan Lab
+
+.. note::
+
+    ``cellmaps_utilscmd.py rocratetable`` runs way faster if the uncompressed
+    `RO-Crate`_ directories are passed in. The script does need the ``.gz``
+    files in the same directory to get file sizes output in the generated
+    table.
+
+
+4) Upload `RO-Crate`_ files
+=============================
+
+For this step the `RO-Crate`_ files ending with ``.gz`` should be uploaded to path matching
+prefix set via ``--downloadurlprefix`` in Step 3
+
+.. note::
+
+    Be sure to verify URLs resolve for uploaded files
+
+
+
+5) Send table from Step 4 to admin of `CM4AI`_ site
+======================================================
+
+In this step send the ``table/data.tsv`` file to `CM4AI`_ admin
+and let them know if this table is to append or overwrite existing
+data
+
+
+.. _CM4AI: https://cm4ai.org
+.. _RO-Crate: https://www.researchobject.org/ro-crate
+.. _FAIRSCAPE CLI: https://fairscape.github.io/fairscape-cli
+.. _FAIRSCAPE: https://fairscape.github.io
+.. _software: https://fairscape.github.io/fairscape-cli/getting-started/#register-software-metadata
+.. _dataset: https://fairscape.github.io/fairscape-cli/getting-started/#register-dataset-metadata
+.. _computation: https://fairscape.github.io/fairscape-cli/getting-started/#register-computation-metadata
+.. _tar: https://en.wikipedia.org/wiki/Tar_(computing)
+.. _gzip: https://en.wikipedia.org/wiki/Gzip
+.. _h5ad: https://github.com/scverse/anndata/issues/180
+.. _tsv: https://en.wikipedia.org/wiki/Tab-separated_values
+.. _csv: https://en.wikipedia.org/wiki/Comma-separated_values
+.. _CX2: https://cytoscape.org/cx/cx2/specification/cytoscape-exchange-format-specification-(version-2)
+.. _HCX: https://cytoscape.org/cx/cx2/hcx-specification
+.. _Reference: https://cellmaps-utils.readthedocs.io/en/latest/cellmaps_utils.html#cellmaps-utils-hierdiff-hierarchy-comparison-module

cellmaps_utils-0.7.0/docs/cx2_to_hcx_conversion.rst

@@ -0,0 +1,84 @@
+CX2 to HCX conversion
+=========================
+
+The CX2 to HCX conversion process enhances a CX2 hierarchical network by adding HCX-specific annotations.
+The HCX format is a specialized version of CX2 that enables hierarchical visualization in Cytoscape,
+ensuring that relationships and interactome information are properly structured.
+
+Why Convert to HCX?
+
+- Enables hierarchical network visualization in Cytoscape.
+- Adds interactome annotations to define relationships.
+- Supports integration with NDEx, allowing retrieval of interactome data.
+
+**Example 1: Converting a CX2 Hierarchical Network to HCX**
+
+To convert a CX2 hierarchical network into an HCX format, use the ``convert_hierarchical_network_to_hcx`` function:
+
+.. code-block::
+
+    from cellmaps_utils.hcx_utils import convert_hierarchical_network_to_hcx
+
+    hierarchy_path = "path/to/hierarchy.cx2"
+    interactome_url = "https://www.ndexbio.org/network/uuid"
+
+    hcx_network = convert_hierarchical_network_to_hcx(
+        hierarchy=hierarchy_path,
+        interactome_url=interactome_url
+    )
+
+    hcx_network.write_as_raw_cx2("path/to/output/hierarchy_hcx.cx2")
+
+Expected Output: ``hierarchy_hcx.cx2`` – The HCX hierarchical network, enriched with interactome annotations.
+
+.. _Example 2:
+
+**Example 2: Converting a CX2 Hierarchy with a Local Interactome**
+
+If you have a local interactome file instead of an NDEx link, you can still convert a CX2 hierarchy to HCX:
+
+.. code-block::
+
+    from ndex2.cx2 import RawCX2NetworkFactory
+    from cellmaps_utils.hcx_utils import add_hcx_network_annotations, add_hcx_members_annotation, add_isroot_node_attribute, get_root_nodes
+
+    hierarchy_path = "path/to/hierarchy.cx2"
+    interactome_path = "path/to/interactome.cx2"
+
+    # Load hierarchy network and interactome
+    factory = RawCX2NetworkFactory()
+    hierarchy = factory.get_cx2network(hierarchy_path)
+    interactome = factory.get_cx2network(interactome_path)
+
+    # Add HCX annotations
+    hierarchy = add_hcx_network_annotations(hierarchy, interactome=interactome, outdir='path/to/output/')
+
+    # Add HCX::members attribute to node attributes
+    add_hcx_members_annotation(hierarchy, interactome)
+
+    # Add isRoot attribute to node attributes
+    add_isroot_node_attribute(hierarchy, get_root_nodes(hierarchy))
+
+    # Save HCX file
+    hierarchy.write_as_raw_cx2("path/to/output/hierarchy.cx2")
+
+Expected Output (Hierarchy and interactome will be saved in the same directory ``path/to/output/``):
+
+- ``hierarchy_hcx.cx2`` – HCX hierarchical network with interactome annotations.
+- ``hierarchy_parent.cx2``
+
+.. _CM4AI: https://cm4ai.org
+.. _RO-Crate: https://www.researchobject.org/ro-crate
+.. _FAIRSCAPE CLI: https://fairscape.github.io/fairscape-cli
+.. _FAIRSCAPE: https://fairscape.github.io
+.. _software: https://fairscape.github.io/fairscape-cli/getting-started/#register-software-metadata
+.. _dataset: https://fairscape.github.io/fairscape-cli/getting-started/#register-dataset-metadata
+.. _computation: https://fairscape.github.io/fairscape-cli/getting-started/#register-computation-metadata
+.. _tar: https://en.wikipedia.org/wiki/Tar_(computing)
+.. _gzip: https://en.wikipedia.org/wiki/Gzip
+.. _h5ad: https://github.com/scverse/anndata/issues/180
+.. _tsv: https://en.wikipedia.org/wiki/Tab-separated_values
+.. _csv: https://en.wikipedia.org/wiki/Comma-separated_values
+.. _CX2: https://cytoscape.org/cx/cx2/specification/cytoscape-exchange-format-specification-(version-2)
+.. _HCX: https://cytoscape.org/cx/cx2/hcx-specification
+.. _Reference: https://cellmaps-utils.readthedocs.io/en/latest/cellmaps_utils.html#cellmaps-utils-hierdiff-hierarchy-comparison-module