tcrdist3

https://tcrdist3.readthedocs.io
Admin
tcrdist3 is an open-source Python package for T cell receptor sequence analysis that enables TCR...
Tokens:3,641
Snippets:35
Trust Score:9.6
Update:5 months ago
Show doc for...
Tokens:
Raw
### Install tcrdist3 using pip

Source: https://tcrdist3.readthedocs.io

Install the tcrdist3 package from GitHub using pip. This command installs version 0.2.2.

```bash
pip install git+https://github.com/kmayerb/tcrdist3.git@0.2.2
```

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

### Set up tcrdist3 environment with venv

Source: https://tcrdist3.readthedocs.io

Create and activate a virtual environment for tcrdist3 using Python 3.8.5, then install parasail and tcrdist3.

```bash
python3 -m venv ./tcr3
source tcr3/bin/activate
pip3 install parasail==1.1.17
pip3 install tcrdist3
```

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

### Install build tools on OSX

Source: https://tcrdist3.readthedocs.io

Install necessary build tools on macOS using Homebrew. These are required for building certain dependencies like parasail.

```bash
brew install autoconf automake libtool
```

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

### Set up tcrdist3 environment with Conda

Source: https://tcrdist3.readthedocs.io

Create and activate a Conda environment for tcrdist3 with Python 3.8, then install the package and related tools like notebook and ipython.

```bash
conda create --name tcrdist3 python=3.8
conda activate tcrdist3
pip install tcrdist3
pip install notebook ipython
ipython
```

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

### Pull tcrdist3 Docker container

Source: https://tcrdist3.readthedocs.io

Pull the tcrdist3 Docker container image version 0.2.0 from Quay.io.

```bash
docker pull quay.io/kmayerb/tcrdist3:0.2.0
```

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

### Initialize TCRRep Object and Compute Distances

Source: https://tcrdist3.readthedocs.io

Initializes a TCRRep object with a pandas DataFrame and computes pairwise TCR distances using default parameters. Ensure the organism, chains, and database file are correctly specified.

```python
import pandas as pd
from tcrdist.repertoire import TCRrep

df = pd.read_csv("dash.csv")
tr = TCRrep(cell_df = df, 
            organism = 'mouse', 
            chains = ['beta'], 
            db_file = 'alphabeta_gammadelta_db.tsv')

```

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

### Load TCR Data into TCRrep Object

Source: https://tcrdist3.readthedocs.io

Load TCR data from a CSV file into a pandas DataFrame and initialize a TCRrep object for analysis. Ensure the 'organism', 'chains', and 'db_file' parameters are correctly set for your dataset.

```python
import pandas as pd
from tcrdist.repertoire import TCRrep

df = pd.read_csv("dash.csv")
tr = TCRrep(cell_df = df, 
            organism = 'mouse', 
            chains = ['alpha','beta'], 
            db_file = 'alphabeta_gammadelta_db.tsv',
            compute_distances = False)
```

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

### Save TCRrep Object with Optimized File Size

Source: https://tcrdist3.readthedocs.io

Save a TCRrep object to a file using dill after optimizing for file size. This involves removing large attributes and converting NumPy arrays to int16. This can significantly reduce the file size for large datasets.

```python
import dill
import pandas as pd
from tcrdist.repertoire import TCRrep

df = pd.read_csv("dash.csv")
tr = TCRrep(cell_df = df,
            organism = 'mouse',
            chains = ['alpha','beta'],
            db_file = 'alphabeta_gammadelta_db.tsv')

"""
Optional: remove CDR specific attributes
prior to saving
"""
tr.pw_pmhc_a_aa = None
tr.pw_cdr3_a_aa = None
tr.pw_cdr2_a_aa = None
tr.pw_cdr1_a_aa = None
tr.pw_pmhc_b_aa = None
tr.pw_cdr3_b_aa = None
tr.pw_cdr2_b_aa = None
tr.pw_cdr1_b_aa = None

"""
Optional: change numpy datatype to further reduces file sizes
"""
tr.pw_alpha = tr.pw_alpha.astype('int16')
tr.pw_alpha = tr.pw_beta.astype('int16')

dill.dump(tr, open("yourfile.dill", mode='wb'))
tr_reloaded = dill.load(open("yourfile.dill", mode='rb'))

```

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

### Hierarchical Clustering for Neighborhood Analysis

Source: https://tcrdist3.readthedocs.io

Performs hierarchical clustering to define TCR neighborhoods and visualizes their properties. This method is useful for exploring TCR diversity across different neighborhood sizes and relating them to experimental conditions.

```python
import pandas as pd
from tcrdist.repertoire import TCRrep

df = pd.read_csv("dash.csv")
tr = TCRrep(cell_df = df, 
            organism = 'mouse', 
            chains = ['beta','alpha'], 
            db_file = 'alphabeta_gammadelta_db.tsv')

from tcrdist.rep_diff import hcluster_diff, member_summ
from hierdiff import plot_hclust_props

# diff testing is pasted on binary comparison, so all epitope not 'PA' are set to 'X'
tr.clone_df['PA'] = ['PA' if x == 'PA' else 'X' for x in tr.clone_df.epitope]

res, Z= hcluster_diff(tr.clone_df, tr.pw_beta, x_cols = ['PA'], count_col = 'count')

res_summary = member_summ(res_df = res, clone_df = tr.clone_df, addl_cols=['epitope'])

res_detailed = pd.concat([res, res_summary], axis = 1)

html = plot_hclust_props(Z,
            title='PA Epitope Example',
            res=res_detailed,
            tooltip_cols=['cdr3_b_aa','v_b_gene', 'j_b_gene','epitope'],
            alpha=0.00001, colors = ['blue','gray'],
            alpha_col='pvalue')

with open('hierdiff_example.html', 'w') as fh:
    fh.write(html)
```

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

### Save and Reload TCRrep Object

Source: https://tcrdist3.readthedocs.io

Save a TCRrep object to a file using dill and then reload it. This is useful for persisting analysis states or sharing data.

```python
import dill
import pandas as pd
from tcrdist.repertoire import TCRrep

df = pd.read_csv("dash.csv")
tr = TCRrep(cell_df = df,
            organism = 'mouse',
            chains = ['alpha','beta'],
            db_file = 'alphabeta_gammadelta_db.tsv')

dill.dump(tr, open("yourfile.dill", mode='wb'))
tr_reloaded = dill.load(open("yourfile.dill", mode='rb'))

```

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

### Generate Gene Usage Plots with tcrdist3

Source: https://tcrdist3.readthedocs.io

Create Sankey plots visualizing V/J gene usage for specific epitopes using tcrdist3's plotting functions. The plots are saved as SVG files.

```python
from tcrdist.plotting import plot_pairings, _write_svg

svg_PA  = plot_pairings(tr.clone_df.loc[tr.clone_df.epitope == "PA"], 
            cols = ['v_b_gene', 'j_b_gene','j_a_gene', 'v_a_gene'], 
            count_col='count')
  
svg_NP = plot_pairings(tr.clone_df.loc[tr.clone_df.epitope == "NP"], 
        cols = ['v_b_gene', 'j_b_gene', 'j_a_gene', 'v_a_gene'], 
        count_col='count')

_write_svg(svg_PA, name = "PA_gene_usage_plot.svg", dest = ".")

_write_svg(svg_NP, name = "NP_gene_usage_plot.svg", dest = ".")
```

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

### Compute Fixed Radius Neighborhoods for TCRs

Source: https://tcrdist3.readthedocs.io

Calculates TCR specificity neighborhoods using a fixed radius. This involves preparing the clone DataFrame, computing pairwise distances for specified chains, and then applying the neighborhood_diff function. The results are sorted by FDRq and OR values.

```python
import pandas as pd
from tcrdist.repertoire import TCRrep

df = pd.read_csv("dash.csv")
tr = TCRrep(cell_df = df, 
            organism = 'mouse', 
            chains = ['beta','alpha'], 
            db_file = 'alphabeta_gammadelta_db.tsv')

from tcrdist.rep_diff import neighborhood_diff
# diff testing is pasted on binary comparison, so all epitope not 'PA' are set to 'X'
tr.clone_df['PA'] = ['PA' if x == 'PA' else 'X' for x in tr.clone_df.epitope]

# Larger Radius
tr.nn_df = neighborhood_diff(clone_df= tr.clone_df, 
    pwmat = tr.pw_beta + tr.pw_alpha, 
    count_col = 'count', 
    x_cols = ['PA'], 
    knn_radius = 150)

tr.nn_df[['K_neighbors', 'val_0', 'ct_0', 'val_2', 'ct_2', 'RR','OR', 'pvalue', 'FWERp','FDRq']].\
    sort_values(['FDRq']).sort_values(['OR','ct_0'], ascending = False)

```

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

### Calculate Neighborhood Differences with Fixed Radius

Source: https://tcrdist3.readthedocs.io

Calculates the differences in neighborhoods for TCRs within a specified radius. Use this to identify TCRs that are similar to a reference TCR based on sequence proximity.

```python
tr.nn_df = neighborhood_diff(clone_df= tr.clone_df, 
    pwmat = tr.pw_beta + tr.pw_alpha, 
    count_col = 'count', 
    x_cols = ['PA'], 
    knn_radius = 75)

tr.nn_df[['K_neighbors', 'val_0', 'ct_0', 'val_2', 'ct_2', 'RR','OR', 'pvalue', 'FWERp','FDRq']].\
    sort_values(['FDRq']).sort_values(['OR','ct_0'], ascending = False)
```

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

### Perform Fisher's Exact Test on Gene Pairs

Source: https://tcrdist3.readthedocs.io

Conduct Fisher's exact test on specified gene pairs within a TCR repertoire subset, such as for a particular epitope. This helps identify statistically significant associations between gene combinations.

```python
import fishersapi
fishersapi.fishers_frame(tr.clone_df.loc[tr.clone_df.epitope == "NP"], 
                         col_pairs=[('v_b_gene', 'j_b_gene'),
                                    ('v_a_gene', 'j_a_gene'),
                                    ('v_a_gene', 'v_b_gene'),
                                    ('j_a_gene', 'j_b_gene')])
```
Tokens:
Raw