# reference-mmcif

> Reference documentation for PDBx/mmCIF dictionary queries and category lookup

- Author: N283T
- Repository: N283T/dotfiles
- Version: 20260120222824
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/N283T/dotfiles
- Web: https://mule.run/skillshub/@@N283T/dotfiles~reference-mmcif:20260120222824

---

---
name: reference-mmcif
description: Reference documentation for PDBx/mmCIF dictionary queries and category lookup
allowed-tools: Read, Glob, Grep, Bash
timeout: 30000
---

# mmCIF Dictionary Reference

Reference the PDBx/mmCIF dictionary to understand CIF file structure, categories, data items, and type constraints.

## What is the mmCIF Dictionary?

The PDBx/mmCIF dictionary defines the schema for macromolecular crystallographic data:
- **Categories**: Logical groupings of related data (e.g., `atom_site`, `entity`, `cell`)
- **Items**: Individual data fields within categories (e.g., `_atom_site.Cartn_x`)
- **Types**: Data type constraints (integer, float, text, enumeration values)

## Setup

### Dictionary Cache Location

```
~/.cache/mmcif/mmcif_pdbx_v50.dic
```

### Prerequisites

Requires standard Unix utilities: `curl`, `grep`, `sort`

### Download Dictionary

If the dictionary is not cached, download it:

```bash
mkdir -p ~/.cache/mmcif || { echo "Failed to create cache directory"; exit 1; }
curl -sfL -o ~/.cache/mmcif/mmcif_pdbx_v50.dic \
  https://mmcif.wwpdb.org/dictionaries/ascii/mmcif_pdbx_v50.dic \
  || { echo "Failed to download mmCIF dictionary"; exit 1; }
```

### Verify Installation

```bash
test -f ~/.cache/mmcif/mmcif_pdbx_v50.dic && echo "Dictionary found" || echo "Dictionary missing"
```

## Query Methods

### Search for a Category

To find information about a specific category (e.g., `atom_site`):

```bash
# Find category definition
grep -A 50 "^_category\.id[[:space:]]\+atom_site$" ~/.cache/mmcif/mmcif_pdbx_v50.dic

# List all items in a category
grep "^_item\.name[[:space:]]\+_atom_site\." ~/.cache/mmcif/mmcif_pdbx_v50.dic
```

### Search for an Item

To find details about a specific item (e.g., `_atom_site.Cartn_x`):

```bash
# Find item definition
grep -A 20 "_item\.name[[:space:]]\+_atom_site\.Cartn_x" ~/.cache/mmcif/mmcif_pdbx_v50.dic
```

### Get Type Information

```bash
# Find type constraints for an item
grep -A 5 "_item_type\.code[[:space:]]\+_atom_site\.Cartn_x" ~/.cache/mmcif/mmcif_pdbx_v50.dic
```

### List All Categories

```bash
grep "^_category\.id" ~/.cache/mmcif/mmcif_pdbx_v50.dic | sort -u
```

## Common Categories

| Category | Description |
|----------|-------------|
| `atom_site` | Atomic coordinates and properties |
| `atom_type` | Atom type definitions |
| `cell` | Unit cell parameters |
| `entity` | Molecular entities (polymer, non-polymer, water) |
| `entity_poly` | Polymer entity details |
| `entity_poly_seq` | Polymer sequence |
| `struct` | Structure title and descriptors |
| `struct_ref` | Database cross-references |
| `exptl` | Experimental method information |
| `refine` | Refinement statistics |
| `pdbx_struct_assembly` | Biological assembly definitions |

## Workflow

When working with CIF files:

1. **Check cache**: Verify dictionary is downloaded
2. **Identify category**: Determine which category contains your data
3. **List items**: Find available items in that category
4. **Check types**: Verify type constraints before writing values
5. **Check enums**: For enumerated types, verify allowed values

## Online Resources

- Dictionary browser: https://mmcif.wwpdb.org/dictionaries/mmcif_pdbx_v50.dic/Index/
- Category list: https://mmcif.wwpdb.org/dictionaries/mmcif_pdbx_v50.dic/Categories/
- Item list: https://mmcif.wwpdb.org/dictionaries/mmcif_pdbx_v50.dic/Items/

## Usage

```
/reference-mmcif                    # General dictionary reference
/reference-mmcif atom_site          # Look up atom_site category
/reference-mmcif _entity.type       # Look up specific item
```

### Examples

**Find all items in atom_site category:**
```
/reference-mmcif atom_site items
```

**Check type constraints for an item:**
```
/reference-mmcif _atom_site.B_iso_or_equiv type
```

**Find enumeration values:**
```
/reference-mmcif _entity.type enum
```

## Troubleshooting

| Issue | Solution |
|-------|----------|
| Dictionary not found | Run the download command in Setup section |
| Permission denied | Ensure `~/.cache/mmcif/` is writable |
| Grep returns no results | Check exact spelling (names are case-sensitive) |
| Download fails | Check internet connection and URL accessibility |