=======
Inputs
=======

The tools can handle inputs in both CX_ and CX2_ format. Please refer to respective documentations for the details
how to create CX_ and CX2_ files, or use ndex2-client_ python package.

- ``HIERARCHY directory``
    A RO-Crate generated by ``cellmaps_generate_hierarchy`` or directory with similar structure,
    containing all necessary files:

    - ``hierarchy.cx`` or  ``hierarchy.cx2``
        Network hierarchy in CX_ or CX2_ (HCX_) format.

        .. code-block:: json

            [
              {
                "CXVersion": "1.0",
                "hasFragments": false
              },
              {
                "metaData": [
                  {
                    "elementCount": 1,
                    "name": "attributeDeclarations"
                  },
                  {
                    "elementCount": 1,
                    "name": "networkAttributes"
                  },
                  {
                    "elementCount": 3,
                    "name": "nodes"
                  },
                  {
                    "elementCount": 2,
                    "name": "edges"
                  }
                ]
              },
              {
                "attributeDeclarations": [removed for readability of the example]
              },
              {
                "networkAttributes": [
                  {
                    "name": "Sample Network",
                    "description": "This is a sample network for demonstration."
                    "ndexSchema": "hierarchy_v0.1",
                    "HCX::modelFileCount": 2,
                    "HCX::interactionNetworkName": "hierarchy_parent.cx2"
                  }
                ]
              },
              {
                "nodes": [
                  {
                    "id": 0,
                    "v": {
                      "name": "Node1",
                      "represents": "Data1"
                      "HCX::isRoot": true,
                      "HCX::members": [
                        0,
                        1,
                        2]
                    }
                  },
                  {
                    "id": 1,
                    "v": {
                      "name": "Node2",
                      "represents": "Data2"
                      "HCX::isRoot": false,
                      "HCX::members": [
                        1]
                    }
                  },
                  {
                    "id": 2,
                    "v": {
                      "name": "Node3",
                      "represents": "Data3"
                      "HCX::isRoot": true,
                      "HCX::members": [
                        2]
                    }
                  }
                ]
              },
              {
                "edges": [
                  {
                    "id": 0,
                    "s": 0,
                    "t": 1
                  },
                  {
                    "id": 1,
                    "s": 0,
                    "t": 2
                  }
                ]
              },
              {
                "status": [
                  {
                    "error": "",
                    "success": true
                  }
                ]
              }
            ]

        - ``hierarchy_parent.cx2``:
            The parent or primary network used as a reference for generating the hierarchy in CX_ or CX2_ format.

        .. code-block:: json

            [
                {
                    "CXVersion": "2.0",
                    "hasFragments": false
                },
                {
                    "metaData": [
                        {"elementCount": 1, "name": "attributeDeclarations"},
                        {"elementCount": 1, "name": "networkAttributes"},
                        {"elementCount": 3, "name": "nodes"},
                        {"elementCount": 2, "name": "edges"}
                    ]
                },
                {
                    "attributeDeclarations": [
                        {
                            "networkAttributes": {"name": {"d": "string"}, "description": {"d": "string"}},
                            "nodes": {"name": {"a": "n", "d": "string"}, "represents": {"a": "r", "d": "string"}},
                            "edges": {"interaction": {"a": "i", "d": "string"}, "Weight": {"d": "double"}}
                        }
                    ]
                },
                {
                    "networkAttributes": [
                        {"name": "Example PPI Network", "description": "Simplified Protein-Protein Interaction network example"}
                    ]
                },
                {
                    "nodes": [
                        {"id": 0, "v": {"n": "ProteinA", "r": "ProteinA"}},
                        {"id": 1, "v": {"n": "ProteinB", "r": "ProteinB"}},
                        {"id": 2, "v": {"n": "ProteinC", "r": "ProteinC"}}
                    ]
                },
                {
                    "edges": [
                        {"id": 0, "s": 0, "t": 1, "v": {"Weight": 0.5, "i": "interacts-with"}},
                        {"id": 1, "s": 0, "t": 2, "v": {"Weight": 0.6, "i": "interacts-with"}},
                    ]
                }
            ]

    - ``ro-crate-metadata.json``:
        Metadata in RO-Crate_ format, a community effort to establish a lightweight approach to packaging research data with their metadata.

        It contains general information about the data i.a. ID, Type, Name, Description, contextual definitions,
        Software detail, as well as datasets details of each individual part of the data.

        For example, the metadata for the content of hierarchy.cx provides unique id, context, type, url, name, keywords, etc.
        The url can be used to view the hierarchy in Cytoscape_ Web.


.. _CX: https://cytoscape.org/cx/specification/cytoscape-exchange-format-specification-(version-1)
.. _CX2: https://cytoscape.org/cx/cx2/specification/cytoscape-exchange-format-specification-(version-2)
.. _HCX: https://cytoscape.org/cx/cx2/hcx-specification
.. _ndex2-client: https://ndex2.readthedocs.io/en/latest/index.html