MULocDeep

https://github.com/yuexujiang/mulocdeep
Admin
MULocDeep is a deep learning model for protein localization prediction at subcellular and...
Tokens:6,285
Snippets:52
Trust Score:5.6
Update:5 months ago
Show doc for...
Tokens:
Raw
### Train Variant Model

Source: https://github.com/yuexujiang/mulocdeep/blob/master/README.md

Train a variant model, for example, using deeploc training data to create a 10-class classification model. Specify the input directory and the model output directory.

```sh
python train.py --input_dir ./data/deeploc_40nr_8folds/ --model_output ./var_model_xxx/
```

--------------------------------

### Convert Sequence to BLOSUM62 Matrix

Source: https://context7.com/yuexujiang/mulocdeep/llms.txt

Encodes a protein sequence into a NumPy matrix using BLOSUM62 substitution scores. Use this as a fallback when PSSM files are unavailable to get evolutionary-informed amino acid encodings.

```python
from utils import convertSampleToBlosum62

seq = "ACDEFGHIKLMNPQRSTVWY"
blosum = convertSampleToBlosum62(seq)
print(blosum.shape)   # (20, 20)
print(blosum[0])      # [ 4 -1 -2 -2  0 -1 -1  0 -2 -1 -1 -1 -1 -2 -1  1  0 -3 -2  0 ]  <- A row
```

--------------------------------

### Train MULocDeep Model

Source: https://github.com/yuexujiang/mulocdeep/blob/master/README.md

Use this command to train a MULocDeep model with specified input directories for level 1 and level 2 data, and an output directory for the model.

```sh
python train.py --lv1_input_dir ./data/UniLoc_train_40nr/ --lv2_input_dir ./data/UniLoc_train_40nr/ --model_output ./model_xxx/ --MULocDeep_model
```

--------------------------------

### Run MULocDeep Prediction (CPU)

Source: https://context7.com/yuexujiang/mulocdeep/llms.txt

Performs protein localization prediction using the CPU. Use --no-att to disable attention visualization and save time.

```bash
python predict.py \
  -input ./wiki_seq.txt \
  -output ./results/ \
  --no-att \
  --cpu
```

--------------------------------

### process_input_user

Source: https://context7.com/yuexujiang/mulocdeep/llms.txt

Runs PSI-BLAST to generate PSSMs for prediction. It iterates over sequences in a FASTA file, runs PSI-BLAST against SwissProt, and saves PSSM output to specified files. Sequences are indexed numerically.

```APIDOC
## `process_input_user()` — Run PSI-BLAST to generate PSSMs for prediction

Iterates over all sequences in a FASTA file, writes each sequence to a temporary file, runs PSI-BLAST (3 iterations, e-value 0.001) against the local SwissProt database, and saves the ASCII PSSM output to `dir/<index>_pssm.txt`. Sequences are indexed numerically (0, 1, 2, …) to avoid ID collisions. Silently skips invalid proteins.

```python
from utils import process_input_user

# Requires NCBI BLAST+ installed and ./db/swissprot/ present
process_input_user(
    seq_file="./wiki_seq.txt",
    dir="./output_pssm/"
)
# Creates: ./output_pssm/0_pssm.txt, ./output_pssm/1_pssm.txt, ...
```
```

--------------------------------

### Train MULocDeep Model

Source: https://context7.com/yuexujiang/mulocdeep/llms.txt

Trains the full dual-head MULocDeep model for subcellular and suborganellar localization. Requires separate input directories for level 1 and level 2 models.

```bash
python train.py \
  --lv1_input_dir ./data/UniLoc_train_40nr/ \
  --lv2_input_dir ./data/UniLoc_train_40nr/ \
  --model_output   ./my_model/ \
  --MULocDeep_model
```

--------------------------------

### Bayesian Hyperparameter Optimization (Bash)

Source: https://context7.com/yuexujiang/mulocdeep/llms.txt

Runs Bayesian optimization for variant model hyperparameters across cross-validation folds. Requires GPyOpt and precomputed PSSMs. Outputs include iteration logs, best parameters, reports, and convergence plots.

```bash
# Run hyperparameter search (requires GPyOpt and precomputed PSSMs)
# Search space: hidden_dim [32,490], da [32,430], r [16,64],
#               W_regularizer [1e-5,1e-3], Att_regularizer_weight [1e-5,1e-3],
#               drop_per [0.1,0.75], drop_hid [0.1,0.75]
python optimise.py

# Outputs per fold (fold 0 shown):
#   ./deeplocdata_phyChpssm_batchnorm_40nr/costum_record_fold0.txt   (iteration log)
#   ./deeplocdata_phyChpssm_batchnorm_40nr/costum_record_0.txt       (best params)
#   fold_0_opti_report.txt                                            (GPyOpt report)
#   ./deeplocdata_phyChpssm_batchnorm_40nr/0.png                     (convergence plot)
```

--------------------------------

### Run PSI-BLAST for PSSM Generation

Source: https://context7.com/yuexujiang/mulocdeep/llms.txt

Processes sequences from a FASTA file to generate PSSM files using PSI-BLAST. Requires NCBI BLAST+ and a SwissProt database. Sequences are indexed numerically to avoid ID collisions.

```python
from utils import process_input_user

# Requires NCBI BLAST+ installed and ./db/swissprot/ present
process_input_user(
    seq_file="./wiki_seq.txt",
    dir="./output_pssm/"
)
# Creates: ./output_pssm/0_pssm.txt, ./output_pssm/1_pssm.txt, ...
```

--------------------------------

### Run MULocDeep Prediction with Precomputed PSSMs

Source: https://context7.com/yuexujiang/mulocdeep/llms.txt

Skips the PSSM generation step by reusing precomputed PSSMs, which can significantly speed up prediction.

```bash
python predict.py \
  -input ./wiki_seq.txt \
  -output ./results/ \
  -existPSSM ./precomputed_pssm/ \
  --att \
  --cpu
```

--------------------------------

### Predict Protein Localization (CPU)

Source: https://github.com/yuexujiang/mulocdeep/blob/master/README.md

Predict protein localization using the pre-trained model on a CPU. This command includes options for input file, output directory, attention visualization, and specifies CPU usage.

```sh
python predict.py -input ./wiki_seq.txt -output ./test --att --cpu
```

--------------------------------

### Train Model with Precomputed PSSMs

Source: https://context7.com/yuexujiang/mulocdeep/llms.txt

Reuses existing PSSMs during the training process to avoid redundant PSI-BLAST computations.

```bash
python train.py \
  --lv1_input_dir ./data/UniLoc_train_40nr/ \
  --lv2_input_dir ./data/UniLoc_train_40nr/ \
  --model_output  ./my_model/ \
  --MULocDeep_model \
  -existPSSM ./data/pssm_cache/
```

--------------------------------

### Run MULocDeep Prediction (GPU)

Source: https://context7.com/yuexujiang/mulocdeep/llms.txt

Performs protein localization prediction using the GPU and generates attention visualization plots.

```bash
python predict.py \
  -input ./wiki_seq.txt \
  -output ./results_gpu/ \
  --att \
  --gpu
```

--------------------------------

### Build MULocDeep Keras Model (GPU/CPU)

Source: https://context7.com/yuexujiang/mulocdeep/llms.txt

Constructs the Keras model for MULocDeep. `singlemodel()` uses CuDNNLSTM for GPU optimization, while `singlemodel_cpu()` uses standard LSTM for CPU inference. Returns models for predicting subcellular and suborganellar/subcellular outputs.

```python
import numpy as np
from utils import singlemodel, singlemodel_cpu

# Dummy batch: 4 proteins × 1000 positions × 25 features
dummy_x = np.zeros((4, 1000, 25))

# Build GPU model
model_big, model_small = singlemodel(dummy_x)
model_big.summary()
# Input shapes: [None, 1000, 25] + [None, 1000, 1]
# model_big  output: [None, 10]       (subcellular probabilities)
# model_small output: [None, 10, 8],  [None, 10]  (suborganellar + subcellular)

# Build CPU model (for inference without GPU)
model_big_cpu, model_small_cpu = singlemodel_cpu(dummy_x)
```

--------------------------------

### Build Single-Level Variant Model (Python)

Source: https://context7.com/yuexujiang/mulocdeep/llms.txt

Constructs a single-output softmax classifier for alternative datasets. Requires NumPy and the utils module.

```python
import numpy as np
from utils import var_model, var_model_cpu

dummy_x = np.zeros((4, 1000, 25))
model = var_model(dummy_x)
model.summary()
# Output: [None, 10]  (softmax over 10 subcellular classes)
```

--------------------------------

### readPSSM

Source: https://context7.com/yuexujiang/mulocdeep/llms.txt

Parses a PSI-BLAST ASCII PSSM file and returns the per-position substitution score matrix as a (seq_len, 20) NumPy string array. It skips the header and stops at the first blank line.

```APIDOC
## `readPSSM()` — Parse a PSI-BLAST PSSM file

Reads a PSI-BLAST ASCII PSSM file and returns the per-position substitution score matrix as a `(seq_len, 20)` NumPy string array (columns 2–21 of the PSSM body). Skips the 3-line header and stops at the first blank line.

```python
from utils import readPSSM
import numpy as np

pssm = readPSSM("./pssm_cache/P03070_pssm.txt")
pssm = pssm.astype(float)
print(pssm.shape)    # (seq_len, 20)
print(pssm[0])       # per-residue PSSM row for position 0
```
```

--------------------------------

### singlemodel / singlemodel_cpu

Source: https://context7.com/yuexujiang/mulocdeep/llms.txt

Builds the MULocDeep Keras model. `singlemodel()` uses `CuDNNLSTM` for GPU optimization, while `singlemodel_cpu()` uses standard `LSTM`. Both return a tuple `(model_big, model_small)` for predicting subcellular and suborganellar/subcellular classes.

```APIDOC
## `singlemodel()` / `singlemodel_cpu()` — Build the MULocDeep Keras model

Constructs the dual-output bidirectional LSTM + structured self-attention Keras model. `singlemodel()` uses `CuDNNLSTM` (GPU-optimized); `singlemodel_cpu()` uses standard `LSTM`. Returns a tuple `(model_big, model_small)`: `model_big` predicts 10 subcellular classes, `model_small` jointly predicts suborganellar (10×8) and subcellular (10) outputs.

```python
import numpy as np
from utils import singlemodel, singlemodel_cpu

# Dummy batch: 4 proteins × 1000 positions × 25 features
dummy_x = np.zeros((4, 1000, 25))

# Build GPU model
model_big, model_small = singlemodel(dummy_x)
model_big.summary()
# Input shapes: [None, 1000, 25] + [None, 1000, 1]
# model_big  output: [None, 10]       (subcellular probabilities)
# model_small output: [None, 10, 8],  [None, 10]  (suborganellar + subcellular)

# Build CPU model (for inference without GPU)
model_big_cpu, model_small_cpu = singlemodel_cpu(dummy_x)
```
```

--------------------------------

### Predict Protein Localization (GPU)

Source: https://github.com/yuexujiang/mulocdeep/blob/master/README.md

Predict protein localization using the pre-trained model on a GPU. This command includes options for input file, output directory, attention visualization, and specifies GPU usage.

```sh
python predict.py -input ./wiki_seq.txt -output ./test --att --gpu
```

--------------------------------

### Parse PSI-BLAST PSSM File

Source: https://context7.com/yuexujiang/mulocdeep/llms.txt

Reads a PSI-BLAST ASCII PSSM file and extracts the per-position substitution score matrix. Skips the header and stops at the first blank line. Ensure the file path is correct.

```python
from utils import readPSSM
import numpy as np

pssm = readPSSM("./pssm_cache/P03070_pssm.txt")
pssm = pssm.astype(float)
print(pssm.shape)    # (seq_len, 20)
print(pssm[0])       # per-residue PSSM row for position 0
```

--------------------------------

### Generate Padding Mask Vector

Source: https://context7.com/yuexujiang/mulocdeep/llms.txt

Creates a binary mask vector to indicate real residues versus padding. Use this to prevent the attention mechanism from attending to padded positions in sequences.

```python
from utils import gen_mask_mat

# Protein of length 350, padded to 1000
mask = gen_mask_mat(num_want=350, num_mask=650)
print(mask.shape)        # (1000,)
print(mask[:3])          # [1. 1. 1.]
print(mask[350:353])     # [0. 0. 0.]
```

--------------------------------

### Train Variant Single-Level Model

Source: https://context7.com/yuexujiang/mulocdeep/llms.txt

Trains a variant single-level model, such as a 10-class DeepLoc model. Uses a single input directory for training data.

```bash
python train.py \
  --input_dir    ./data/deeploc_40nr_8folds/ \
  --model_output ./var_model/
```

--------------------------------

### convertlabels_to_categorical

Source: https://context7.com/yuexujiang/mulocdeep/llms.txt

Parses a label string in "i.j" format into a `(10, 8)` NumPy float array. Index `i` represents the subcellular class (0–9) and `j` represents the suborganellar sub-class (0–7).

```APIDOC
## `convertlabels_to_categorical()` — Parse label string to 10×8 matrix

Converts a semicolon-delimited label string in "i.j" format (e.g., `"0.1;3.3"`) into a `(10, 8)` NumPy float array. Index `i` is the subcellular class (0–9) and `j` is the suborganellar sub-class (0–7).

```python
from utils import convertlabels_to_categorical

label_str = "0.1;3.3"   # Nucleus nucleoplasm + Mitochondrion matrix
y = convertlabels_to_categorical(label_str)
print(y.shape)          # (10, 8)
print(y[0])             # [0. 1. 0. 0. 0. 0. 0. 0.]  <- Nucleus row
print(y[3])             # [0. 0. 0. 1. 0. 0. 0. 0.]  <- Mitochondrion row
```
```

--------------------------------

### Convert Label String to Categorical Matrix

Source: https://context7.com/yuexujiang/mulocdeep/llms.txt

Parses a semicolon-delimited label string (e.g., "i.j") into a (10, 8) NumPy float array. Index 'i' is the subcellular class and 'j' is the suborganellar subclass.

```python
from utils import convertlabels_to_categorical

label_str = "0.1;3.3"   # Nucleus nucleoplasm + Mitochondrion matrix
y = convertlabels_to_categorical(label_str)
print(y.shape)          # (10, 8)
print(y[0])             # [0. 1. 0. 0. 0. 0. 0. 0.]  <- Nucleus row
print(y[3])             # [0. 0. 0. 1. 0. 0. 0. 0.]  <- Mitochondrion row
```

--------------------------------

### convertSampleToBlosum62

Source: https://context7.com/yuexujiang/mulocdeep/llms.txt

Encodes a protein sequence into a (seq_len, 20) NumPy matrix using BLOSUM62 substitution scores. This is used as a fallback when PSSM files are unavailable, providing evolutionary-informed amino acid encodings.

```APIDOC
## `convertSampleToBlosum62()` — Encode sequence with BLOSUM62 substitution matrix

Converts a protein sequence into a `(seq_len, 20)` NumPy matrix using BLOSUM62 substitution scores. Used as a fallback when PSSM files are unavailable, providing evolutionary-informed amino acid encodings.

```python
from utils import convertSampleToBlosum62

seq = "ACDEFGHIKLMNPQRSTVWY"
blosum = convertSampleToBlosum62(seq)
print(blosum.shape)   # (20, 20)
print(blosum[0])      # [ 4 -1 -2 -2  0 -1 -1  0 -2 -1 -1 -1 -1 -2 -1  1  0 -3 -2  0 ]  <- A row
```
```

--------------------------------

### Encode Sequence with PCA-Reduced Physicochemical Properties

Source: https://context7.com/yuexujiang/mulocdeep/llms.txt

Converts an amino acid sequence into a NumPy matrix using PCA-reduced physicochemical descriptors. Unrecognized characters are represented as zeros.

```python
from utils import convertSampleToPhysicsVector_pca

seq = "MSLRQSIRFFKPAT"
phychem = convertSampleToPhysicsVector_pca(seq)
print(phychem.shape)   # (14, 5)
print(phychem[0])      # [ 0.239  -0.141  -0.155   0.321   0.077 ]  <- M
```

--------------------------------

### Structured Self-Attention Keras Layer (Python)

Source: https://context7.com/yuexujiang/mulocdeep/llms.txt

Implements a custom Keras Layer for structured self-attention with padding awareness. Computes attention weights and context vectors, optionally returning attention matrices and penalizing redundant heads.

```python
import keras
from keras.layers import Input, Bidirectional, LSTM, Lambda, concatenate
from keras.models import Model
from hier_attention_mask import Attention

seq_input  = Input(shape=(100, 64))   # (batch, seq_len, hidden)
mask_input = Input(shape=(100, 1))    # (batch, seq_len, 1)

# Attention with 16 heads over 64-dim hidden, projection dim 32
att_out, att_weights = Attention(
    hidden=64, da=32, r=16,
    activation='tanh',
    return_attention=True,
    attention_regularizer_weight=0.0007
)(concatenate([seq_input, mask_input]))

# att_out shape:     (batch, 16, 64)  — 16 context vectors
# att_weights shape: (batch, 16, 100) — 16 attention distributions

model = Model(inputs=[seq_input, mask_input], outputs=[att_out, att_weights])
model.summary()
```

--------------------------------

### gen_mask_mat

Source: https://context7.com/yuexujiang/mulocdeep/llms.txt

Generates a 1D binary mask vector of length `num_want + num_mask`. Ones indicate real residues, and zeros indicate padding positions. This is used to prevent the attention mechanism from attending to padded positions.

```APIDOC
## `gen_mask_mat()` — Generate a padding mask vector

Creates a 1D binary mask vector of length `num_want + num_mask`: ones for real residues and zeros for padding positions. Used to prevent the attention mechanism from attending to padded positions.

```python
from utils import gen_mask_mat

# Protein of length 350, padded to 1000
mask = gen_mask_mat(num_want=350, num_mask=650)
print(mask.shape)        # (1000,)
print(mask[:3])          # [1. 1. 1.]
print(mask[350:353])     # [0. 0. 0.]
```
```

--------------------------------

### Convert Suborganellar to Subcellular Labels

Source: https://context7.com/yuexujiang/mulocdeep/llms.txt

Collapses a suborganellar label tensor into a subcellular binary label tensor. A subcellular class is positive if any of its suborganellar subclasses are positive. Handles both 3D and 2D inputs.

```python
from utils import getTrue4out1
import numpy as np

# Simulate one sample: positive for Nucleus->nucleoplasm (0,1) and Mitochondrion->matrix (3,3)
y = np.zeros((1, 10, 8))
y[0, 0, 1] = 1.0  # Nucleus, nucleoplasm
y[0, 3, 3] = 1.0  # Mitochondrion matrix

lv1_labels = getTrue4out1(y)
print(lv1_labels.shape)     # (1, 10)
print(lv1_labels[0])        # [1. 0. 0. 1. 0. 0. 0. 0. 0. 0.]
```

--------------------------------

### getTrue4out1

Source: https://context7.com/yuexujiang/mulocdeep/llms.txt

Converts suborganellar labels to subcellular binary labels. It collapses a `(N, 10, 8)` suborganellar label tensor into a `(N, 10)` subcellular binary label tensor. A subcellular class is marked positive (1) if any of its suborganellar sub-classes is positive. It also handles 2D inputs `(N, 10)` by collapsing across the last axis.

```APIDOC
## `getTrue4out1()` — Convert suborganellar labels to subcellular binary labels

Collapses a `(N, 10, 8)` suborganellar label tensor into a `(N, 10)` subcellular binary label tensor. A subcellular class is marked positive (1) if any of its suborganellar sub-classes is positive. Also handles 2D inputs `(N, 10)` by collapsing across the last axis.

```python
from utils import getTrue4out1
import numpy as np

# Simulate one sample: positive for Nucleus->nucleoplasm (0,1) and Mitochondrion->matrix (3,3)
y = np.zeros((1, 10, 8))
y[0, 0, 1] = 1.0  # Nucleus, nucleoplasm
y[0, 3, 3] = 1.0  # Mitochondrion matrix

lv1_labels = getTrue4out1(y)
print(lv1_labels.shape)     # (1, 10)
print(lv1_labels[0])        # [1. 0. 0. 1. 0. 0. 0. 0. 0. 0.]
```
```
Tokens:
Raw