CNNreg 0.1.0__py3-none-any.whl

CNNreg/__init__.py

@@ -0,0 +1,8 @@
+"""
+cnn_deconv: A CNN-based regression package for cell type deconvolution of bulk RNA-seq using scRNA-seq reference.
+"""
+from .data import data_CSE, flatten_list, divide_by_row_sum, reformat_ref
+from .layers import RefCombLayer, SliceSumLayer, CelltypeScaleLayer, StretchLayer, DeconvProp_S1
+from .losses import (loss_spearmanr, loss_prop, loss_ref, loss_scale, 
+                     loss_stretch, loss_epsilon_insensitive)
+from .train import trainProp

CNNreg/cli.py

@@ -0,0 +1,67 @@
+import argparse
+import torch
+import pandas as pd
+from .train import trainProp
+from .data import data_CSE, reformat_ref, divide_by_row_sum
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="CNN-based bulk RNA-seq deconvolution",
+        formatter_class=argparse.ArgumentDefaultsHelpFormatter
+    )
+    parser.add_argument("-M", dest="runMode", type=str, required=True, choices=['train', 'evaluate', 'predict', 'explain'])
+    parser.add_argument("-bulk", dest="bulk", type=str, required=False)
+    parser.add_argument("-ref", dest="reference", type=str, required=False)
+    parser.add_argument("-pre", dest="prefix", type=str, default="Project")
+    parser.add_argument("-o", dest="outDIR", type=str, required=True)
+    parser.add_argument("-mP", dest="modelFile", type=str)
+    parser.add_argument("-C", dest="kernelSize", type=int, default=10)
+    parser.add_argument("-EP", dest="maxEpochCellProp", type=int, default=1000)
+
+    args = parser.parse_args()
+
+    device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
+    
+    # Set default model file path if not provided
+    model_file = args.modelFile if args.modelFile else f"{args.outDIR}/cellprop_model.pt"
+    
+    paraHash = {
+        "runMode": args.runMode,
+        "bulk": args.bulk,
+        "reference": args.reference,
+        "data_out_dir": args.outDIR,
+        "max_epoch_cellprop": args.maxEpochCellProp,
+        "model_file": model_file,
+        "prefix": args.prefix,
+        "device": device,
+        "n_kernel": args.kernelSize
+    }
+
+    if paraHash["runMode"] == "train":
+        df_bulk = pd.read_csv(paraHash["bulk"])
+        dataHash = {
+            "bulk": torch.tensor(df_bulk.iloc[:,1:].values.transpose(), dtype=torch.float32).to(device),
+            "sample": df_bulk.columns.values[range(1, df_bulk.shape[1])],
+            "celltype": [f"celltype_{i+1}" for i in range(paraHash["n_kernel"])],
+            "CSE": data_CSE(paraHash["reference"], device=device)
+        }
+        paraHash["n_gene"] = df_bulk.shape[0]
+        paraHash["n_sample"] = df_bulk.shape[1]-1
+        paraHash["n_celltype"] = paraHash["n_kernel"]
+        paraHash["n_ref"] = dataHash["CSE"].expr_cse.shape[0]
+        
+        # Initialize index arrays for celltype and reference features
+        k = paraHash["n_gene"] * paraHash["n_celltype"]
+        dataHash["idx_feature_celltype"] = []
+        for x in range(paraHash["n_celltype"]):
+            dataHash["idx_feature_celltype"].append([int(y+x) for y in range(0, k, paraHash["n_celltype"])])
+        
+        dataHash["idx_feature_ref"] = []
+        for x in range(paraHash["n_ref"]):
+            dataHash["idx_feature_ref"].append([y for y in range(x*k, (x+1)*k)])
+        
+        dataHash["CSE_reformat"] = reformat_ref(dataHash["CSE"].expr_cse)
+        trainProp(dataHash, paraHash)
+
+if __name__ == "__main__":
+    main()

CNNreg/data.py

@@ -0,0 +1,43 @@
+import torch
+import pandas as pd
+import numpy as np
+
+def flatten_list(nested_list):
+    """Flatten a nested list recursively."""
+    flattened_list = []
+    for item in nested_list:
+        if isinstance(item, list):
+            flattened_list.extend(flatten_list(item))
+        else:
+            flattened_list.append(item)
+    return flattened_list
+
+def divide_by_row_sum(array):
+    """Normalize rows to sum to 1."""
+    row_sums = np.sum(array, axis=1, keepdims=True)
+    return array / row_sums
+
+def reformat_ref(CSE_data):
+    """Flatten the reference CSE tensor."""
+    return torch.flatten(torch.t(CSE_data), start_dim=0)
+
+class data_CSE(torch.utils.data.Dataset):
+    """Dataset wrapper for Cell Type Specific Expression (CSE)."""
+    def __init__(self, f_CSE, device):
+        super().__init__()
+        df_cse = pd.read_csv(f_CSE)
+        sample = df_cse.iloc[:,0]
+        expr_cse = df_cse.iloc[:,1:]
+        self.expr_cse = torch.tensor(expr_cse.values, dtype=torch.float32).to(device)
+        self.sample = sample
+
+    def __len__(self):
+        return self.expr_cse.shape[0]
+
+    def __getitem__(self, idx):
+        if torch.is_tensor(idx):
+            idx = idx.tolist()
+        return {'expr_cse': self.expr_cse[idx, :], 'sample': self.sample[idx]}
+
+    def update_data(self, new_CSE):
+        self.expr_cse = new_CSE

CNNreg/layers.py

@@ -0,0 +1,91 @@
+import torch
+import torch.nn as nn
+import numpy as np
+import torchsort
+
+class RefCombLayer(nn.Module):
+    """Reference combination layer for CNN deconvolution."""
+    def __init__(self, pHash, dHash, device=None):
+        super().__init__()
+        num = 1.0 / pHash["n_ref"]
+        w = torch.empty(pHash["n_ref"] * pHash["n_celltype"])
+        self.weight = nn.Parameter(torch.nn.init.uniform_(w, a=num-num/5, b=num+num/5).to(device))
+        self.w_expand = torch.flatten(self.weight.expand([pHash["n_gene"], len(w)]))
+
+    def forward(self, x):
+        return torch.mul(x, self.w_expand)
+
+
+class SliceSumLayer(nn.Module):
+    """Sum slices of the reference layer output."""
+    def __init__(self, pHash, dHash, device=None):
+        super().__init__()
+        self.slice_column = pHash["n_ref"]
+        self.slice_row = pHash["n_celltype"] * pHash["n_gene"]
+
+    def forward(self, x):
+        x = x.reshape(self.slice_row, self.slice_column)
+        return torch.sum(x, dim=1)
+
+
+class CelltypeScaleLayer(nn.Module):
+    """Scale expression for each cell type."""
+    def __init__(self, pHash, dHash, device=None):
+        super().__init__()
+        w = torch.empty(pHash["n_celltype"])
+        self.weight = nn.Parameter(torch.nn.init.normal_(w, 1.0, 0.1).to(device))
+        self.idx = dHash["idx_feature_celltype"]
+
+    def forward(self, x):
+        z = x[self.idx[0]] * self.weight[0]
+        for ii in range(1, len(self.idx)):
+            y = x[self.idx[ii]] * self.weight[ii]
+            z = torch.vstack((z,y))
+        return torch.flatten(torch.t(z))
+
+
+class StretchLayer(nn.Module):
+    """Stretch layer to scale features per gene."""
+    def __init__(self, pHash, dHash, device=None):
+        super().__init__()
+        w = torch.empty(pHash["n_gene"])
+        self.weight = nn.Parameter(torch.nn.init.normal_(w, 1.0, 0.1).to(device))
+        self.w_expand = torch.flatten(torch.t(self.weight.expand((pHash["n_celltype"], -1))))
+
+
+    def forward(self, x):
+        return torch.mul(x, self.w_expand)
+
+
+class DeconvProp_S1(nn.Module):
+    """Stage I CNN model for cell proportion estimation."""
+    
+    @staticmethod
+    def ini_kernel_weight(pHash):
+        """Initialize kernel weights for conv1 layer."""
+        ## (out_channels, in_channels, kernel_size)
+        arr = np.ones(pHash["n_celltype"])/pHash["n_celltype"]
+        arr = np.tile(arr, (pHash["n_sample"], 1, 1))
+        w = torch.empty((arr.shape[0], arr.shape[1], arr.shape[2]))
+        weights = torch.nn.init.normal_(w, 1.0/pHash["n_celltype"], 0.25*1.0/pHash["n_celltype"]).to(pHash["device"])
+        return nn.Parameter(weights)
+    
+    def __init__(self, dHash, pHash):
+        super().__init__()
+        k = pHash["n_gene"]*pHash["n_celltype"]
+        self.refLayer = RefCombLayer(pHash, dHash, device=pHash["device"])
+        self.sum = SliceSumLayer(pHash, dHash, device=pHash["device"])
+        self.celltypeScaleLayer = CelltypeScaleLayer(pHash, dHash, device=pHash["device"])
+        self.stretchLayer = StretchLayer(pHash, dHash, device=pHash["device"])
+        self.conv1 = nn.Conv1d(1, pHash["n_sample"], kernel_size=pHash["n_kernel"],
+                               stride=pHash["n_kernel"], device=pHash["device"], bias=False)
+        self.conv1.weight = self.ini_kernel_weight(pHash)
+
+    def forward(self, x, N_batch, N_feature):
+        y = self.refLayer(x)
+        y0 = self.sum(y)
+        y1 = self.celltypeScaleLayer(y0)
+        y2 = self.stretchLayer(y1)
+        y = y2.view(N_batch, 1, N_feature)
+        y = self.conv1(y).squeeze(0)
+        return y, y0, y1, y2

CNNreg/losses.py

@@ -0,0 +1,107 @@
+import torch
+import torchsort
+
+def spearmanr(pred, target, indx=None, **kw):
+    """Differentiable Spearman correlation using soft ranking."""
+    if len(pred.shape) == 1:
+        pred = pred.unsqueeze(0)
+    if len(target.shape) == 1:
+        target = target.unsqueeze(0)
+    if indx is not None:
+        pred = pred[:, indx]
+        target = target[:, indx]
+    pred_rank = torchsort.soft_rank(pred, **kw)
+    target_rank = torchsort.soft_rank(target, **kw)
+    pred_rank_center = pred_rank - pred_rank.mean(dim=-1, keepdim=True)
+    target_rank_center = target_rank - target_rank.mean(dim=-1, keepdim=True)
+    covariance = (pred_rank_center * target_rank_center).sum(dim=-1)
+    pred_std_rank = torch.sqrt((pred_rank_center ** 2).sum(dim=-1))
+    target_std_rank = torch.sqrt((target_rank_center ** 2).sum(dim=-1))
+    return covariance / (pred_std_rank * target_std_rank)
+
+def loss_spearmanr(pred, target, indx=None, **kw):
+    """Spearman correlation loss."""
+    return torch.mean(1 - spearmanr(pred, target, indx=indx))
+
+def loss_prop(model):
+    loss = 0.0
+    for param in model.conv1.parameters():
+        loss = loss + torch.sum(torch.abs(param[param < 0]))
+        #prop_sum = torch.sum(torch.squeeze(param,1),1) ## sum of cell proportion for each sample
+        #loss = loss + torch.mean(torch.max(torch.abs(prop_sum-1.0)-0.8, torch.zeros_like(prop_sum)))
+    return loss
+
+
+def loss_ref(model, pHash):
+    loss = 0.0
+    for param in model.refLayer.parameters():
+        loss = torch.sum(torch.abs(param[param < 0]))
+        for x in range(pHash["n_celltype"]):
+            idx = [y for y in range(x*pHash["n_ref"], (x+1)*pHash["n_ref"])]
+            ref_sum = torch.sum(param[idx])
+            #loss = loss + torch.abs(ref_sum-1)
+            loss = loss +torch.max(torch.abs(ref_sum-1.0), torch.zeros_like(ref_sum))
+    return loss
+
+
+
+def loss_scale(model):
+    loss = 0.0
+    #for param in model.celltypeScaleLayer.parameters():
+    #    idx_lo = param < 0.2
+    #    if torch.sum(idx_lo) > 0:
+    #        loss = loss + torch.mean((0.2-param[idx_lo])*(0.2-param[idx_lo]))
+    #    idx_hi = param > 5.0
+    #    if torch.sum(idx_hi) > 0:
+    #        loss = loss + torch.mean((5.0-param[idx_hi])*(5.0-param[idx_hi]))
+    #return loss
+    for param in model.stretchLayer.parameters():
+        #loss = torch.sum(torch.abs(param[param < 0.0]))
+        #loss = loss + torch.sum(torch.max(torch.abs(param-1.0)-0.1, torch.zeros_like(param)))
+        loss = torch.sum(torch.abs(param[param < 0.5]))
+        loss = loss + torch.sum(torch.abs(param[param > 2]))
+        #for ii in range(pHash["n_celltype"]):
+        #    loss = loss + loss_spearmanr(x[dHash["idx_feature_celltype"][ii]], dHash["ref_CSE"][ii])
+    return loss
+
+
+
+def loss_stretch(model,x, dHash, pHash):
+    loss = 0.0
+    for param in model.stretchLayer.parameters():
+        #loss = torch.sum(torch.abs(param[param < 0.0]))
+        #loss = loss + torch.sum(torch.max(torch.abs(param-1.0)-0.1, torch.zeros_like(param)))
+        loss = torch.mean(torch.abs(param[param < 0.5]))
+        loss = loss + torch.mean(torch.abs(param[param > 2]))
+        #for ii in range(pHash["n_celltype"]):
+        #    loss = loss + loss_spearmanr(x[dHash["idx_feature_celltype"][ii]], dHash["ref_CSE"][ii])
+    return loss
+
+
+def loss_epsilon_insensitive(prediction, target, epsilon):
+    #return torch.mean(torch.max(torch.abs(prediction-target) - epsilon, torch.zeros_like(prediction)))
+    return torch.mean(torch.max(torch.abs(prediction-target) - epsilon*target, torch.zeros_like(prediction)))
+
+
+def loss_epsilon_insensitive_2(prediction, target, epsilon):
+    #return torch.mean(torch.max(torch.abs(prediction-target) - epsilon, torch.zeros_like(prediction)))
+    return torch.mean(torch.max(torch.abs(prediction-target) - epsilon, torch.zeros_like(prediction)))
+
+
+def loss_large_insensitive(prediction, target, threshold):
+    #return torch.mean(torch.min(torch.abs(prediction-target) , threshold*torch.ones_like(prediction)))
+    return torch.mean(torch.min(torch.abs(prediction-target), threshold*target))
+
+
+
+def loss_large_insensitive_2(prediction, target, threshold):
+    #return torch.mean(torch.min(torch.abs(prediction-target) , threshold*torch.ones_like(prediction)))
+    return torch.mean(torch.min(torch.abs(prediction-target), threshold*torch.ones_like(prediction)))
+
+
+def loss_small_large_insensitive(prediction, target, epsilon, threshold):
+    #return torch.mean(torch.min(torch.abs(prediction-target) , threshold*torch.ones_like(prediction)))
+    loss = torch.min( torch.max(torch.abs(prediction-target) - epsilon*target, torch.zeros_like(prediction)), threshold*torch.ones_like(prediction))
+    return torch.mean(loss)
+
+

CNNreg/train.py

@@ -0,0 +1,134 @@
+import torch
+import pandas as pd
+import numpy as np
+from .data import divide_by_row_sum, reformat_ref
+from .layers import DeconvProp_S1
+from .losses import (loss_prop, loss_ref, loss_scale, loss_stretch, 
+                     loss_epsilon_insensitive, loss_epsilon_insensitive_2,
+                     spearmanr)
+import torch.nn as nn
+from torchmetrics.functional import pearson_corrcoef
+
+# https://pytorch.org/docs/0.3.0/optim.html#per-parameter-options
+# https://discuss.pytorch.org/t/parameters-with-requires-grad-false-are-updated-during-training/90096/9
+# https://www.youtube.com/watch?v=DbeIqrwb_dE
+
+#### initialize weigth with some randomness improves performance
+#### use of optim.Adam worsen the performance a lot
+#### block = 2 seems perform better than larger block size
+#### tuning celltypeScale layer and cell prortion layer separately in S1 performs better than tuning them together. 
+#### using StretchLayer_2 in S2 worsen the performance. Should stick to StretchLayer
+
+def trainProp(dHash, pHash):
+    """
+    Train the Stage I CNN model for cell proportion estimation.
+    
+    Parameters
+    ----------
+    dHash : dict
+        Data dictionary containing bulk RNA-seq and reference data.
+    pHash : dict
+        Parameter dictionary with model configuration.
+    """
+    ## Stage I:  scale expression for each cell type and adjust cell proportion
+    
+    torch.manual_seed(1334)
+    torch.cuda.manual_seed(1334)
+    net_Prop_S1 = DeconvProp_S1(dHash, pHash)
+    net_Prop_S1.train()
+    block = 4
+    loss  = nn.L1Loss()      # nn.MSELoss() nn.HuberLoss() 
+    target = dHash["bulk"]   # (N_sample, N_feature)
+    target_mean  = torch.mean(target, 0) + 0.0001
+    target_mean_adj  = 2.0*torch.tanh(target_mean+0.1)
+    #condition2   = torch.logical_and(target_mean >  0.01, target_mean <= 0.5)
+    #target_mean_adj  = torch.tensor(torch.where(condition1, torch.tensor(0.25).double().to(pHash["device"]), torch.where(condition2, torch.tensor(0.5).double().to(pHash["device"]), torch.tensor(1.0).double().to(pHash["device"]))), dtype=torch.float64, device=pHash["device"])
+    LR = 0.02 #max(0.0001, min(0.001, 1-epoch/N)) ## cannot use bigger than 0.05
+    N = pHash["max_epoch_cellprop"]
+    ll_kernel = []
+    loss_model  = []
+    for epoch in range(0, N):
+        print("epoch = " + str(epoch))
+        modd       = epoch % block
+        x_predict, x_afterRef, x_afterScale, x_afterStretch  = net_Prop_S1(dHash["CSE_reformat"], 1, pHash["n_celltype"]*pHash["n_gene"])
+        new_ref    = x_afterStretch.reshape([pHash["n_gene"], pHash["n_celltype"]])
+        gene_var   = torch.var(new_ref, dim=1)
+        quantile_marker = torch.quantile(new_ref, 0.5, dim=0)
+        ll = []
+        for ii in range( pHash["n_celltype"] ):
+            mask        = torch.ones(new_ref.shape[1], dtype=torch.bool)
+            mask[ii]    = False  # Set the mask to False for the column you want to exclude
+            #ll = ll + torch.where((new_ref[:,ii] >= quantile_marker[ii]) & (new_ref[:,ii] > torch.mean(new_ref[:,mask],dim=1)[0]))[0].tolist()
+            ll = ll + torch.where((new_ref[:,ii] >= quantile_marker[ii]))[0].tolist()
+        indx_marker     = list(set(ll)) 
+        gene_cv    = gene_var/target_mean
+        th         = torch.quantile(gene_cv, 0.75)
+        indx_1     = torch.where(((gene_cv >= 1.0) | (gene_cv >= th)))[0]
+        #indx_2     = list(set(indx_marker + torch.where((target_mean >= 0.5))[0].tolist()))
+        indx_2     = list(set(indx_marker).intersection(set(torch.where((target_mean >= 0.05))[0].tolist())))
+        indx_3     = torch.where((target_mean < 2.0))[0]
+        if modd == 1:       # tune reference layer
+            train_loss = loss_ref(net_Prop_S1, pHash) + (1-torch.mean(pearson_corrcoef(x_predict[:,indx_3].t(),  target[:,indx_3].t())))
+            #train_loss = loss_ref(net_Prop_S1, pHash) + 1-torch.mean(spearmanr(x_predict[:,indx_3], target[:,indx_3]))
+            #0.1*(1-torch.mean(pearson_corrcoef(x_predict[:,indx_3].t(), target[:,indx_3].t())))
+            train_loss.backward()
+            with torch.no_grad():
+                net_Prop_S1.refLayer.weight.sub_(net_Prop_S1.refLayer.weight.grad*LR/pHash["n_ref"])
+
+        elif modd == 2:
+            train_loss = loss_scale(net_Prop_S1) + 0.1*(1-torch.mean(pearson_corrcoef(x_predict[:,indx_3].t(),  target[:,indx_3].t())))
+            train_loss.backward()
+            with torch.no_grad():
+                net_Prop_S1.celltypeScaleLayer.weight.sub_(net_Prop_S1.celltypeScaleLayer.weight.grad*LR)
+
+        elif modd == 3:
+            train_loss = loss_stretch(net_Prop_S1, x_afterStretch, dHash, pHash) + 0.1*(1-torch.mean(pearson_corrcoef(x_predict[:,indx_3].t(),  target[:,indx_3].t())))
+            train_loss.backward()
+            with torch.no_grad():
+                net_Prop_S1.stretchLayer.weight.sub_(net_Prop_S1.stretchLayer.weight.grad*LR*pHash["n_gene"]/100)
+
+        else:      
+            rho_1      = spearmanr(x_predict[:,indx_1].t(), target[:,indx_1].t())
+            rho_2      = spearmanr(x_predict[:,indx_2], target[:,indx_2])
+            train_loss = loss_prop(net_Prop_S1) + \
+              loss_epsilon_insensitive(x_predict[:,indx_3]/target_mean_adj[indx_3], target[:,indx_3]/target_mean_adj[indx_3], 0.05) + \
+              0.1*loss_epsilon_insensitive_2(rho_1, torch.ones_like(rho_1), 0.05) + \
+              0.1*loss_epsilon_insensitive_2(rho_2, torch.ones_like(rho_2), 0.05)
+            train_loss.backward()
+            with torch.no_grad():
+                net_Prop_S1.conv1.weight.sub_(net_Prop_S1.conv1.weight.grad*LR)
+                ll_kernel.append(net_Prop_S1.conv1.weight.tolist())
+                
+        with torch.no_grad():
+            net_Prop_S1.refLayer.weight.grad.zero_()
+            net_Prop_S1.celltypeScaleLayer.weight.grad.zero_()
+            net_Prop_S1.stretchLayer.weight.grad.zero_()
+            net_Prop_S1.conv1.weight.grad.zero_()
+        ## output estimation
+        if epoch % 1000 == 0:
+            print("celltypeScaleLayer weight")
+            print(net_Prop_S1.celltypeScaleLayer.weight.tolist())
+            cellprop = np.squeeze(np.array(net_Prop_S1.conv1.weight.tolist()), 1)
+            cellprop = divide_by_row_sum(cellprop)
+            df   = pd.concat([pd.DataFrame(dHash["sample"]), pd.DataFrame(cellprop)], axis=1)
+            x    = ["Sample"]
+            x.extend(dHash["celltype"])
+            df.columns = x
+            df.to_csv(pHash["data_out_dir"]+ "/" + "Prop_predicted_" + pHash["prefix"] + "_epoch_" + str(epoch) + ".csv", index=False)
+
+
+    for name, param in net_Prop_S1.named_parameters():
+        print(name, param)
+
+    ### output estimated proportion from Stage I
+    cellprop = np.squeeze(np.array(net_Prop_S1.conv1.weight.tolist()), 1)
+    df   = pd.concat([pd.DataFrame(dHash["sample"]), pd.DataFrame(cellprop)], axis=1)
+    x    = ["Sample"]
+    x.extend(dHash["celltype"])
+    df.columns = x
+    df.to_csv(pHash["data_out_dir"]+ "/" + "Prop_predicted_" + pHash["prefix"] + ".csv", index=False)
+    # save final model
+    torch.save(net_Prop_S1.state_dict(), pHash["model_file"])
+
+
+####################################################################################################################################################################

cnnreg-0.1.0.dist-info/METADATA

@@ -0,0 +1,218 @@
+Metadata-Version: 2.4
+Name: CNNreg
+Version: 0.1.0
+Summary: CNN-based regression for cell type deconvolution of bulk RNA-seq using scRNA-seq reference
+Author-email: Xue Wang <wang.xue@mayo.edu>
+Maintainer-email: Yuanhang Liu <liu.yuanhang@mayo.edu>, Xue Wang <wang.xue@mayo.edu>
+License: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: torch>=1.10.0
+Requires-Dist: torchmetrics>=0.10.0
+Requires-Dist: torchsort>=0.1.0
+Requires-Dist: numpy
+Requires-Dist: pandas
+Dynamic: license-file
+
+# CNNreg: CNN-based Cell Type Deconvolution
+
+[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A deep learning approach for cell type deconvolution of bulk RNA-seq data using single-cell RNA-seq reference data. CNNreg employs a custom CNN-based regression model to estimate cell type proportions in complex tissue samples.
+
+## Installation
+
+### Option 1: Using pip (Recommended)
+
+CNNreg requires PyTorch. Install PyTorch first according to your system configuration:
+
+```bash
+# For CUDA 12.6 (check your CUDA version: nvidia-smi)
+pip3 install torch --index-url https://download.pytorch.org/whl/cu126
+
+# For CUDA 11.8
+pip3 install torch --index-url https://download.pytorch.org/whl/cu118
+
+# For CPU only
+pip3 install torch --index-url https://download.pytorch.org/whl/cpu
+```
+
+Then install CNNreg:
+
+```bash
+pip install CNNreg
+```
+
+### Option 2: From Source (Development)
+
+```bash
+git clone https://github.com/mwang159/CNNreg.git
+cd CNNreg
+pip install -e .
+```
+
+### Option 3: Using Conda Environment
+
+```bash
+# Create environment
+conda create -n cnnreg_env python=3.10
+conda activate cnnreg_env
+
+# Install PyTorch (choose appropriate CUDA version)
+pip3 install torch --index-url https://download.pytorch.org/whl/cu126
+
+# Install CNNreg
+pip install CNNreg
+```
+
+### Verify Installation
+
+```bash
+# Check CLI command
+cnnreg --help
+
+# Test in Python
+python -c "import CNNreg; print('CNNreg installed successfully!')"
+```
+
+## Quick Start
+
+### Command Line Interface
+
+```bash
+cnnreg -M train \
+    -bulk data/bulk.csv \
+    -ref data/sc_ref.csv \
+    -o output/ \
+    -C 7 \
+    -EP 50000 \
+    -pre GBM_analysis
+```
+
+**Parameters:**
+- `-M`: Mode - currently only `train` is implemented (evaluate/predict/explain coming in future versions)
+- `-bulk`: Path to bulk RNA-seq CSV file
+- `-ref`: Path to reference cell type specific expression (CSE) CSV
+- `-o`: Output directory
+- `-C`: Number of cell types (kernel size)
+- `-EP`: Maximum training epochs
+- `-pre`: Output file prefix
+
+**Note**: Training mode automatically generates cell proportion predictions for the input bulk samples. Predictions are saved at checkpoints (every 1000 epochs) and at completion.
+
+### Python API
+
+```python
+import torch
+import pandas as pd
+from CNNreg.data import data_CSE, reformat_ref
+from CNNreg.train import trainProp
+from CNNreg.layers import DeconvProp_S1
+
+# Setup
+device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
+
+# Load data
+df_bulk = pd.read_csv("bulk.csv")
+bulk_data = torch.tensor(
+    df_bulk.iloc[:, 1:].values.transpose(), 
+    dtype=torch.float32
+).to(device)
+
+# Configure parameters
+pHash = {
+    "bulk": "bulk.csv",
+    "reference": "sc_ref.csv",
+    "data_out_dir": "output/",
+    "max_epoch_cellprop": 50000,
+    "model_file": "output/model.pt",
+    "prefix": "GBM",
+    "device": device,
+    "n_kernel": 7,
+    "n_gene": df_bulk.shape[0],
+    "n_sample": df_bulk.shape[1] - 1,
+    "n_celltype": 7
+}
+
+# Initialize data dictionary
+dHash = {
+    "bulk": bulk_data,
+    "sample": df_bulk.columns.values[1:],
+    "celltype": ["AClike", "MESlike", "NPClike", "OPClike", "OL", "Myeloid", "T"],
+    "CSE": data_CSE(pHash["reference"], device=device)
+}
+
+# Add required indices
+k = pHash["n_gene"] * pHash["n_celltype"]
+dHash["idx_feature_celltype"] = [
+    [int(y+x) for y in range(0, k, pHash["n_celltype"])]
+    for x in range(pHash["n_celltype"])
+]
+dHash["CSE_reformat"] = reformat_ref(dHash["CSE"].expr_cse)
+
+# Train model
+trainProp(dHash, pHash)
+```
+
+## Input Data Format
+
+### Bulk RNA-seq Data
+
+Rows are samples, columns are genes:
+
+```csv
+Sample,Gene1,Gene2,Gene3,...
+Sample1,0.5,1.2,0.8,...
+Sample2,1.1,0.9,1.5,...
+Sample3,0.7,1.3,0.6,...
+```
+
+### Reference scRNA-seq Data
+
+Cell Type Specific Expression profiles from scRNA-seq:
+
+```csv
+CellType,Gene1,Gene2,Gene3,...
+AClike_ref1,0.3,0.8,0.5,...
+AClike_ref2,0.4,0.7,0.6,...
+MESlike_ref1,0.9,0.2,0.4,...
+```
+
+## Output Files
+
+- `Prop_predicted_{prefix}_epoch_{N}.csv`: Cell proportions at checkpoint epochs (every 1000)
+- `Prop_predicted_{prefix}.csv`: Final estimated cell proportions
+- `cellprop_model.pt`: Trained PyTorch model (state dict)
+
+**Output format:**
+
+```csv
+Sample,celltype_1,celltype_2,celltype_3,...
+Sample1,0.23,0.15,0.31,...
+Sample2,0.19,0.28,0.22,...
+```
+
+## Model Architecture
+
+CNNreg uses a custom 5-layer CNN pipeline specifically designed for biological deconvolution:
+
+1. **RefCombLayer**: Combines multiple reference samples per cell type
+2. **SliceSumLayer**: Aggregates reference combinations
+3. **CelltypeScaleLayer**: Scales expression for each cell type independently
+4. **StretchLayer**: Applies gene-specific scaling factors
+5. **Conv1D Layer**: Estimates cell proportions via 1D convolution
+
+## Citation
+
+If you use CNNreg in your research, please cite:
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Contact
+
+- **Issues**: [GitHub Issues](https://github.com/yourusername/CNNreg/issues)
+- **Email**: wang.xue@mayo.edu, liu.yuanhang@mayo.edu

cnnreg-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+CNNreg/__init__.py,sha256=LZNMFSvn-lvAp4amVFYy8HnhxlXLQeXt9aT6i-BS2EQ,454
+CNNreg/cli.py,sha256=YErLfKgt0RD4uRw6_rOdFMajRo9akQhj_ncL4YXPKkI,2870
+CNNreg/data.py,sha256=gAvpMOJHj7T7bh2Jp4gKgM5K5A0DvNGIMV6dVi3p0GY,1335
+CNNreg/layers.py,sha256=SMgAR0ojLvOEqUqt4_hyhj1OKmkvIGaXWtIWz44twkM,3569
+CNNreg/losses.py,sha256=zmpjIFhpmgwosoG6Lgrvq0RObqtvMzhyfxrHKFdzgUc,4699
+CNNreg/train.py,sha256=cJVQ3x4IqAgXfORkavna0B5btZtozOf4GVG7l2Zzmr4,7262
+cnnreg-0.1.0.dist-info/licenses/LICENSE,sha256=6le1Ynl_12mYxMvuMCVOeBVHPY01YMyexsWvTBl0r6Y,1064
+cnnreg-0.1.0.dist-info/METADATA,sha256=EnhVzcsm5HkiQpuVD4_bTr9y-WxnutpAE9e2QLeRutk,5699
+cnnreg-0.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+cnnreg-0.1.0.dist-info/entry_points.txt,sha256=oNea6BqtYSR4t5s0q0t9IV4i4k4z6omc4D7c64lx5Uw,43
+cnnreg-0.1.0.dist-info/top_level.txt,sha256=zSYWDE6KCfeTnHz1PQ5KXUVxpZSIVkjuOS9FrgHWJBA,7
+cnnreg-0.1.0.dist-info/RECORD,,

cnnreg-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

cnnreg-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+cnnreg = CNNreg.cli:main

cnnreg-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Xue Wang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cnnreg-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+CNNreg