### Showcase and Run CLI Examples

Source: https://github.com/gph82/mdciao/blob/master/doc/cli_cli/cli_cli.md

Use this script to view and optionally run examples of the command-line tools. Type the tool name after the script to see its examples.

```bash
>>> mdc_examples.py
usage: mdc_examples.py [-h] [-x] [--short_options] clt

Wrapper script to showcase and optionally run examples of the
command-line-tools that ship with mdciao.

Available command line tools are:
 * mdc_GPCR_overview.py
 * mdc_CGN_overview.py
 * mdc_KLIFS_overview.py
 * mdc_compare.py
 * mdc_fragments.py
 * mdc_interface.py
 * mdc_neighborhoods.py
 * mdc_notebooks.py
 * mdc_pdb.py
 * mdc_residues.py
 * mdc_sites.py

You can type for example:
 > mdc_interface.py  -h
 to view the command's documentation or
 > mdc_examples.py interf
 to show and/or run an example of that command
```

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

### Install mdciao from source

Source: https://context7.com/gph82/mdciao/llms.txt

Install mdciao from its source code repository. This is useful for developers or for installing a specific version.

```bash
git clone https://github.com/gph82/mdciao.git
cd mdciao
python3 -m pip install .
```

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

### Fetch Example Data with mdciao

Source: https://github.com/gph82/mdciao/blob/master/mdciao/examples/02.Missing_Contacts.ipynb

Downloads and extracts example data for mdciao if it doesn't already exist. This is a prerequisite for running subsequent examples.

```python
import mdciao, os
if not os.path.exists("mdciao_example"): 
    mdciao.examples.fetch_example_data()
```

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

### List Built-in Command-Line Examples

Source: https://github.com/gph82/mdciao/blob/master/doc/index.md

This command lists all available built-in command-line toy examples for mdciao. These examples can be used to quickly test or demonstrate functionalities.

```bash
mdc_examples.py
```

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

### Explore mdciao Command Line Examples

Source: https://github.com/gph82/mdciao/blob/master/doc/cli_stub.md

Use `mdc_examples.py` to view usage information for all available command-line tools and to run examples. Type `mdc_examples.py <tool_name>` to see specific examples.

```bash
>>> mdc_examples.py
usage: mdc_examples.py [-h] [-x] [--short_options] clt

Wrapper script to showcase and optionally run examples of the
command-line-tools that ship with mdciao.

Available command line tools are:
 * mdc_GPCR_overview.py
 * mdc_CGN_overview.py
 * mdc_compare.py
 * mdc_fragments.py
 * mdc_interface.py
 * mdc_neighborhoods.py
 * mdc_pdb.py
 * mdc_residues.py
 * mdc_sites.py

You can type for example:
 > mdc_interface.py  -h
 to view the command's documentation or
 > mdc_examples.py interf
 to show and/or run an example of that command
```

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

### Download and Load Example Data

Source: https://github.com/gph82/mdciao/blob/master/mdciao/examples/08.Manuscript.ipynb

Fetches example data for the 'b2ar@Gs' system and loads the trajectory and topology files.

```python
import numpy as np
import os
if not os.path.exists("mdciao_example"):
    mdciao.examples.fetch_example_data("b2ar@Gs")
traj = md.load("mdciao_example/traj.xtc",top="mdciao_example/top.pdb")
```

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

### Run an Example for a Specific Command Line Tool

Source: https://github.com/gph82/mdciao/blob/master/doc/cli_stub.md

To show and/or run an example for a specific command-line tool, invoke `mdc_examples.py` with the tool's name or a relevant keyword.

```bash
> mdc_examples.py interf
```

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

### Install mdciao from local source

Source: https://github.com/gph82/mdciao/blob/master/doc/installation.md

Install mdciao from the local source files after cloning or downloading the repository. This command installs the package and its dependencies.

```bash
python3 -m pip install .
```

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

### Install core dependencies with pip

Source: https://github.com/gph82/mdciao/blob/master/doc/installation.md

If core dependencies like numpy, cython, or mdtraj are not installed properly, use these pip commands to install them individually before installing mdciao.

```bash
pip install cython
pip install numpy
pip install mdtraj
```

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

### Fetch example data if not present

Source: https://github.com/gph82/mdciao/blob/master/mdciao/examples/07.EGFR_Kinase_Inhibitors.ipynb

Checks if the 'example_kinases' directory exists and fetches the example data for EGFR if it does not. This ensures the necessary PDB files are available.

```python
if not os.path.exists("example_kinases"):
    mdciao.examples.fetch_example_data("EGFR");
```

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

### Install and Enable nglview

Source: https://github.com/gph82/mdciao/blob/master/mdciao/examples/01.Tutorial.ipynb

Commands to install the nglview Python package and enable its Jupyter notebook extension.

```bash
pip install nglview
jupyter-nbextension enable nglview --py --sys-prefix

```

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

### Download mdciao repository snapshot

Source: https://github.com/gph82/mdciao/blob/master/doc/installation.md

Download a snapshot of the mdciao repository using wget if Git is not installed. Note that you will need to re-download to get updates.

```bash
wget https://github.com/gph82/mdciao/archive/master.zip
```

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

### Install core dependencies with conda

Source: https://github.com/gph82/mdciao/blob/master/doc/installation.md

If core dependencies like numpy, cython, or mdtraj are not installed properly, use these conda commands to install them individually before installing mdciao.

```bash
conda install cython
conda install numpy
conda install mdtraj -c conda forge
```

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

### Generate an example ContactGroup

Source: https://github.com/gph82/mdciao/blob/master/mdciao/examples/01.Tutorial.ipynb

Create an example `ContactGroup` object for experimentation using `mdciao.examples.ContactGroupL394()`. This is useful for exploring `ContactGroup` methods and attributes without needing a full trajectory.

```python
from mdciao import examples
CG = examples.ContactGroupL394()
CG

```

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

### Install bezier for Python 3.13 Compatibility

Source: https://github.com/gph82/mdciao/blob/master/README.rst

Install the bezier module with specific environment variables to ensure compatibility with Python 3.13, which is required for mdciao.

```bash
BEZIER_NO_EXTENSION="True" BEZIER_IGNORE_VERSION_CHECK="True" pip install bezier
```

```bash
pip install mdciao
```

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

### Install mdciao from local source (editable mode)

Source: https://github.com/gph82/mdciao/blob/master/doc/installation.md

Install mdciao in editable mode from local source files. This links the Python path directly to the source directory, so changes take effect immediately without re-installation.

```bash
python3 -m pip install -e .
```

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

### Install mdciao using pip

Source: https://github.com/gph82/mdciao/blob/master/doc/installation.md

Use this command to install the mdciao package with Python's pip package installer. It is recommended to use a virtual environment.

```bash
pip install mdciao
```

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

### Download Example Trajectory Data

Source: https://github.com/gph82/mdciao/blob/master/mdciao/examples/09.Consensus_Labels.ipynb

Downloads trajectory data for specified GPCR systems using mdciao.examples.fetch_example_data. It iterates through a list of system aliases and downloads the corresponding data, skipping if it already exists.

```python
systems = ["b2ar@Gs",   
           "ghrelin@ghsr" , 
           "mor@muor", 
           "y1_apo"]
for system in systems:
    d = mdciao.examples.fetch_example_data(system, 
                                           unzip=system,
                                           skip_on_existing=True)
```

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

### Install Miniconda on Linux

Source: https://github.com/gph82/mdciao/blob/master/doc/installation.md

Execute this command to install the Miniconda distribution on a Linux system. Follow the on-screen prompts, and consider answering 'no' to make the Anaconda Python interpreter non-default.

```bash
sh Miniconda3-latest-Linux-x86_64.sh
```

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

### Load Example Data for Cov19

Source: https://github.com/gph82/mdciao/blob/master/mdciao/examples/03.Comparing_CGs_Bars.ipynb

Loads pre-computed domain interfaces for the Covid-19 Spike Protein example data. Ensures the example data exists before loading.

```python
import mdciao 
import mdtraj as md 
import numpy as np
import os
if not os.path.exists("example_cov19"):
    mdciao.examples.fetch_example_data("cov19")
interfaces = np.load("example_cov19/interfaces.f_50.t_2.npy",allow_pickle=True)[()]
interfaces = {key:interfaces[key] for key in ['WT', 'K417V', 'N439K','N439K/K417V']}
```

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

### Map Consensus Nomenclature from Online Databases

Source: https://github.com/gph82/mdciao/blob/master/doc/highlights.md

This example demonstrates mapping consensus nomenclature, automatically fetching data from GPCRdb or KLIFS if local files are not found. It provides citations for the databases used and details the mapping of fragments onto the topology.

```text
...
No local file ./adrb2_human.xlsx found, checking online in
https://gpcrdb.org/services/residues/extended/adrb2_human ...done!
Please cite the following reference to the GPCRdb:
 * Kooistra et al, (2021) GPCRdb in 2021: Integrating GPCR sequence, structure and function
   Nucleic Acids Research 49, D335--D343
   https://doi.org/10.1093/nar/gkaa1080
For more information, call mdciao.nomenclature.references()
The GPCR-labels align best with fragments: [3] (first-last: GLU30-LEU340).
Mapping the GPCR fragments onto your topology:
    TM1 with     32 AAs    GLU30@1.29x29   ( 760) -    PHE61@1.60x60   (791 ) (TM1)
   ICL1 with      4 AAs    GLU62@12.48x48  ( 792) -    GLN65@12.51x51  (795 ) (ICL1)
    TM2 with     32 AAs    THR66@2.37x37   ( 796) -    LYS97@2.68x67   (827 ) (TM2)
   ECL1 with      4 AAs    MET98@23.49x49  ( 828) -   PHE101@23.52x52  (831 ) (ECL1)
    TM3 with     36 AAs   GLY102@3.21x21   ( 832) -   SER137@3.56x56   (867 ) (TM3)
   ICL2 with      8 AAs   PRO138@34.50x50  ( 868) -   LEU145@34.57x57  (875 ) (ICL2)
    TM4 with     27 AAs   THR146@4.38x38   ( 876) -   HIS172@4.64x64   (902 ) (TM4)
   ECL2 with     20 AAs   TRP173           ( 903) -   THR195           (922 ) (ECL2)  resSeq jumps
    TM5 with     42 AAs   ASN196@5.35x36   ( 923) -   GLU237@5.76x76   (964 ) (TM5)
   ICL3 with      1 AAs   GLY238           ( 965) -   ARG239           (966 ) (ICL3)
    TM5 with     35 AAs   CYS265@6.27x27   ( 967) -   GLN299@6.61x61   (1001) (TM6)
   ECL2 with      4 AAs   ASP300           (1002) -   ILE303           (1005) (ECL3)
    TM7 with     25 AAs   ARG304@7.31x30   (1006) -   ARG328@7.55x55   (1030) (TM7)
     H8 with     12 AAs   SER329@8.47x47   (1031) -   LEU340@8.58x58   (1042) (H8)
...
Please cite the following reference to the CGN nomenclature:
 * Flock et al, (2015) Universal allosteric mechanism for G$\\alpha$ activation by GPCRs
   Nature 2015 524:7564 524, 173--179
   https://doi.org/10.1038/nature14663
For more information, call mdciao.nomenclature.references()
The CGN-labels align best with fragments: [0] (first-last: LEU4-LEU394).
Mapping the CGN fragments onto your topology:
   G.HN with     33 AAs     LEU4@G.HN.10   (   0) -    VAL36@G.HN.53   (32  ) (G.HN)
 G.hns1 with      3 AAs    TYR37@G.hns1.01 (  33) -    ALA39@G.hns1.03 (35  ) (G.hns1)
   G.S1 with      7 AAs    THR40@G.S1.01   (  36) -    LEU46@G.S1.07   (42  ) (G.S1)
...
 G.hgh4 with     21 AAs   TYR311@G.hgh4.01 ( 270) -   ASP331@G.hgh4.21 (290 ) (G.hgh4)
   G.H4 with     16 AAs   PRO332@G.H4.01   ( 291) -   ARG347@G.H4.17   (306 ) (G.H4)
 G.h4s6 with     11 AAs   ILE348@G.h4s6.01 ( 307) -   TYR358@G.h4s6.20 (317 ) (G.h4s6)
   G.S6 with      5 AAs   CYS359@G.S6.01   ( 318) -   PHE363@G.S6.05   (322 ) (G.S6)
 G.s6h5 with      5 AAs   THR364@G.s6h5.01 ( 323) -   ASP368@G.s6h5.05 (327 ) (G.s6h5)
   G.H5 with     26 AAs   THR369@G.H5.01   ( 328) -   LEU394@G.H5.26   (353 ) (G.H5)
...

```

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

### Load Structure and Fragments

Source: https://github.com/gph82/mdciao/blob/master/mdciao/examples/05.Flareplot_Schemes.ipynb

Loads a PDB structure and extracts fragments from its topology. Ensure mdciao is installed and accessible.

```python
import mdciao
geom = mdciao.cli.pdb("3SN6")
fragments = mdciao.fragments.get_fragments(geom.top)
```

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

### Analyze Molecular Fragments with mdc_fragments.py

Source: https://github.com/gph82/mdciao/blob/master/doc/highlights.md

Run mdc_fragments.py on a .gro file to get an overview of available fragmentation heuristics and their results without computing contacts.

```default
mdc_fragments.py 3SN6.gro
```

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

### Get Fragmentation Heuristics (mdciao)

Source: https://github.com/gph82/mdciao/blob/master/mdciao/examples/01.Tutorial.ipynb

Use mdciao.cli.fragment_overview to apply various fragmentation heuristics to a topology. This method iterates through available heuristics and returns fragment definitions as a dictionary.

```python
frags= mdciao.cli.fragment_overview(xray3SN6.top)
```

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

### List Available mdciao Command Line Tools

Source: https://github.com/gph82/mdciao/blob/master/doc/overview.md

Execute mdc_examples.py without arguments to list all available command-line tools shipped with mdciao. This provides a summary of their functionalities.

```bash
>>> mdc_examples.py
```

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

### mdciao Command Line Tool Usage

Source: https://github.com/gph82/mdciao/blob/master/doc/overview.md

This is the usage information displayed when running 'mdc_examples.py'. It outlines the script's purpose and lists the available command-line tools with brief descriptions.

```text
usage: mdc_examples.py [-h] [-x] [--short_options] clt\n\nWrapper script to showcase and optionally run examples of the\ncommand-line-tools that ship with mdciao.\n\nAvailable command line tools are:\n * mdc_GPCR_overview.py\n * mdc_CGN_overview.py\n * mdc_compare.py\n * mdc_fragments.py\n * mdc_interface.py\n * mdc_neighborhoods.py\n * mdc_pdb.py\n * mdc_residues.py\n * mdc_sites.py\n\nYou can type for example:\n > mdc_interface.py  -h\n to view the command's documentation or\n > mdc_examples.py interf\n to show and/or run an example of that command\n
```

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

### View Help for a Specific Command Line Tool

Source: https://github.com/gph82/mdciao/blob/master/doc/cli_stub.md

To view the documentation for any specific command-line tool, use the `-h` flag when invoking it directly.

```bash
> mdc_interface.py  -h
```

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

### List mdciao notebooks

Source: https://github.com/gph82/mdciao/blob/master/doc/installation.md

After launching the notebooks, use this command within the 'mdciao_notebooks' directory to list available notebook files.

```bash
ls -1
```

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

### Initialize Labeler Objects

Source: https://github.com/gph82/mdciao/blob/master/mdciao/examples/01.Tutorial.ipynb

Create Labeler objects for GPCR and CGN nomenclature. These objects can be reused and their data can be optionally saved to disk.

```python
from mdciao import nomenclature
GPCR = nomenclature.LabelerGPCR("adrb2_human", 
                            #write_to_disk=True 
                           )
CGN = nomenclature.LabelerCGN("gnas2_human", 
                             # write_to_disk=True
                             )
```

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

### Run MDC Notebooks CLI

Source: https://github.com/gph82/mdciao/blob/master/doc/gallery.md

Execute this command from the CLI to create a local, sandboxed copy of the Jupyter notebooks for modification and experimentation.

```bash
mdc_notebooks.py
```

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

### Plotting Frequency Data as Flare Plots

Source: https://github.com/gph82/mdciao/blob/master/mdciao/examples/04.Comparing_CGs_Flares.ipynb

Generate and display flare plots for multiple contact group setups. This code iterates through different interfaces, plots their frequency data, and sets titles indicating the setup and total frequency. It uses a shared axis for comparison and highlights specific residues.

```python
myfig, myax = plt.subplots(2,2,
                           sharex=True,
                           sharey=True, 
                           figsize=(20,20), tight_layout=True)
for (setup, iintf), iax in zip(interfaces.items(),myax.flatten()):
    iintf.plot_freqs_as_flareplot(4.5,         
                                  fragments=mdciao.fragments.get_fragments(iintf.top, "chains", verbose=False),  
                                  fragment_names=fragment_names,
                                  SS="example_cov19/run3-clone0.stride.050.h5",
                                  highlight_residxs=[85,107],
                                  sparse_residues=union,
                                  ax=iax,
                                  subplot=True,
                                 )
    iax.set_title("%s\n$\Sigma$ = %2.1f"%(setup, iintf.frequency_per_contact(4).sum()), fontsize=20)
myfig.tight_layout()
```

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

### Get Fragments from Topology

Source: https://context7.com/gph82/mdciao/llms.txt

Break an mdtraj.Topology into non-overlapping fragments using specified methods like 'lig_resSeq+', 'bonds', or 'chains'.

```python
import mdciao.fragments as mdcfrg
import mdtraj as md

top = md.load("3SN6.pdb").topology

# Default heuristic: 'lig_resSeq+' (puts non-AA residues in their own fragment)
fragments = mdcfrg.get_fragments(top, method="lig_resSeq+")
# Returns a list of arrays, e.g.:
# [array([0,...,348]),   # Galpha
#  array([349,...,688]), # Gbeta
#  ...
#  array([1318])]        # ligand P0G

# Pretty-print fragments
mdcfrg.print_fragments(fragments, top)
# fragment      0 with  349 AAs  THR9 (0) - LEU394 (348)
# fragment      1 with  340 AAs  GLN1 (349) - ASN340 (688)
# ...

# Bond-based fragmentation
fragments_bonds = mdcfrg.get_fragments(top, method="bonds")

# Chain-based fragmentation
fragments_chains = mdcfrg.get_fragments(top, method="chains")
```

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

### Generate Tables and Figures from Command Line

Source: https://github.com/gph82/mdciao/blob/master/doc/highlights.md

Use this command to generate paper-ready tables and figures directly from the command line. The '-ni' flag indicates non-interactive mode, and '-at' shows atom types.

```bash
mdc_neighborhoods.py top.pdb traj.xtc -r L394 --GPCR adrb2_human --CGN gnas2_human -ni -at #ni: not interactive, at: show atom-types
```

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

### Visualize Trajectory with nglview

Source: https://github.com/gph82/mdciao/blob/master/mdciao/examples/01.Tutorial.ipynb

Visualize an mdtraj.Trajectory object using nglview. This code block includes error handling for missing nglview installation.

```python
try:
    import nglview
    iwd = nglview.show_mdtraj(xray3SN6)
except ImportError:
    iwd = None
iwd

```

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

### Download PDB Structure with mdc_pdb.py

Source: https://github.com/gph82/mdciao/blob/master/doc/highlights.md

Use mdc_pdb.py to download a PDB structure and save it as a .gro file. Ensure you cite the relevant publication.

```default
>>> mdc_pdb.py 3SN6 -o 3SN6.gro

Checking https://files.rcsb.org/download/3SN6.pdb ...done
Saving to 3SN6.gro...done
Please cite the following 3rd party publication:
 * Crystal structure of the beta2 adrenergic receptor-Gs protein complex
  Rasmussen, S.G. et al., Nature 2011
  https://doi.org/10.1038/nature10361
```

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

### Set VMD Viewpoint

Source: https://github.com/gph82/mdciao/blob/master/doc/highlights.md

Applies a specific viewpoint to the VMD console, useful for replicating example visualizations. Results may vary with different input files.

```default
molinfo top set {center_matrix rotate_matrix scale_matrix global_matrix} {{{1 0 0 -66.7954} {0 1 0 -66.6322} {0 0 1 -45.2629} {0 0 0 1}} {{-0.688392 0.720507 0.0835694 0} {-0.0925729 0.0269995 -0.995339 0} {-0.719405 -0.692919 0.0481138 0} {0 0 0 1}} {{0.0348044 0 0 0} {0 0.0348044 0 0} {0 0 0.0348044 0} {0 0 0 1}} {{1 0 0 0.15} {0 1 0 0.12} {0 0 1 0} {0 0 0 1}}}
```

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

### Create Consensus Labeler Objects

Source: https://github.com/gph82/mdciao/blob/master/mdciao/examples/08.Manuscript.ipynb

Initializes labeler objects for GPCR and CGN nomenclatures.

```python
GPCR = mdciao.nomenclature.LabelerGPCR("adrb2_human")
CGN = mdciao.nomenclature.LabelerCGN("GNAS2_HUMAN")
```

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

### Get CA Indices for Mapping

Source: https://github.com/gph82/mdciao/blob/master/mdciao/examples/07.EGFR_Kinase_Inhibitors.ipynb

Retrieves the indices of alpha-carbon (CA) atoms for mapping between structures using the KLIFS alignment object. This is a prerequisite for superposing structures.

```python
# We can directly get CA indices to map atoms
KLIFS_alignment.CAidxs
```

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

### Interpret mdciao Neighborhood Output

Source: https://github.com/gph82/mdciao/blob/master/doc/overview.md

This is an example of the terminal output from the mdc_neighborhoods.py command, showing contact frequencies, residue information, and created files. Some headers are omitted for brevity.

```text
...\nThe following 6 contacts capture 5.26 (~97%) of the total frequency 5.43 (over 9 contacts with nonzero frequency at 4.50 Angstrom).\n[...]\n   freq          label            residues  fragments   sum\n1  1.00  L394@frag0 - L388@frag0  353 - 347    0 - 0   1.00\n2  1.00  L394@frag0 - R389@frag0  353 - 348    0 - 0   2.00\n3  0.97  L394@frag0 - L230@frag3  353 - 957    0 - 3   2.97\n4  0.97  L394@frag0 - R385@frag0  353 - 344    0 - 0   3.94\n5  0.80  L394@frag0 - I233@frag3  353 - 960    0 - 3   4.74\n6  0.52  L394@frag0 - K270@frag3  353 - 972    0 - 3   5.26\nThe following files have been created:\n./neighborhood.overall@4.5_Ang.pdf\n./neighborhood.LEU394@frag0@4.5_Ang.dat\n./neighborhood.LEU394@frag0.time_trace@4.5_Ang.pdf\n
```

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

### Define a custom site as a Python dictionary

Source: https://github.com/gph82/mdciao/blob/master/mdciao/examples/01.Tutorial.ipynb

Define a custom site by creating a Python dictionary with 'name' and 'pairs' keys. This dictionary can be directly passed to the `mdciao.cli.sites` function.

```python
my_site = {
    "name":"interface small",
    "pairs": {"AAresSeq": [
        "L394-K270",
        "D381-Q229",
        "Q384-Q229",
        "R385-Q229",
        "D381-K232",
        "Q384-I135"
        ]}}

```

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

### Initialize Labeler Objects

Source: https://github.com/gph82/mdciao/blob/master/mdciao/examples/05.Flareplot_Schemes.ipynb

Initialize LabelerGPCR and LabelerCGN objects for consensus labeling. These objects can be reused with multiple topologies or function calls.

```python
GPCR = mdciao.nomenclature.LabelerGPCR("adrb2_human")
CGN = mdciao.nomenclature.LabelerCGN("gnas2_human")
```

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

### Plotting with Verbose Legend Disabled

Source: https://github.com/gph82/mdciao/blob/master/mdciao/examples/03.Comparing_CGs_Bars.ipynb

This example shows how to disable the legend in the plot using `verbose_legend=False` to reduce visual clutter, in addition to applying identity and lower cutoff values.

```python
mdciao.plots.compare_groups_of_contacts(interfaces,
                                        ctc_cutoff_Ang=4.5,
                                        figsize=(35,5),
                                        remove_identities=True, 
                                        identity_cutoff=.80,
                                        mutations_dict={"V417": "K417",
                                                        "K439": "N439"
                                                       },
                                        lower_cutoff_val=.25,
                                        verbose_legend=False,
                                       );

```

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

### Get CA Indices for Alignment

Source: https://github.com/gph82/mdciao/blob/master/mdciao/examples/09.Consensus_Labels.ipynb

Retrieve the indices of alpha-carbon atoms for alignment, excluding specific transmembrane helices (TM6) and helix H8. This selection is used for structural superposition.

```python
CA_idxs = AC.CAidxs_match("?.*,-6.*,8.*")
```

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

### Run Basic Neighborhood Analysis

Source: https://github.com/gph82/mdciao/blob/master/doc/index.md

This command-line tool calculates residue-residue distances, contact frequencies, and distance distributions from MD simulation files. It requires topology and trajectory files, and specifies residues of interest. Output files include PDF plots and data files.

```bash
mdc_neighborhoods.py top.pdb traj.xtc --residues L394
[...] 
The following 6 contacts capture 5.26 (~97%) of the total frequency 5.43 (over 9 contacts with nonzero frequency at 4.50 Angstrom).
As orientation value, the first 6 ctcs already capture 90.0% of 5.43.
The 6-th contact has a frequency of 0.52.
   freq          label            residues  fragments   sum
1  1.00  L394@frag0 - L388@frag0  353 - 347    0 - 0   1.00
2  1.00  L394@frag0 - R389@frag0  353 - 348    0 - 0   2.00
3  0.97  L394@frag0 - L230@frag3  353 - 957    0 - 3   2.97
4  0.97  L394@frag0 - R385@frag0  353 - 344    0 - 0   3.94
5  0.80  L394@frag0 - I233@frag3  353 - 960    0 - 3   4.74
6  0.52  L394@frag0 - K270@frag3  353 - 972    0 - 3   5.26
The following files have been created:
./neighborhood.overall@4.5_Ang.pdf
./neighborhood.LEU394@frag0@4.5_Ang.dat
./neighborhood.LEU394@frag0.time_trace@4.5_Ang.pdf
```

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

### Clone mdciao GitHub repository

Source: https://github.com/gph82/mdciao/blob/master/doc/installation.md

Clone the mdciao GitHub repository using Git to easily obtain the latest fixes and features by pulling regularly. This is part of the installation from source process.

```bash
git clone https://github.com/gph82/mdciao.git
```

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

### Import mdciao and mdtraj

Source: https://github.com/gph82/mdciao/blob/master/mdciao/examples/08.Manuscript.ipynb

Import necessary libraries for trajectory analysis.

```python
import mdtraj as md
import mdciao
```

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

### Initialize NGLWidget

Source: https://github.com/gph82/mdciao/blob/master/mdciao/examples/09.Consensus_Labels.ipynb

Initialize an NGLWidget instance. This is typically done before adding trajectories or representations for visualization.

```python
iwd = nglview.NGLWidget()
```

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

### Calculate Union of Residue Indices

Source: https://github.com/gph82/mdciao/blob/master/mdciao/examples/04.Comparing_CGs_Flares.ipynb

Calculate the union of all residue indices across different interfaces. This is useful for ensuring that comparisons between setups are based on a consistent set of residues, especially when dealing with point mutations.

```python
union = np.unique(np.vstack([iintf.res_idxs_pairs for iintf in interfaces.values()]))
```

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

### Visualize Representative Frames with NGLView

Source: https://github.com/gph82/mdciao/blob/master/mdciao/examples/09.Consensus_Labels.ipynb

Visualize representative frames from different simulation systems using NGLView. This requires 'repframes' to be populated with trajectory data.

```python
import nglview
from matplotlib import colors as mplcolors
colors = mdciao.plots.color_dict_guesser("tab10", repframes.keys())
iwd = nglview.NGLWidget()
for ii, (system, geom) in enumerate(repframes.items()):
    iwd.add_trajectory(geom)#, [[gpcr_idxs]]), title="test")
    iwd.clear_representations(component=ii)
    iwd.add_cartoon(component=ii, color=mplcolors.to_hex(colors[system]), name=system, radius=.1)
iwd
```

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

### Define and run sites analysis

Source: https://context7.com/gph82/mdciao/llms.txt

Use `mdc_sites.py` to compute frequencies for predefined residue pairs specified in a JSON file. The `-sa` flag enables site analysis.

```bash
# Define a site file
echo '{
  "name": "interface small",
  "pairs": {"AAresSeq": [
    "L394-K270",
    "D381-Q229",
    "Q384-Q229",
    "R385-Q229",
    "D381-K232",
    "Q384-I135"
  ]}
}' > tip.json

# Run sites analysis
mdc_sites.py top.pdb traj.xtc --site tip.json -at -nf -sa

# Files created:
# ./sites.overall@4.5_Ang.pdf
# ./sites.overall@4.5_Ang.dat
```

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

### Get Consensus-MSA for a Specific Region

Source: https://github.com/gph82/mdciao/blob/master/mdciao/examples/09.Consensus_Labels.ipynb

Obtain the consensus Multiple Sequence Alignment (MSA) for a specific region, such as TM3, using the AAresSeq_match method. This highlights conserved patterns within the selected transmembrane helix.

```python
AC.AAresSeq_match("3.*")
```

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

### Create Multi-Panel Flareplot Figure

Source: https://github.com/gph82/mdciao/blob/master/mdciao/examples/04.Comparing_CGs_Flares.ipynb

Generate a 2x2 figure with multiple flareplots by creating a matplotlib subplot grid and plotting each flareplot onto a specific Axes object. This allows for comparative visualization of different setups.

```python
from matplotlib import pyplot as plt
myfig, myax = plt.subplots(2,2,
                           sharex=True,
                           sharey=True, 
                           figsize=(20,20), tight_layout=True)
for (setup, iintf), iax in zip(interfaces.items(),myax.flatten()):
    iintf.plot_freqs_as_flareplot(4.5, 
                                  fragments=mdciao.fragments.get_fragments(iintf.top, "chains", verbose=False), 
                                  fragment_names=fragment_names,
                                  SS="example_cov19/run3-clone0.stride.050.h5",
                                  highlight_residxs=[85,107],
                                  scheme="residues_sparse",
                                  lw=.1,
                                  ax=iax,
                                  subplot=True,
                                 )
    iax.set_title("%s\n$\Sigma$ = %2.1f"%(setup, iintf.frequency_per_contact(4).sum()), fontsize=20)
myfig.tight_layout()
```

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

### Initialize GPCR Nomenclature Objects

Source: https://github.com/gph82/mdciao/blob/master/mdciao/examples/09.Consensus_Labels.ipynb

Initializes LabelerGPCR objects for different GPCR systems using their UniProt entry names. This allows for mapping consensus labels to canonical and topological sequences. Data is written to disk as .xlsx files.

```python
key2GPCR_UniProt = {"b2ar@Gs" :      "adrb2_human", 
                    "ghrelin@ghsr" : "ghsr_human", 
                    "mor@muor" :     "oprm_mouse", 
                    "y1_apo" :       "npy1r_human"
                   }
GPCR = {key : mdciao.nomenclature.LabelerGPCR(val, scheme="BW", 
                                              write_to_disk=True, local_path=key) for key, val in key2GPCR_UniProt.items()}
```

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

### Instantiate Consensus Nomenclature Labelers

Source: https://context7.com/gph82/mdciao/llms.txt

Map consensus residue labels (Ballesteros-Weinstein, CGN, KLIFS) onto a topology. Labels are fetched locally or from databases. Use 'top2labels' to get labels per residue or 'top2frags' to map labels to fragment subdomain definitions.

```python
import mdciao.nomenclature as mdcn
import mdtraj as md

top = md.load("top.pdb").topology

# GPCR labeler: looks up adrb2_human.xlsx locally, or fetches from GPCRdb
GPCR_labeler = mdcn.LabelerGPCR("adrb2_human")
gpcr_labels = GPCR_labeler.top2labels(top)
# gpcr_labels[i] is e.g. "3.50x50" or None for non-GPCR residues

# CGN labeler for G-alpha
CGN_labeler = mdcn.LabelerCGN("gnas2_human")
cgn_labels = CGN_labeler.top2labels(top)
# cgn_labels[i] is e.g. "G.H5.26" or None

# KLIFS labeler for kinases via UniProt Accession Code
KLIFS_labeler = mdcn.LabelerKLIFS("UniProtAC:P31751")
klifs_labels = KLIFS_labeler.top2labels(top)

# Map labels back to fragment subdomain definitions
gpcr_frags = GPCR_labeler.top2frags(top, input_dataframe=GPCR_labeler.most_recent_alignment)
# {'TM1': array([...]), 'ICL1': array([...]), 'TM2': array([...]), ...}

# Look up a residue's consensus label by index
print(gpcr_labels[860])  # e.g. '3.50x50'
```

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

### mdciao.sites.x2site() — Load Site Definitions from JSON

Source: https://context7.com/gph82/mdciao/llms.txt

Parse a contact site definition from a JSON file or dict into a standardized site dictionary used by mdciao.cli.sites().

```APIDOC
## API: `mdciao.sites.x2site()` — Load Site Definitions from JSON

Parse a contact site definition from a JSON file or dict into a standardized site dictionary used by `mdciao.cli.sites()`.

```python
import mdciao.sites as mdcsites

# From a JSON file on disk
site = mdcsites.x2site("tip.json")
print(site["name"])    # e.g. "interface small"
print(site["n_pairs"]) # e.g. 6
print(site["pairs"])
# {'AAresSeq': [['L394', 'K270'], ['D381', 'Q229'], ...]}

# Directly from a dict
site_dict = {
    "name": "my_site",
    "pairs": {
        "AAresSeq": ["L394-K270", "D381-Q229", "Q384-Q229"]
    }
}
site = mdcsites.x2site(site_dict)
print(site["n_pairs"])  # 3

# Use with mdciao.cli.sites()
import mdciao
CG = mdciao.cli.sites(
    [site],
    trajectories="traj.xtc",
    topology="top.pdb",
    ctc_cutoff_Ang=4.5,
    accept_guess=True,
    no_disk=True,
)
```
```

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

### Select Residues for Highlighting

Source: https://github.com/gph82/mdciao/blob/master/mdciao/examples/04.Comparing_CGs_Flares.ipynb

Use residue_selection to identify and select specific residues of interest. This is often a preliminary step before visualization.

```python
mdciao.cli.residue_selection("K417,N439",intfWT.top, fragments=["chains"]);
```

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

### Import necessary libraries

Source: https://github.com/gph82/mdciao/blob/master/mdciao/examples/06.MSA_via_Consensus_Labels.ipynb

Imports the required libraries for mdciao, visualization, and plotting.

```python
import mdciao
import nglview
import matplotlib
```

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

### Consensus Nomenclature Overview with mdc_GPCR_overview.py

Source: https://context7.com/gph82/mdciao/llms.txt

Maps GPCR, G-protein (CGN), or kinase (KLIFS) consensus labels onto a topology file or queries by UniProt/KLIFS identifiers. Can look up from GPCRdb if no local file is found.

```bash
# Map GPCR nomenclature onto a topology — lookup from GPCRdb if no local file found
mdc_GPCR_overview.py adrb2_human --topology top.pdb

# Output (excerpt):
#     TM1 with  32 AAs    GLU30@1.29x29   ( 760) -  PHE61@1.60x60   (791) (TM1)
#    ICL1 with   4 AAs    GLU62@12.48x48  ( 792) -  GLN65@12.51x51  (795) (ICL1)
#     TM2 with  32 AAs    THR66@2.37x37   ( 796) -  LYS97@2.68x67   (827) (TM2)
#     ...

# Map CGN onto a G-alpha topology
mdc_CGN_overview.py gnas2_human --topology top.pdb

# Map KLIFS kinase nomenclature via UniProt Accession Code
mdc_KLIFS_overview.py UniProtAC:P31751 --topology kinase.pdb
```

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

### Compare Contact Frequencies with mdc_compare.py

Source: https://context7.com/gph82/mdciao/llms.txt

Compares `.dat` frequency files from different simulations or crystal structures to identify changed contacts. Requires pre-computed neighborhood files.

```bash
# Download crystal structure and compute its neighborhoods
mdc_pdb.py 3SN6
mdc_neighborhoods.py 3SN6.pdb 3SN6.pdb -r R131 -nf -o 3SN6.X

# Compute neighborhoods from MD simulation
mdc_neighborhoods.py top.pdb traj.xtc -r R131 -nf -o 3SN6.MD

# Compare both
mdc_compare.py 3SN6.X.ARG131@4.5_Ang.dat 3SN6.MD.ARG131@4.5_Ang.dat \
    -k Xray,MD -t "3SN6 cutoff 4.5AA" -a R131

# Output:
# These interactions are not shared:
# I325, I72, V222
# Their cumulative ctc freq is 1.07.
# Created files:
# freq_comparison.pdf
# freq_comparison.xlsx
```

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

### Plotting All Residues with Flareplot

Source: https://github.com/gph82/mdciao/blob/master/mdciao/examples/05.Flareplot_Schemes.ipynb

Use the 'all' scheme to plot as many residues as possible. This is useful when you want to visualize all available residue information, especially when a topology is present. The output can be saved to a PDF file for external viewing and zooming.

```python
ifig, iax, flareplot_attrs = intf.plot_freqs_as_flareplot(3.5, scheme="all");
ifig.savefig("flare.all.pdf")
```

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

### Process PDB files and extract fragments

Source: https://github.com/gph82/mdciao/blob/master/mdciao/examples/07.EGFR_Kinase_Inhibitors.ipynb

Iterates through all PDB files in the 'example_kinases' directory, prints their paths, and extracts molecular fragments using mdciao.fragments.get_fragments.

```python
for pdb in sorted(glob("example_kinases/*.pdb")):
    print(pdb)
    mdciao.fragments.get_fragments(pdb)
    print()
```

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

### Load Site Definitions from JSON

Source: https://context7.com/gph82/mdciao/llms.txt

Parse a contact site definition from a JSON file or dict into a standardized site dictionary. This dictionary can then be used with mdciao.cli.sites().

```python
import mdciao.sites as mdcsites
import mdciao

# From a JSON file on disk
site = mdcsites.x2site("tip.json")
print(site["name"])    # e.g. "interface small"
print(site["n_pairs"]) # e.g. 6
print(site["pairs"])
# {'AAresSeq': [['L394', 'K270'], ['D381', 'Q229'], ...]}

# Directly from a dict
site_dict = {
    "name": "my_site",
    "pairs": {
        "AAresSeq": ["L394-K270", "D381-Q229", "Q384-Q229"]
    }
}
site = mdcsites.x2site(site_dict)
print(site["n_pairs"])  # 3

# Use with mdciao.cli.sites()
CG = mdciao.cli.sites(
    [site],
    trajectories="traj.xtc",
    topology="top.pdb",
    ctc_cutoff_Ang=4.5,
    accept_guess=True,
    no_disk=True,
)
```

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

### Map Custom Topology and Trajectory Files

Source: https://github.com/gph82/mdciao/blob/master/mdciao/examples/09.Consensus_Labels.ipynb

Defines dictionaries to map system names to custom topology and trajectory filenames. This is useful when your files do not follow the default naming conventions.

```python
alias = {"b2ar@Gs" :       "adrb2", 
             "ghrelin@ghsr" : "ghsr",
             "mor@muor" :     "muor", 
             "y1_apo" :       "y1"
           }
#these are just examples of possible other topology filenames.
top = {"adrb2" :   "adrb2/prot1.pdb",  
       "ghsr" :    "ghrelin/system.pdb", 
       "muor" :    "muor/muor.pdb", 
       "y1"   :    "y1/top.pdb"
      }
#these are just examples of possible other trajectory filenames.
trajs = {"adrb2" :   "adrb2/traj.xtc",  
        "ghsr" :     "ghrelin/traj1.xtc", "ghrelin/traj2.xtc",
        "muor" :     "muor/run*.xtc", 
        "y1"   :     "y1/run1.xtc"
      }
```

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

### Run mdc_neighborhoods.py for Contact Analysis

Source: https://github.com/gph82/mdciao/blob/master/doc/highlights.md

Use this script to identify and quantify contacts in molecular dynamics simulations. Specify the PDB and trajectory files, the residue of interest, and output file prefix. The output lists contacts by frequency and residue.

```default
>>> mdc_neighborhoods.py top.pdb traj.xtc -r R131 -nf -o 3SN6.MD
...
The following 6 contacts capture 3.15 (~99%) of the total frequency 3.17 (over 7 contacts with nonzero frequency at 4.50 Angstrom).
As orientation value, the first 4 ctcs already capture 90.0% of 3.17.
The 4-th contact has a frequency of 0.39.
   freq    label       residues  fragments   sum
1  0.99  R131 - Y391   861 - 350    0 - 0   0.99
2  0.94  R131 - Y326  861 - 1028    0 - 0   1.92
3  0.76  R131 - Y219   861 - 946    0 - 0   2.69
4  0.39  R131 - I278   861 - 980    0 - 0   3.07
5  0.05  R131 - I325  861 - 1027    0 - 0   3.12
6  0.02  R131 - I72    861 - 802    0 - 0   3.15

...
The following files have been created:
...
./3SN6.MD.ARG131@4.5_Ang.dat
```

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

### Import mdciao Library

Source: https://github.com/gph82/mdciao/blob/master/doc/api_stub.md

This is the standard way to import the mdciao library into your Python scope.

```python
import mdciao
```

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

### Load PDB structures

Source: https://github.com/gph82/mdciao/blob/master/mdciao/examples/06.MSA_via_Consensus_Labels.ipynb

Loads PDB structures for four different GPCR receptors using their PDB IDs.

```python
pdbs = {"OPS"  : mdciao.cli.pdb("3CAP"), 
        "B2AR" : mdciao.cli.pdb("3SN6"), 
        "MUOR" : mdciao.cli.pdb("6DDF"), 
        "DOP"  : mdciao.cli.pdb("7CKW")}
```

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

### Create and Activate Conda Environment

Source: https://github.com/gph82/mdciao/blob/master/doc/installation.md

Use these commands to create a new isolated environment for your project and then activate it. This prevents conflicts with other Python packages or the base environment.

```bash
conda create -n for_mdciao
conda activate for_mdciao
```

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

### Generate Flareplot for Interface Analysis

Source: https://github.com/gph82/mdciao/blob/master/mdciao/examples/08.Manuscript.ipynb

Combines molecular topology, secondary structure, contact pairs, and residue participation into a single flareplot visualization, saving it as an SVG.

```python
ifig, iax, flareplot_attrs  = intf.plot_freqs_as_flareplot(4.5, 
                                                           fragments=fragments, fragment_names = fragment_names,  
                                                           scheme="consensus_sparse", consensus_maps=[GPCR, CGN], 
                                                           aura=intf.frequency_sum_per_residue_idx_dict(4,return_array=True),
                                                           SS=True)
ifig.figure.savefig("flare.svg")
```

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

### Initialize AlignerConsensus for Sequence Alignment

Source: https://github.com/gph82/mdciao/blob/master/mdciao/examples/09.Consensus_Labels.ipynb

Initialize the AlignerConsensus class with receptor information and topology files. This is the first step towards performing sequence-based alignment.

```python
AC = mdciao.nomenclature.AlignerConsensus(GPCR, tops={key : val.top for key, val in repframes.items()})
```