Getting Started
===============

Installation
------------

1. Clone the repository:

   .. code-block:: bash

       git clone <repo-url>
       cd proteINET

2. Create and activate the conda environment:

   .. code-block:: bash

       conda env create -f environment.yml
       conda activate proteINET

If not using conda, install the pip packages listed in ``environment.yml``.


Basic Workflow
--------------

The typical workflow involves three steps:

1. **Fetch data from STRING**
2. **Build network and compute metrics**
3. **Generate reports and visualizations**


Fetching Data from STRING
~~~~~~~~~~~~~~~~~~~~~~~~~~

Use :class:`graph.StringLoader.StringLoader` to query the STRING API:

.. code-block:: python

    from graph.StringLoader import StringLoader

    loader = StringLoader(
        protein_query=["TP53", "BRCA1", "EGFR"],
        species=9606,  # Human
        add_nodes=20,
        required_score=400
    )

    # Retrieve and standardize data
    data = (
        loader
        .retrieve_data()
        .standardize_data_format()
        .get_data()
    )

    print(data["nodes"].head())
    print(data["edges"].head())


Building a Network
~~~~~~~~~~~~~~~~~~

Use :class:`graph.PPINetwork.PPINetwork` to construct and analyze the network:

.. code-block:: python

    from graph.PPINetwork import PPINetwork

    ppin = PPINetwork(data=data)

    # Compute network metrics
    ppin.compute_all_global_metrics(weighted=False)
    ppin.compute_all_node_metrics(weighted=False)
    ppin.compute_all_edge_metrics(weighted=False)

    # Access computed metrics
    print(ppin.graph_metrics)
    print(ppin.node_metrics_df.head())


Exporting for Cytoscape
~~~~~~~~~~~~~~~~~~~~~~~

Export the network for use in Cytoscape:

.. code-block:: python

    exported_files = ppin.export_for_cytoscape(
        output_dir="cytoscape_export",
        basename="ppi_network_TP53-BRCA1"
    )

    for file_type, path in exported_files.items():
        print(f"{file_type}: {path}")


Generating Interactive HTML Reports
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Use :class:`visual.ReportGenerator.ReportGenerator` to create an interactive report:

.. code-block:: python

    from visual.ReportGenerator import ReportGenerator

    ReportGenerator().add_cytoscape_html_report(
        ppin,
        title="STRING Protein Network",
        node_color_attr="pagerank",
        node_size_attr="degree"
    ).generate_report_file("protein_network_report.html")


Running Enrichment Analysis (GSEA)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Compute gene set enrichment on ranked proteins:

.. code-block:: python

    ranked_genes, gsea_results = ppin.run_gsea(
        node_attribute="degree_centrality",
        gene_sets="GO_Biological_Process_2023",
        outdir="gsea_results"
    )

    print(gsea_results.head(10))


Example: Complete Pipeline
---------------------------

See ``main.py`` for a complete example that ties all components together:

.. code-block:: bash

    python main.py

This runs a full pipeline that:

1. Queries STRING for a set of proteins
2. Builds the PPI network
3. Computes metrics
4. Runs GSEA enrichment
5. Exports Cytoscape-ready files
6. Generates an interactive HTML report


Troubleshooting
---------------

**Network timeout errors:**
  Increase the ``timeout`` parameter in StringLoader:

  .. code-block:: python

      loader = StringLoader(..., timeout=60)

**No identifiers found:**
  Ensure input protein names are correct. STRING accepts:
  - Gene names (e.g., "TP53")
  - UniProt IDs
  - Ensembl IDs

**Large networks are slow:**
  Reduce the number of additional nodes or filter by ``required_score``:

  .. code-block:: python

      loader = StringLoader(..., add_nodes=5, required_score=800)