===========================================
FineST: Fine-grained Spatial Transcriptomic
===========================================


A tatistical model and toolbox to identify the super-resolved ligand-receptor interaction 
with spatial co-expression (i.e., spatial association). 
Uniquely, FineST can distinguish co-expressed ligand-receptor pairs (LR pairs) 
from spatially separating pairs at sub-spot level or single-cell level, 
and identify the super-resolved ligand-receptor interaction (LRI).

.. image:: https://github.com/LingyuLi-math/FineST/blob/main/docs/fig/FineST_framework_all.png?raw=true
   :width: 800px
   :align: center

It comprises three components (*Training*-*Imputation*-*Discovery*) after HE image feature is extracted: 

* Step0: HE image feature extraction
* Step1: **Training** FineST on the within spots
* Step2: Super-resolution spatial RNA-seq **imputation**
* Step3: Fine-grained LR pair and CCC pattern **discovery**

.. It comprises two main steps:

.. 1. global selection `spatialdm_global` to identify significantly interacting LR pairs;
.. 2. local selection `spatialdm_local` to identify local spots for each interaction.

Installation
============

FineST is available through `PyPI <https://pypi.org/project/FineST/>`_.
To install, type the following command line and add ``-U`` for updates:

.. code-block:: bash

   pip install -U FineST

Alternatively, install from this GitHub repository for latest (often
development) version (time: < 1 min):

.. code-block:: bash

   pip install -U git+https://github.com/LingyuLi-math/FineST

Installation using Conda
========================

.. code-block:: bash

   $ git clone https://github.com/LingyuLi-math/FineST.git
   $ conda create --name FineST python=3.8
   $ conda activate FineST
   $ cd FineST
   $ pip install -r requirements.txt

Typically installation is completed within a few minutes. 
Then install pytorch, refer to `pytorch installation <https://pytorch.org/get-started/locally/>`_.

.. code-block:: bash

   $ conda install pytorch=1.7.1 torchvision torchaudio cudatoolkit=11.0 -c pytorch

Verify the installation using the following command:

.. code-block:: bash

   python
   >>> import torch
   >>> print(torch.__version__)
   >>> print(torch.cuda.is_available())


Get Started for Visium HD data
==============================

Illustrate using a single slice of 10x Visium HD human colorectal cancer 
(CRC) data with 16-um bin.


Step0: HE image feature extraction
----------------------------------

**Input**

* ``Visium_HD_Human_Colon_Cancer_tissue_image.btf``: Raw histology image (.btf *Visium HD* or .tif *Visium*)
* ``tissue_positions.parquet``: Spot/bin locations (.parquet *Visium HD* or .csv *Visium*)

**Output**

* ``HD_CRC_16um_pth_32_16_image``: Segmeted histology image patches (.png)
* ``HD_CRC_16um_pth_32_16``: Extracted image feature embeddiings for each patche (.pth)

.. code-block:: bash

   python .FineST/HIPT_image_feature_extract.py --dataset HD_CRC_16um --position ./Colon_Cancer/square_016um/spatial/tissue_positions.parquet --image ./Colon_Cancer/Visium_HD_Human_Colon_Cancer_tissue_image.btf --output_path_img ./HD_CRC_16um_pth_32_16_image --output_path_pth ./HD_CRC_16um_pth_32_16 --patch_size 32 --logging_folder ./Finetune/HIPT_image_feature_extract/

``HIPT_image_feature_extract.py`` also output the execution time:

* The image segment execution time for the loop is: 62.491 seconds
* The image feature extract time for the loop is: 1717.818 seconds


Step1: Training FineST on the within spots
------------------------------------------


Step2: Super-resolution spatial RNA-seq imputation
--------------------------------------------------


Step3: Fine-grained LR pair and CCC pattern discovery
-----------------------------------------------------



.. Quick example
.. =============

.. Using the build-in NPC dataset as an example, the following Python script
.. will predict super-resolution ST gene expression and compute the p-value indicating whether a certain Ligand-Receptor is
.. spatially co-expressed. 

Detailed Manual
===============

The full manual is at `finest-rtd-tutorial <https://finest-rtd-tutorial.readthedocs.io>`_ for installation, tutorials and examples. 

* `Sub-spot level prediction by FineST (For Visium dataset)`_.

* `Super-resolved ligand-receptor interavtion discovery by FineST`_.

.. _Sub-spot level prediction by FineST (For Visium dataset): docs/source/NPC_Train_Impute.ipynb

.. _Super-resolved ligand-receptor interavtion discovery by FineST: docs/source/NPC_LRI_CCC.ipynb