PyNMR-STAR

https://pynmrstar.readthedocs.io/en/latest/
Admin
PyNMR-STAR is a Python module for reading, writing, and manipulating NMR-STAR files, developed by...
Tokens:23,226
Snippets:229
Trust Score:9.6
Update:3 months ago
Show doc for...
Tokens:
Raw
### Initialize and Update Git Submodules

Source: https://pynmrstar.readthedocs.io/en/latest/_sources/usage/unit-test.rst.txt

Required setup step to download the necessary unit test submodules before running tests.

```bash
git submodule init
git submodule update
```

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

### Example NMR-STAR file structure

Source: https://pynmrstar.readthedocs.io/en/latest/usage/nmrstar-introduction.html

A basic representation of an NMR-STAR file showing the entry, saveframe, tag, and loop syntax.

```text
data_dates
    save_special_dates_saveframe_1
        _Special_Dates.Type     Holidays
        loop_
            _Events.Date
            _Events.Description
            12/31/2017 "New Year's Eve"
            01/01/2018 "New Year's Day"
        stop_
    save_
```

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

### Example NMR-STAR saveframe structure

Source: https://pynmrstar.readthedocs.io/en/latest/_sources/usage/quick-start.rst.txt

A raw representation of a software saveframe containing multiple loops.

```text
############################
#  Computer software used  #
############################

save_X-PLOR_NIH
   _Software.Sf_category   software
   _Software.Sf_framecode  X-PLOR_NIH
   _Software.Entry_ID      15000
   _Software.ID            5
   _Software.Name          'X-PLOR NIH'
   _Software.Version       .
   _Software.Details       .

   loop_
      _Vendor.Name
      _Vendor.Address
      _Vendor.Electronic_address
      _Vendor.Entry_ID
      _Vendor.Software_ID

     'CD Schwieters, JJ Kuszewski, N Tjandra and GM Clore'   .   .   15000   5

   stop_

   loop_
      _Task.Task
      _Task.Entry_ID
      _Task.Software_ID

     refinement             15000   5
     'structure solution'   15000   5

   stop_

save_
```

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

### Get NMR-STAR String Representation

Source: https://pynmrstar.readthedocs.io/en/latest/usage/examples.html

Request the string representation of an object to view its NMR-STAR format.

```python
>>> print(ent15000['assembly'])
#############################################
#  Molecular system (assembly) description  #
#############################################

save_assembly
   _Assembly.Sf_category                      assembly
   _Assembly.Sf_framecode                     assembly
   _Assembly.Entry_ID                         15000
   _Assembly.ID                               1
   _Assembly.Name                             F5-Phe-cVHP
   _Assembly.BMRB_code                        .
   _Assembly.Number_of_components             1
   _Assembly.Organic_ligands                  .
   _Assembly.Metal_ions                       .
   _Assembly.Non_standard_bonds               .
   _Assembly.Ambiguous_conformational_states  .
   _Assembly.Ambiguous_chem_comp_sites        .
   _Assembly.Molecules_in_chemical_exchange   .
   _Assembly.Paramagnetic                     no
   _Assembly.Thiol_state                      'all free'
   _Assembly.Molecular_mass                   .
   _Assembly.Enzyme_commission_number         .
   _Assembly.Details                          .
   _Assembly.DB_query_date                    .
   _Assembly.DB_query_revised_last_date       .

   loop_
      _Entity_assembly.ID
      _Entity_assembly.Entity_assembly_name
      _Entity_assembly.Entity_ID
      _Entity_assembly.Entity_label
      _Entity_assembly.Asym_ID
      _Entity_assembly.PDB_chain_ID
      _Entity_assembly.Experimental_data_reported
      _Entity_assembly.Physical_state
      _Entity_assembly.Conformational_isomer
      _Entity_assembly.Chemical_exchange_state
      _Entity_assembly.Magnetic_equivalence_group_code
      _Entity_assembly.Role
      _Entity_assembly.Details
      _Entity_assembly.Entry_ID
      _Entity_assembly.Assembly_ID

     1   F5-Phe-cVHP   1   $F5-Phe-cVHP   K   .   yes   native   no   no   .   .   .   15000   1

   stop_

save_
```

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

### Get Tag Value

Source: https://pynmrstar.readthedocs.io/en/latest/usage/examples.html

Retrieve the value of a specific tag from a saveframe.

```python
>>> ent15000['assembly'].get_tag('ID')
1
```

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

### Create and Modify Saveframes with from_scratch

Source: https://pynmrstar.readthedocs.io/en/latest/_sources/usage/quick-start.rst.txt

Demonstrates initializing an empty saveframe, adding tags, handling tag updates, and appending loops.

```python
# You must provide the saveframe name (the value that comes after "save_" at the start of the saveframe and saveframe
# tag prefix (the value before the "." in a tag name) when creating a saveframe this way
my_sf = pynmrstar.Saveframe.from_scratch("sf_name", "example_sf_category")
print(my_sf)
save_sf_name

save_

# Add a tag using the add_tag() method. Update=True will override existing tag with the same name.
# Update=False will raise an exception if the tag already exists
my_sf.add_tag("tagName1", "tagValue1")
print(my_sf)
save_sf_name
   _example_sf_category.tagName1  tagValue1

save_

my_sf.add_tag("tagName1", "tagValue2", update=False)
ValueError: There is already a tag with the name 'tagName1'.
my_sf.add_tag("tagName1", "tagValue2", update=True)
print(my_sf)
save_sf_name
   _example_sf_category.tagName1  tagValue1

save_
# Alternatively, you can access or write tag values using direct subset access:
my_sf['tagName1']
['tagValue2']
my_sf['tagName2'] = "some value"
print(my_sf)
save_sf_name
   _example_sf_category.tagName1  tagValue2
   _example_sf_category.tagName2  'some value'

save_

# Now add the loop we created before
my_sf.add_loop(lp)
print(my_sf)
save_sf_name
   _example_sf_category.tagName1  tagValue2
   _example_sf_category.tagName2  'some value'

   loop_
      _loop_category.tag1
      _loop_category.tag2
      _loop_category.tag3

     1   2   3
     4   5   6

   stop_

save_

# Now write out our saveframe to a file. Optionally specify format="json" to write in JSON format.
my_sf.write_to_file("file_name.str")
my_sf.write_to_file("file_name.json", format_="json")
```

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

### Entry.from_scratch

Source: https://pynmrstar.readthedocs.io/en/latest/usage/full.html

Creates an empty entry initialized with an entry ID.

```APIDOC
## Entry.from_scratch(entry_id)

### Description
Create an empty entry that you can programmatically add to.

### Parameters
- **entry_id** (str | int) - Required - The unique identifier for the entry.
```

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

### Importing the library

Source: https://pynmrstar.readthedocs.io/en/latest/_sources/usage/examples.rst.txt

Initialize the pynmrstar module.

```python
import pynmrstar
```

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

### Create and populate a loop

Source: https://pynmrstar.readthedocs.io/en/latest/_sources/usage/examples.rst.txt

Construct a new loop from scratch, add tags, and insert data. Data encapsulation and null value conversion are handled automatically.

```python
>>> new_loop = pynmrstar.Loop.from_scratch()
>>> new_loop.add_tag("_Example.age")
>>> new_loop.add_tag("name")
>>> new_loop.add_tag("description")
>>> new_loop.add_tag("notes")
```

```python
>>> new_loop.add_tag(["_Example.age","name","description","notes"])
```

```python
>>> new_loop.add_data([29,"Jon","A BRMB employee", None])
```

```python
>>> print(new_loop)
   loop_
      _Example.age
      _Example.name
      _Example.description
      _Example.notes

     29   Jon   'A BRMB employee'   .

   stop_
```

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

### Create and Populate a Loop

Source: https://pynmrstar.readthedocs.io/en/latest/usage/examples.html

Construct a new loop from scratch and add tags individually or as a list.

```python
>>> new_loop = pynmrstar.Loop.from_scratch()
>>> new_loop.add_tag("_Example.age")
>>> new_loop.add_tag("name")
>>> new_loop.add_tag("description")
>>> new_loop.add_tag("notes")
```

```python
>>> new_loop.add_tag(["_Example.age","name","description","notes"])
```

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

### pynmrstar.Schema.__init__

Source: https://pynmrstar.readthedocs.io/en/latest/usage/full.html

Initializes a BMRB schema object. If no arguments are provided, the latest schema is fetched from the BMRB FTP site.

```APIDOC
## pynmrstar.Schema(schema_file: str | IO = None)

### Description
Initialize a BMRB schema. With no arguments the most up-to-date schema will be fetched from the BMRB FTP site. Otherwise pass a URL or a file to load a schema from using the schema_file keyword argument.

### Parameters
- **schema_file** (str | IO) - Optional - A URL or file path to load the schema from.
```

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

### Entry.from_file

Source: https://pynmrstar.readthedocs.io/en/latest/usage/full.html

Creates an entry by loading data from a file path, URL, or file handle.

```APIDOC
## Entry.from_file(the_file, convert_data_types=False, raise_parse_warnings=False, schema=None)

### Description
Creates an entry by loading in a file. Supports local paths, pathlib.Path objects, open file handles, or remote URLs (http, https, ftp).

### Parameters
- **the_file** (str | Path | TextIO | BinaryIO) - Required - The file path or handle to load.
- **convert_data_types** (bool) - Optional - If True, converts data to corresponding Python types based on the BMRB schema.
- **raise_parse_warnings** (bool) - Optional - If True, raises a ParsingError instead of logging warnings for non-valid issues.
- **schema** (Schema) - Optional - A custom schema object to use.
```

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

### Entry.from_string

Source: https://pynmrstar.readthedocs.io/en/latest/usage/full.html

Creates an entry by parsing a provided string.

```APIDOC
## Entry.from_string(the_string, convert_data_types=False, raise_parse_warnings=False, schema=None)

### Description
Create an entry by parsing a string.

### Parameters
- **the_string** (str) - Required - The string content to parse.
- **convert_data_types** (bool) - Optional - If True, converts data to corresponding Python types.
- **raise_parse_warnings** (bool) - Optional - If True, raises a ParsingError for non-valid issues.
- **schema** (Schema) - Optional - A custom schema object to use.
```

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

### Entry.from_template

Source: https://pynmrstar.readthedocs.io/en/latest/usage/full.html

Creates an entry populated with saveframes and loops from the schema.

```APIDOC
## Entry.from_template(entry_id, all_tags=False, default_values=False, schema=None)

### Description
Create an entry that has all of the saveframes and loops from the schema present. No values will be assigned.

### Parameters
- **entry_id** (str) - Required - The entry ID.
- **all_tags** (bool) - Optional - If True, includes all tags instead of just mandatory ones.
- **default_values** (bool) - Optional - If True, inserts default values from the schema.
- **schema** (Schema) - Optional - A custom schema object to use.
```

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

### Loop.from_file

Source: https://pynmrstar.readthedocs.io/en/latest/usage/full.html

Creates a loop by loading data from a file.

```APIDOC
## Loop.from_file(the_file, csv=False, convert_data_types=False, raise_parse_warnings=False, schema=None)

### Description
Create a loop by loading in a file. Supports local paths, file handles, and remote URLs (http/https/ftp).

### Parameters
- **the_file** (str | Path | TextIO | BinaryIO) - Required - The file path or handle.
- **csv** (bool) - Optional - Set to True if the file is a CSV.
- **convert_data_types** (bool) - Optional - Automatically convert data to Python types based on BMRB schema.
- **raise_parse_warnings** (bool) - Optional - Raise ParsingError on non-valid issues instead of logging warnings.
- **schema** (Schema) - Optional - Custom schema object.
```

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

### Manage and validate BMRB schema loops

Source: https://pynmrstar.readthedocs.io/en/latest/usage/quick-start.html

Create a loop from scratch, populate it with data, sort tags to match the BMRB schema, and perform validation checks.

```python
# Create the loop with the proper category
my_cs_loop = pynmrstar.Loop.from_scratch("Atom_chem_shift")
# Add the tags we will fill
my_cs_loop.add_tag(['Comp_ID', 'Atom_ID', 'Comp_index_ID', 'Atom_type', 'Val', 'Val_err'])
print(my_cs_loop)
   loop_
      _Atom_chem_shift.Comp_ID
      _Atom_chem_shift.Atom_ID
      _Atom_chem_shift.Comp_Index_ID
      _Atom_chem_shift.Atom_type
      _Atom_chem_shift.Val
      _Atom_chem_shift.Val_err


   stop_
# Populate the data array
my_cs_loop.data = [['SER', 'H',  '2', 'H', '9.3070', '0.01'],
                       ['SER', 'HA', '2', 'H', '4.5970', '0.01'],
                       ['SER', 'HB2', '2', 'H', '4.3010', '0.01']]
print(my_cs_loop)
   loop_
      _Atom_chem_shift.Comp_ID
      _Atom_chem_shift.Atom_ID
      _Atom_chem_shift.Comp_Index_ID
      _Atom_chem_shift.Atom_type
      _Atom_chem_shift.Val
      _Atom_chem_shift.Val_err

     SER   H     2   H   9.3070   0.01
     SER   HA    2   H   4.5970   0.01
     SER   HB2   2   H   4.3010   0.01

   stop_

# Now lets sort the tags to match the BMRB schema
my_cs_loop.sort_tags()
# You can see that the Comp_index_ID tag has been moved to the front to match the BMRB standard
print(my_cs_loop)
   loop_
      _Atom_chem_shift.Comp_index_ID
      _Atom_chem_shift.Comp_ID
      _Atom_chem_shift.Atom_ID
      _Atom_chem_shift.Atom_type
      _Atom_chem_shift.Val
      _Atom_chem_shift.Val_err

     2   SER   H     H   9.3070   0.01
     2   SER   HA    H   4.5970   0.01
     2   SER   HB2   H   4.3010   0.01

   stop_

# Check for any errors - returns a list of errors. No errors here:
print(my_cs_loop.validate())
[]
# Let us now set 'Comp_index_ID' to have an invalid value
my_cs_loop.data[0][0] = "invalid"
# You can see that there is now a validation error - the data doesn't match the specified type
print(my_cs_loop.validate())
["Value does not match specification: '_Atom_chem_shift.Comp_index_ID':'invalid' on line '0 tag 0 of loop'.\n     Type specified: int\n     Regular expression for type: '-?[0-9]+'"]
# If you use the pynmrstar.validate(object) function, it will print the report in a human-readable format
pynmrstar.validate(my_cs_loop)
1: Value does not match specification: '_Atom_chem_shift.Comp_index_ID':'invalid' on line '0 tag 0 of loop'.
     Type specified: int
     Regular expression for type: '-?[0-9]+'

# Finally, add in any tags that you didn't have a value for
my_cs_loop.add_missing_tags()
# You can see that all the standard "Atom_chem_shift" loop tags have been added, and their values
# all set to a logical null value - "."
print(my_cs_loop)

   loop_
      _Atom_chem_shift.ID
      _Atom_chem_shift.Assembly_atom_ID
      _Atom_chem_shift.Entity_assembly_ID
      _Atom_chem_shift.Entity_ID
      _Atom_chem_shift.Comp_index_ID
      _Atom_chem_shift.Seq_ID
      _Atom_chem_shift.Comp_ID
      _Atom_chem_shift.Atom_ID
      _Atom_chem_shift.Atom_type
      _Atom_chem_shift.Atom_isotope_number
      _Atom_chem_shift.Val
      _Atom_chem_shift.Val_err
      _Atom_chem_shift.Assign_fig_of_merit
      _Atom_chem_shift.Ambiguity_code
      _Atom_chem_shift.Ambiguity_set_ID
      _Atom_chem_shift.Occupancy
      _Atom_chem_shift.Resonance_ID
      _Atom_chem_shift.Auth_entity_assembly_ID
      _Atom_chem_shift.Auth_asym_ID
      _Atom_chem_shift.Auth_seq_ID
      _Atom_chem_shift.Auth_comp_ID
      _Atom_chem_shift.Auth_atom_ID
      _Atom_chem_shift.Details
      _Atom_chem_shift.Entry_ID
      _Atom_chem_shift.Assigned_chem_shift_list_ID

     .   .   .   .   invalid   .   SER   H     H   .   9.3070   0.01   .   .   .   .   .   .   .   .   .   .   .   .   .
     .   .   .   .   2         .   SER   HA    H   .   4.5970   0.01   .   .   .   .   .   .   .   .   .   .   .   .   .
     .   .   .   .   2         .   SER   HB2   H   .   4.3010   0.01   .   .   .   .   .   .   .   .   .   .   .   .   .

   stop_
```

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

### Retrieving tags using get_tag and get_tags

Source: https://pynmrstar.readthedocs.io/en/latest/_sources/usage/quick-start.rst.txt

Demonstrates fetching specific tag values or multiple tags as a dictionary from an entry.

```python
entry15000.get_tag('Task.Task')
```

```python
entry15000.get_tags(['_NMR_spectrometer.Manufacturer', '_NMR_spectrometer.Model', '_NMR_spectrometer.Field_strength'])
```

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

### Entry.from_database

Source: https://pynmrstar.readthedocs.io/en/latest/usage/full.html

Creates an Entry object by fetching the most up-to-date data from the public BMRB server.

```APIDOC
## Entry.from_database(entry_num, convert_data_types=False, schema=None)

### Description
Fetches an entry from the public BMRB server and initializes an Entry object. Requires an active internet connection.

### Parameters
- **entry_num** (str | int) - Required - The ID of the BMRB entry to fetch.
- **convert_data_types** (bool) - Optional - If True, converts data types based on the BMRB schema (e.g., floats to decimal.Decimal).
- **schema** (Schema) - Optional - A custom schema object to use for validation and type conversion.
```

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

### Create a Loop from Template

Source: https://pynmrstar.readthedocs.io/en/latest/_sources/usage/quick-start.rst.txt

Initializes a loop structure based on a predefined BMRB schema template.

```python
chemical_shifts = pynmrstar.Loop.from_template('atom_chem_shift_list')
print(chemical_shifts)
```

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

### Entry.format

Source: https://pynmrstar.readthedocs.io/en/latest/usage/full.html

Returns the entry as a formatted string in STAR format with customizable options.

```APIDOC
## Entry.format(skip_empty_loops=True, skip_empty_tags=False, show_comments=True)

### Description
Serializes the Entry object into a STAR-formatted string. Allows fine-grained control over the output format.

### Parameters
- **skip_empty_loops** (bool) - Optional - If True, omits loops that contain no tags.
- **skip_empty_tags** (bool) - Optional - If True, omits tags that have no non-null values.
- **show_comments** (bool) - Optional - If True, includes standard comments before saveframes.
```

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

### Create a Saveframe from Template

Source: https://pynmrstar.readthedocs.io/en/latest/_sources/usage/quick-start.rst.txt

Initializes a saveframe with tags pre-filled from the BMRB schema based on the provided category.

```python
my_sf = pynmrstar.Saveframe.from_template("assigned_chemical_shifts")
print(my_sf)
```

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

### Create and Validate NMR-STAR Loops

Source: https://pynmrstar.readthedocs.io/en/latest/_sources/usage/quick-start.rst.txt

Demonstrates the lifecycle of a loop object including initialization, data population, tag sorting, and schema validation.

```python
# Create the loop with the proper category
my_cs_loop = pynmrstar.Loop.from_scratch("Atom_chem_shift")
# Add the tags we will fill
my_cs_loop.add_tag(['Comp_ID', 'Atom_ID', 'Comp_index_ID', 'Atom_type', 'Val', 'Val_err'])
print(my_cs_loop)
   loop_
      _Atom_chem_shift.Comp_ID
      _Atom_chem_shift.Atom_ID
      _Atom_chem_shift.Comp_Index_ID
      _Atom_chem_shift.Atom_type
      _Atom_chem_shift.Val
      _Atom_chem_shift.Val_err


   stop_
# Populate the data array
my_cs_loop.data = [['SER', 'H',  '2', 'H', '9.3070', '0.01'],
                       ['SER', 'HA', '2', 'H', '4.5970', '0.01'],
                       ['SER', 'HB2', '2', 'H', '4.3010', '0.01']]
print(my_cs_loop)
   loop_
      _Atom_chem_shift.Comp_ID
      _Atom_chem_shift.Atom_ID
      _Atom_chem_shift.Comp_Index_ID
      _Atom_chem_shift.Atom_type
      _Atom_chem_shift.Val
      _Atom_chem_shift.Val_err

     SER   H     2   H   9.3070   0.01
     SER   HA    2   H   4.5970   0.01
     SER   HB2   2   H   4.3010   0.01

   stop_

# Now lets sort the tags to match the BMRB schema
my_cs_loop.sort_tags()
# You can see that the Comp_index_ID tag has been moved to the front to match the BMRB standard
print(my_cs_loop)
   loop_
      _Atom_chem_shift.Comp_index_ID
      _Atom_chem_shift.Comp_ID
      _Atom_chem_shift.Atom_ID
      _Atom_chem_shift.Atom_type
      _Atom_chem_shift.Val
      _Atom_chem_shift.Val_err

     2   SER   H     H   9.3070   0.01
     2   SER   HA    H   4.5970   0.01
     2   SER   HB2   H   4.3010   0.01

   stop_

# Check for any errors - returns a list of errors. No errors here:
print(my_cs_loop.validate())
[]
# Let us now set 'Comp_index_ID' to have an invalid value
my_cs_loop.data[0][0] = "invalid"
# You can see that there is now a validation error - the data doesn't match the specified type
print(my_cs_loop.validate())
["Value does not match specification: '_Atom_chem_shift.Comp_index_ID':'invalid' on line '0 tag 0 of loop'.\n     Type specified: int\n     Regular expression for type: '-?[0-9]+'"]
# If you use the pynmrstar.validate(object) function, it will print the report in a human-readable format
pynmrstar.validate(my_cs_loop)
1: Value does not match specification: '_Atom_chem_shift.Comp_index_ID':'invalid' on line '0 tag 0 of loop'.
     Type specified: int
     Regular expression for type: '-?[0-9]+'

# Finally, add in any tags that you didn't have a value for
my_cs_loop.add_missing_tags()
# You can see that all the standard "Atom_chem_shift" loop tags have been added, and their values
# all set to a logical null value - "."
print(my_cs_loop)
```

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

### Entry.print_tree

Source: https://pynmrstar.readthedocs.io/en/latest/usage/full.html

Prints a summary of the entry structure.

```APIDOC
## Entry.print_tree()

### Description
Prints a summary, tree style, of the frames and loops in the entry.
```

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

### Initialize Saveframe from Template

Source: https://pynmrstar.readthedocs.io/en/latest/usage/quick-start.html

Initializes a saveframe using a predefined template name.

```python
my_sf = pynmrstar.Saveframe.from_template("assigned_chemical_shifts")
print(my_sf)
     ###################################
     #  Assigned chemical shift lists  #
     ###################################

###################################################################
#       Chemical Shift Ambiguity Index Value Definitions          #
#                                                                 #
# The values other than 1 are used for those atoms with different #
# chemical shifts that cannot be assigned to stereospecific atoms #
# or to specific residues or chains.                              #
#                                                                 #
#   Index Value            Definition                             #
#                                                                 #
#      1             Unique (including isolated methyl protons,   #
#                         geminal atoms, and geminal methyl       #
#                         groups with identical chemical shifts)  #
#                         (e.g. ILE HD11, HD12, HD13 protons)     #
#      2             Ambiguity of geminal atoms or geminal methyl #
#                         proton groups (e.g. ASP HB2 and HB3     #
#                         protons, LEU CD1 and CD2 carbons, or    #
#                         LEU HD11, HD12, HD13 and HD21, HD22,    #
#                         HD23 methyl protons)                    #
#      3             Aromatic atoms on opposite sides of          #
#                         symmetrical rings (e.g. TYR HE1 and HE2 #
#                         protons)                                #
#      4             Intraresidue ambiguities (e.g. LYS HG and    #
#                         HD protons or TRP HZ2 and HZ3 protons)  #
#      5             Interresidue ambiguities (LYS 12 vs. LYS 27) #
#      6             Intermolecular ambiguities (e.g. ASP 31 CA   #
#                         in monomer 1 and ASP 31 CA in monomer 2 #
#                         of an asymmetrical homodimer, duplex    #
#                         DNA assignments, or other assignments   #
#                         that may apply to atoms in one or more  #
#                         molecule in the molecular assembly)     #
#      9             Ambiguous, specific ambiguity not defined    #
#                                                                 #
###################################################################
```

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

### Run Unit Tests via Python Module

Source: https://pynmrstar.readthedocs.io/en/latest/_sources/usage/unit-test.rst.txt

Executes the unit test suite using the pynmrstar module directly.

```bash
python3 -m pynmrstar.unit_tests
```

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

### Inspect Entry Structure

Source: https://pynmrstar.readthedocs.io/en/latest/_sources/usage/quick-start.rst.txt

Visualize the hierarchical structure of the entry, including saveframes and loops.

```python
entry15000.print_tree()
```

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

### Loop.format

Source: https://pynmrstar.readthedocs.io/en/latest/usage/full.html

Returns a string representation of the loop with customizable formatting options.

```APIDOC
## Loop.format(skip_empty_loops=True, skip_empty_tags=False)

### Description
Returns a string representation of the loop. skip_empty_loops will omit printing loops with no tags at all, and skip_empty_tags will omit tags in the loop which have no non-null values.

### Parameters
- **skip_empty_loops** (bool) - Optional - Omit printing loops with no tags.
- **skip_empty_tags** (bool) - Optional - Omit tags with no non-null values.
```

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

### Loop.from_string

Source: https://pynmrstar.readthedocs.io/en/latest/usage/full.html

Creates a loop by parsing a string.

```APIDOC
## Loop.from_string(the_string, csv=False, convert_data_types=False, raise_parse_warnings=False, schema=None)

### Description
Create a loop by parsing a string. Specify csv=True if the string is in CSV format.

### Parameters
- **the_string** (str) - Required - The string to parse.
- **csv** (bool) - Optional - Set to True if the string is CSV format.
- **convert_data_types** (bool) - Optional - Automatically convert data to Python types.
- **raise_parse_warnings** (bool) - Optional - Raise ParsingError on non-valid issues.
- **schema** (Schema) - Optional - Custom schema object.
```

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

### Write entry to file

Source: https://pynmrstar.readthedocs.io/en/latest/_sources/usage/examples.rst.txt

Save a modified entry to disk in NMR-STAR format.

```python
>>> ent15000_2.write_to_file("example_entry.str")
```

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

### Run Unit Tests via Pytest

Source: https://pynmrstar.readthedocs.io/en/latest/_sources/usage/unit-test.rst.txt

Executes the unit test suite using the pytest framework.

```bash
pytest
```

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

### Viewing the entry hierarchy

Source: https://pynmrstar.readthedocs.io/en/latest/_sources/usage/examples.rst.txt

Display the structure of saveframes and loops as a tree.

```python
>>> ent15000.print_tree()
<pynmrstar.Entry '15000' from_database(15000)>
    [0] <pynmrstar.Saveframe 'entry_information'>
        [0] <pynmrstar.Loop '_Entry_author'>
        [1] <pynmrstar.Loop '_SG_project'>
        [2] <pynmrstar.Loop '_Struct_keywords'>
        [3] <pynmrstar.Loop '_Data_set'>
        [4] <pynmrstar.Loop '_Datum'>
        [5] <pynmrstar.Loop '_Release'>
        [6] <pynmrstar.Loop '_Related_entries'>
    [1] <pynmrstar.Saveframe 'citation_1'>
        [0] <pynmrstar.Loop '_Citation_author'>
    [2] <pynmrstar.Saveframe 'assembly'>
        [0] <pynmrstar.Loop '_Entity_assembly'>
    [3] <pynmrstar.Saveframe 'F5-Phe-cVHP'>
        [0] <pynmrstar.Loop '_Entity_db_link'>
        [1] <pynmrstar.Loop '_Entity_comp_index'>
        [2] <pynmrstar.Loop '_Entity_poly_seq'>
    [4] <pynmrstar.Saveframe 'natural_source'>
        [0] <pynmrstar.Loop '_Entity_natural_src'>
    [5] <pynmrstar.Saveframe 'experimental_source'>
        [0] <pynmrstar.Loop '_Entity_experimental_src'>
    [6] <pynmrstar.Saveframe 'chem_comp_PHF'>
        [0] <pynmrstar.Loop '_Chem_comp_descriptor'>
        [1] <pynmrstar.Loop '_Chem_comp_atom'>
        [2] <pynmrstar.Loop '_Chem_comp_bond'>
    [7] <pynmrstar.Saveframe 'unlabeled_sample'>
        [0] <pynmrstar.Loop '_Sample_component'>
    [8] <pynmrstar.Saveframe 'selectively_labeled_sample'>
        [0] <pynmrstar.Loop '_Sample_component'>
    [9] <pynmrstar.Saveframe 'sample_conditions'>
        [0] <pynmrstar.Loop '_Sample_condition_variable'>
    [10] <pynmrstar.Saveframe 'NMRPipe'>
        [0] <pynmrstar.Loop '_Vendor'>
        [1] <pynmrstar.Loop '_Task'>
    [11] <pynmrstar.Saveframe 'PIPP'>
        [0] <pynmrstar.Loop '_Vendor'>
        [1] <pynmrstar.Loop '_Task'>
    [12] <pynmrstar.Saveframe 'SPARKY'>
        [0] <pynmrstar.Loop '_Vendor'>
        [1] <pynmrstar.Loop '_Task'>
    [13] <pynmrstar.Saveframe 'CYANA'>
        [0] <pynmrstar.Loop '_Vendor'>
        [1] <pynmrstar.Loop '_Task'>
    [14] <pynmrstar.Saveframe 'X-PLOR_NIH'>
        [0] <pynmrstar.Loop '_Vendor'>
        [1] <pynmrstar.Loop '_Task'>
    [15] <pynmrstar.Saveframe 'spectrometer_1'>
    [16] <pynmrstar.Saveframe 'spectrometer_2'>
    [17] <pynmrstar.Saveframe 'spectrometer_3'>
    [18] <pynmrstar.Saveframe 'spectrometer_4'>
    [19] <pynmrstar.Saveframe 'spectrometer_5'>
    [20] <pynmrstar.Saveframe 'spectrometer_6'>
    [21] <pynmrstar.Saveframe 'NMR_spectrometer_list'>
        [0] <pynmrstar.Loop '_NMR_spectrometer_view'>
    [22] <pynmrstar.Saveframe 'experiment_list'>
        [0] <pynmrstar.Loop '_Experiment'>
    [23] <pynmrstar.Saveframe 'chemical_shift_reference_1'>
        [0] <pynmrstar.Loop '_Chem_shift_ref'>
    [24] <pynmrstar.Saveframe 'assigned_chem_shift_list_1'>
        [0] <pynmrstar.Loop '_Chem_shift_experiment'>
        [1] <pynmrstar.Loop '_Atom_chem_shift'>
```

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

### Entry.from_json

Source: https://pynmrstar.readthedocs.io/en/latest/usage/full.html

Creates an entry from a JSON dictionary or serialized JSON string.

```APIDOC
## Entry.from_json(json_dict)

### Description
Creates an entry from JSON (serialized or unserialized JSON).

### Parameters
- **json_dict** (dict | str) - Required - The JSON data to load.
```

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

### Retrieve loop data with get_tag

Source: https://pynmrstar.readthedocs.io/en/latest/usage/quick-start.html

Demonstrates accessing a specific category loop and printing its raw content.

```python
print(entry15000.get_loops_by_category("Atom_chem_shift")[0])
   loop_
      _Atom_chem_shift.ID
      _Atom_chem_shift.Assembly_atom_ID
      _Atom_chem_shift.Entity_assembly_ID
      _Atom_chem_shift.Entity_ID
      _Atom_chem_shift.Comp_index_ID
      _Atom_chem_shift.Seq_ID
      _Atom_chem_shift.Comp_ID
      _Atom_chem_shift.Atom_ID
      _Atom_chem_shift.Atom_type
      _Atom_chem_shift.Atom_isotope_number
      _Atom_chem_shift.Val
      _Atom_chem_shift.Val_err
      _Atom_chem_shift.Assign_fig_of_merit
      _Atom_chem_shift.Ambiguity_code
      _Atom_chem_shift.Occupancy
      _Atom_chem_shift.Resonance_ID
      _Atom_chem_shift.Auth_entity_assembly_ID
      _Atom_chem_shift.Auth_asym_ID
      _Atom_chem_shift.Auth_seq_ID
      _Atom_chem_shift.Auth_comp_ID
      _Atom_chem_shift.Auth_atom_ID
      _Atom_chem_shift.Details
      _Atom_chem_shift.Entry_ID
      _Atom_chem_shift.Assigned_chem_shift_list_ID

     1     .   1   1   2    2    SER   H      H   1    9.3070     0.01   .   .   .   .   .   .   2    SER   H     .   15000   1
     2     .   1   1   2    2    SER   HA     H   1    4.5970     0.01   .   .   .   .   .   .   2    SER   HA    .   15000   1
     3     .   1   1   2    2    SER   HB2    H   1    4.3010     0.01   .   .   .   .   .   .   2    SER   HB2   .   15000   1
    ...
```

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

### Load Entry with Type Conversion

Source: https://pynmrstar.readthedocs.io/en/latest/_sources/usage/quick-start.rst.txt

Load an entry from the database with convert_data_types=True to ensure values match the BMRB schema instead of defaulting to strings.

```python
entry15000 = pynmrstar.Entry.from_database(15000, convert_data_types=True)
cs_result_sets = []
for chemical_shift_loop in entry15000.get_loops_by_category("Atom_chem_shift"):
     cs_result_sets.append(chemical_shift_loop.get_tag(['Comp_index_ID', 'Comp_ID', 'Atom_ID', 'Atom_type', 'Val', 'Val_err']))
print(cs_result_sets)
```

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

### print_tree()

Source: https://pynmrstar.readthedocs.io/en/latest/usage/full.html

Prints a tree-style summary of the loop.

```APIDOC
### print_tree()

Prints a summary, tree style, of the loop.
```

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

### Entry.get_json

Source: https://pynmrstar.readthedocs.io/en/latest/usage/full.html

Returns the entry in JSON format or as a dictionary.

```APIDOC
## Entry.get_json(serialize=True)

### Description
Returns the entry in JSON format. If serialize is set to False a dictionary representation of the entry that is serializeable is returned instead.

### Parameters
- **serialize** (bool) - Optional - Whether to return a serialized JSON string or a dictionary.
```

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

### Loading an entry from the database

Source: https://pynmrstar.readthedocs.io/en/latest/_sources/usage/examples.rst.txt

Fetch a BMRB entry directly using its ID.

```python
>>> ent15000 = pynmrstar.Entry.from_database(15000)
```

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

### pynmrstar.utils.diff(entry1, entry2)

Source: https://pynmrstar.readthedocs.io/en/latest/usage/full.html

Prints the differences between two Entry objects.

```APIDOC
## pynmrstar.utils.diff(entry1, entry2)

### Description
Prints the differences between two entries. Non-equal entries will always be detected, but specific differences detected depends on the order of entries.

### Parameters
- **entry1** (Entry) - Required - The first entry to compare.
- **entry2** (Entry) - Required - The second entry to compare.
```

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

### Entry.normalize

Source: https://pynmrstar.readthedocs.io/en/latest/usage/full.html

Sorts and normalizes the entry structure based on a schema.

```APIDOC
## Entry.normalize(schema=None)

### Description
Sorts saveframes, loops, and tags according to the schema provided (or BMRB default if none provided). Also re-assigns ID tag values and updates tag links.

### Parameters
- **schema** (Schema) - Optional - The schema to use for normalization.
```

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

### Add data to a loop using a flat list of values

Source: https://pynmrstar.readthedocs.io/en/latest/usage/full.html

Format 4: A single list of values. Requires rearrange=True if adding multiple rows.

```python
['Jeff', 'Connecticut']                          # one row
['Jeff', 'Connecticut', 'Chad', 'Madison']       # two rows (requires rearrange=True)
```

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

### add_data(data, rearrange=False, convert_data_types=False, schema=None)

Source: https://pynmrstar.readthedocs.io/en/latest/usage/full.html

Adds data to a loop using one of four supported formats: row-oriented dictionaries, column-oriented dictionaries, a matrix of values, or a flat list.

```APIDOC
## add_data

### Description
Adds data to a loop. You can supply data in four canonical formats: row-oriented dictionaries, column-oriented dictionary of lists, matrix of values, or a flat list of values.

### Parameters
- **data** (Dict | List) - Required - The data to add.
- **rearrange** (bool) - Optional - Only used with flat list format to split into rows.
- **convert_data_types** (bool) - Optional - If True, converts values to types defined in schema.
- **schema** (Schema) - Optional - A pynmrstar.Schema instance used for type conversion.
```

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

### Load NMR-STAR Entries

Source: https://pynmrstar.readthedocs.io/en/latest/_sources/usage/quick-start.rst.txt

Load data either from the BMRB database using an ID or from a local file path.

```python
entry15000 = pynmrstar.Entry.from_database(15000)
```

```python
entry = pynmrstar.Entry.from_file("/location/of/the/file.str")
```

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

### Inspect spectral peak list saveframes

Source: https://pynmrstar.readthedocs.io/en/latest/usage/examples.html

Displays the list of identified spectral peak saveframes.

```python
>>> spectral_peaks
[<pynmrstar.Saveframe 'peak_list_1'>,
 <pynmrstar.Saveframe 'peak_list_2'>,
 <pynmrstar.Saveframe 'peak_list_3'>]
```

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

### Entry.get_tags

Source: https://pynmrstar.readthedocs.io/en/latest/usage/full.html

Retrieves values for a list of tags.

```APIDOC
## Entry.get_tags(tags)

### Description
Given a list of tags, get all of the tags and return the results in a dictionary.

### Parameters
- **tags** (list) - Required - A list of tag names.
```

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

### validate

Source: https://pynmrstar.readthedocs.io/en/latest/usage/full.html

Validates the entry against schema and STAR syntax rules.

```APIDOC
## validate(validate_schema=True, schema=None, validate_star=True)

### Description
Validate an entry in a variety of ways. Returns a list of errors found. 0-length list indicates no errors found.

### Parameters
- **validate_schema** (bool) - Optional - Determines if the entry is validated against the NMR-STAR schema.
- **schema** (Schema) - Optional - Custom schema to use for validation.
- **validate_star** (bool) - Optional - Determines if the STAR syntax checks are ran.
```

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

### Loop.get_json

Source: https://pynmrstar.readthedocs.io/en/latest/usage/full.html

Returns the loop in JSON format.

```APIDOC
## Loop.get_json(serialize=True)

### Description
Returns the loop in JSON format. If serialize is set to False, a dictionary representation is returned.

### Parameters
- **serialize** (bool) - Optional - If False, returns a dictionary instead of a JSON string.
```

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

### write_to_file(file_name, format, show_comments, skip_empty_loops, skip_empty_tags)

Source: https://pynmrstar.readthedocs.io/en/latest/usage/full.html

Writes the saveframe to a file in the specified format.

```APIDOC
## write_to_file(file_name : str | Path, format_ : str = 'nmrstar', show_comments : bool = True, skip_empty_loops : bool = False, skip_empty_tags : bool = False) -> None

### Description
Writes the saveframe to the specified file in NMR-STAR format.
```

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

### Add data to a loop using column-oriented dictionary of lists

Source: https://pynmrstar.readthedocs.io/en/latest/usage/full.html

Format 2: A dictionary mapping each tag to a list of values. All value-lists must be the same length.

```python
{'name': ['Jeff', 'Chad'],
 'location': ['Connecticut', 'Madison']}
```

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

### Display loop content in NMR-STAR format

Source: https://pynmrstar.readthedocs.io/en/latest/usage/examples.html

Prints the raw NMR-STAR representation of the _Peak_char loop.

```python
>>> print(peak1['_Peak_char'])
   loop_
      _Peak_char.Peak_ID
      _Peak_char.Spectral_dim_ID
      _Peak_char.Chem_shift_val
      _Peak_char.Chem_shift_val_err
      _Peak_char.Line_width_val
      _Peak_char.Line_width_val_err
      _Peak_char.Phase_val
      _Peak_char.Phase_val_err
      _Peak_char.Decay_rate_val
      _Peak_char.Decay_rate_val_err
      _Peak_char.Coupling_pattern
      _Peak_char.Bounding_box_upper_val
      _Peak_char.Bounding_box_lower_val
      _Peak_char.Bounding_box_range_val
      _Peak_char.Details
      _Peak_char.Derivation_method_ID
      _Peak_char.Entry_ID
      _Peak_char.Spectral_peak_list_ID

     1      1   9.857   .   .   .   .   .   .   .   .   .   .   .   .   .   6577   1
     1      2   4.922   .   .   .   .   .   .   .   .   .   .   .   .   .   6577   1
     2      1   9.857   .   .   .   .   .   .   .   .   .   .   .   .   .   6577   1
     2      2   2.167   .   .   .   .   .   .   .   .   .   .   .   .   .   6577   1
     ...etc...
```

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

### tag_dict

Source: https://pynmrstar.readthedocs.io/en/latest/usage/full.html

Returns a dictionary of tag names and values.

```APIDOC
## tag_dict

### Description
Returns a hash of (tag name).lower() -> tag value.
```

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

### Entry.get_tag

Source: https://pynmrstar.readthedocs.io/en/latest/usage/full.html

Retrieves values for a specific tag.

```APIDOC
## Entry.get_tag(tag, whole_tag=False)

### Description
Given a tag return a list of all values for that tag.

### Parameters
- **tag** (str) - Required - The tag name.
- **whole_tag** (bool) - Optional - If True, returns [tag_name, tag_value] pairs.
```

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

### Inspecting Loop Structures

Source: https://pynmrstar.readthedocs.io/en/latest/_sources/usage/examples.rst.txt

Display the hierarchy of loops within a saveframe and print the raw content of a specific loop.

```python
>>> peak1.print_tree()
<pynmrstar.Saveframe 'peak_list_1'>
    [0] <pynmrstar.Loop '_Spectral_peak_software'>
    [1] <pynmrstar.Loop '_Peak_general_char'>
    [2] <pynmrstar.Loop '_Peak_char'>
    [3] <pynmrstar.Loop '_Assigned_peak_chem_shift'>
```

```python
>>> print(peak1['_Peak_char'])
   loop_
      _Peak_char.Peak_ID
      _Peak_char.Spectral_dim_ID
      _Peak_char.Chem_shift_val
      _Peak_char.Chem_shift_val_err
      _Peak_char.Line_width_val
      _Peak_char.Line_width_val_err
      _Peak_char.Phase_val
      _Peak_char.Phase_val_err
      _Peak_char.Decay_rate_val
      _Peak_char.Decay_rate_val_err
      _Peak_char.Coupling_pattern
      _Peak_char.Bounding_box_upper_val
      _Peak_char.Bounding_box_lower_val
      _Peak_char.Bounding_box_range_val
      _Peak_char.Details
      _Peak_char.Derivation_method_ID
      _Peak_char.Entry_ID
      _Peak_char.Spectral_peak_list_ID

     1      1   9.857   .   .   .   .   .   .   .   .   .   .   .   .   .   6577   1
     1      2   4.922   .   .   .   .   .   .   .   .   .   .   .   .   .   6577   1
     2      1   9.857   .   .   .   .   .   .   .   .   .   .   .   .   .   6577   1
     2      2   2.167   .   .   .   .   .   .   .   .   .   .   .   .   .   6577   1
     ...etc...
```

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

### validate()

Source: https://pynmrstar.readthedocs.io/en/latest/usage/full.html

Validates the loop against schema and STAR syntax rules.

```APIDOC
### validate(validate_schema=True, schema=None, validate_star=True, category=None)

Validate a loop in a variety of ways. Returns a list of errors found. 0-length list indicates no errors found.
```
Tokens:
Raw