Module documentation

Entry class

class pynmrstar.Entry(**kwargs)

An object oriented representation of a BMRB entry. You can initialize this object several ways; (e.g. from a file, from the official database, from scratch) see the class methods below.

__contains__(item: Any)

Check if the given item is present in the entry.

__delitem__(item: Saveframe | int | str) → None

Remove the indicated saveframe.

__eq__(other) → bool

Returns True if this entry is equal to another entry, false if it is not equal.

__getitem__(item: int | str) → Saveframe

Get the indicated saveframe.

__hash__ = None

__init__(**kwargs) → None

You should not directly instantiate an Entry using this method. Instead use the class methods:

Entry.from_database(), Entry.from_file(), Entry.from_string(), Entry.from_scratch(), Entry.from_json(), and Entry.from_template()

__iter__() → Saveframe

Yields each of the saveframes contained within the entry.

__len__() → int

Returns the number of saveframes in the entry.

__repr__() → str

Returns a description of the entry.

__setitem__(key: int | str, item: Saveframe) → None

Set the indicated saveframe.

__str__(skip_empty_loops: bool = False, skip_empty_tags: bool = False, show_comments: bool = True) → str

Returns the entire entry in STAR format as a string.

__weakref__

list of weak references to the object

add_missing_tags(schema: Schema = None, all_tags: bool = False) → None

Automatically adds any missing tags (according to the schema) to all saveframes and loops and sorts the tags.

add_saveframe(frame) → None

Add a saveframe to the entry.

property category_list: List[str]

Returns a list of the unique categories present in the entry.

compare(other) → List[str]

Returns the differences between two entries as a list. Non-equal entries will always be detected, but specific differences detected depends on order of entries.

delete_empty_saveframes() → None

Deprecated. Please use py:meth:pynmrstar.Entry.remove_empty_saveframes.

property empty: bool

Check if the entry has no data. Ignore the structural tags.

property entry_id: str | int

When read, fetches the entry ID.

When set, updates the entry ID for the Entry, and updates all the tags which are foreign keys of the Entry_ID. (For example, Entry.ID and Citation.Entry_ID will be updated, if present.)

format(skip_empty_loops: bool = True, skip_empty_tags: bool = False, show_comments: bool = True) → str

The same as calling str(Entry), except that you can pass options to customize how the entry is printed.

skip_empty_loops will omit printing loops with no tags at all. (A loop with null tags is not “empty”.) skip_empty_tags will omit tags in the saveframes and loops which have no non-null values. show_comments will show the standard comments before a saveframe.

property frame_dict: Dict[str, Saveframe]

Returns a dictionary of saveframe name -> saveframe object mappings.

classmethod from_database(entry_num: str | int, convert_data_types: bool = False, schema: Schema = None)

Create an entry corresponding to the most up to date entry on the public BMRB server. (Requires ability to initiate outbound HTTP connections.)

Setting convert_data_types to True will automatically convert the data loaded from the file into the corresponding python type as determined by loading the standard BMRB schema. This would mean that all floats will be represented as decimal.Decimal objects, all integers will be python int objects, strings and vars will remain strings, and dates will become datetime.date objects. When printing str() is called on all objects. Other that converting uppercase “E”s in scientific notation floats to lowercase “e”s this should not cause any change in the way re-printed NMR-STAR objects are displayed. Specify a custom schema object to use using the schema parameter.

classmethod from_file(the_file: str | Path | TextIO | BinaryIO, convert_data_types: bool = False, raise_parse_warnings: bool = False, schema: Schema = None)

Create an entry by loading in a file. If the_file starts with http://, https://, or ftp:// then we will use those protocols to attempt to open the file. the_file can be a string path, pathlib.Path object, or an open file handle.

Setting convert_data_types to True will automatically convert the data loaded from the file into the corresponding python type as determined by loading the standard BMRB schema. This would mean that all floats will be represented as decimal.Decimal objects, all integers will be python int objects, strings and vars will remain strings, and dates will become datetime.date objects. When printing str() is called on all objects. Other that converting uppercase “E”s in scientific notation floats to lowercase “e”s this should not cause any change in the way re-printed NMR-STAR objects are displayed. Specify a custom schema object to use using the schema parameter.

Setting raise_parse_warnings to True will result in the raising of a ParsingError rather than logging a warning when non-valid (but ignorable) issues are found.

classmethod from_json(json_dict: dict | str)

Create an entry from JSON (serialized or unserialized JSON).

classmethod from_scratch(entry_id: str | int)

Create an empty entry that you can programmatically add to. You must pass a value corresponding to the Entry ID. (The unique identifier “xxx” from “data_xxx”.)

classmethod from_string(the_string: str, convert_data_types: bool = False, raise_parse_warnings: bool = False, schema: Schema = None)

Create an entry by parsing a string.

Setting convert_data_types to True will automatically convert the data loaded from the file into the corresponding python type as determined by loading the standard BMRB schema. This would mean that all floats will be represented as decimal.Decimal objects, all integers will be python int objects, strings and vars will remain strings, and dates will become datetime.date objects. When printing str() is called on all objects. Other that converting uppercase “E”s in scientific notation floats to lowercase “e”s this should not cause any change in the way re-printed NMR-STAR objects are displayed. Specify a custom schema object to use using the schema parameter.

Setting raise_parse_warnings to True will result in the raising of a ParsingError rather than logging a warning when non-valid (but ignorable) issues are found.

classmethod from_template(entry_id, all_tags=False, default_values=False, schema=None) → Entry

Create an entry that has all of the saveframes and loops from the schema present. No values will be assigned. Specify the entry ID when calling this method.

The optional argument ‘all_tags’ forces all tags to be included rather than just the mandatory tags.

The optional argument ‘default_values’ will insert the default values from the schema.

The optional argument ‘schema’ allows providing a custom schema.

get_json(serialize: bool = True) → dict | str

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

get_loops_by_category(value: str) → List[Loop]

Allows fetching loops by category.

get_saveframe_by_name(saveframe_name: str) → Saveframe

Allows fetching a saveframe by name.

get_saveframes_by_category(value: str) → List[Saveframe]

Allows fetching saveframes by category.

get_saveframes_by_tag_and_value(tag_name: str, value: Any) → List[Saveframe]

Allows fetching saveframe(s) by tag and tag value.

get_tag(tag: str, whole_tag: bool = False) → list

Given a tag (E.g. _Assigned_chem_shift_list.Data_file_name) return a list of all values for that tag. Specify whole_tag=True and the [tag_name, tag_value] pair will be returned.

get_tags(tags: list) → Dict[str, list]

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

normalize(schema: Schema | None = None) → None

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 to ID values.

print_tree() → None

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

remove_empty_saveframes() → None

This method will remove all empty saveframes in an entry (the loops in the saveframe must also be empty for the saveframe to be deleted). “Empty” means no values in tags, not no tags present.

remove_saveframe(item: str | List[str] | Tuple[str] | Saveframe | List[Saveframe] | Tuple[Saveframe]) → None

Removes one or more saveframes from the entry. You can remove saveframes either by passing the saveframe object itself, the saveframe name (as a string), or a list or tuple of either.

rename_saveframe(original_name: str, new_name: str) → None

Renames a saveframe and updates all pointers to that saveframe in the entry with the new name.

validate(validate_schema: bool = True, schema: Schema = None, validate_star: bool = True) → List[str]

Validate an entry in a variety of ways. Returns a list of errors found. 0-length list indicates no errors found. By default all validation modes are enabled.

validate_schema - Determines if the entry is validated against the NMR-STAR schema. You can pass your own custom schema if desired, otherwise the cached schema will be used.

validate_star - Determines if the STAR syntax checks are ran.

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

Writes the entry to the specified file in NMR-STAR format.

Optionally specify: show_comments=False to disable the comments that are by default inserted. Ignored when writing json. skip_empty_loops=False to force printing loops with no tags at all (loops with null tags are still printed) skip_empty_tags=True will omit tags in the saveframes and loops which have no non-null values. format_=json to write to the file in JSON format.

Saveframe class

class pynmrstar.Saveframe(**kwargs)

A saveframe object. Create using the class methods, see below.

__contains__(item: any) → bool

Check if the saveframe contains a tag or a loop name.

__delitem__(item: int | str | Loop) → None

Remove the indicated tag or loop.

__eq__(other) → bool

Returns True if this saveframe is equal to another saveframe, False if it is equal.

__getitem__(item: int | str) → list | Loop

Get the indicated loop or tag.

__hash__ = None

__init__(**kwargs) → None

Don’t use this directly. Use the class methods to construct: Saveframe.from_scratch(), Saveframe.from_string(), Saveframe.from_template(), Saveframe.from_file(), Saveframe.from_json()

__iter__() → Iterable[Loop]

Yields each of the loops contained within the saveframe.

__len__() → int

Return the number of loops in this saveframe.

__lt__(other) → bool

Returns True if this saveframe sorts lower than the compared saveframe, false otherwise. The alphabetical ordering of the saveframe category is used to perform the comparison.

__repr__() → str

Returns a description of the saveframe.

__setitem__(key: str | int, item: str | Loop) → None

Set the indicated loop or tag.

__str__(first_in_category: bool = True, skip_empty_loops: bool = False, skip_empty_tags: bool = False, show_comments: bool = True) → str

Returns the saveframe in STAR format as a string. Please use Saveframe.format() when you want to pass arguments.

__weakref__

list of weak references to the object

add_loop(loop_to_add: Loop) → None

Add a loop to the saveframe loops.

add_missing_tags(schema: Schema = None, all_tags: bool = False, recursive: bool = True) → None

Automatically adds any missing tags (according to the schema) and sorts the tags.

Set recursive to False to only operate on the tags in this saveframe, and not those in child loops.

add_tag(name: str, value: Any, update: bool = False, convert_data_types: bool = False, schema: Schema = None) → None

Add a tag to the tag list. Does a bit of validation and parsing.

Set update to True to update a tag if it exists rather than raise an exception.

Set convert_data_types to True to convert the tag value from str to whatever type the tag is as defined in the schema.

Optionally specify a schema if you don’t want to use the default schema.

add_tags(tag_list: list, update: bool = False, convert_data_types: bool = False, schema: Schema = None) → None

Adds multiple tags to the list. Input should be a list of tuples that are either [key, value] or [key]. In the latter case the value will be set to “.”. Set update to true to update a tag if it exists rather than raise an exception.

compare(other) → List[str]

Returns the differences between two saveframes as a list. Non-equal saveframes will always be detected, but specific differences detected depends on order of saveframes.

delete_tag(tag: str) → None

Deprecated, please see pynmrstar.Saveframe.remove_tag().

property empty: bool

Check if the saveframe has no data. Ignore the structural tags.

format(skip_empty_loops: bool = True, skip_empty_tags: bool = False, show_comments: bool = True) → str

The same as calling str(Saveframe), except that you can pass options to customize how the saveframe is printed.

skip_empty_loops will omit printing loops with no tags at all. (A loop with null tags is not “empty”.) skip_empty_tags will omit tags in the saveframe and child loops which have no non-null values. show_comments will show the standard comments before a saveframe.

classmethod from_file(the_file: str | Path | TextIO | BinaryIO, csv: bool = False, convert_data_types: bool = False, raise_parse_warnings: bool = False, schema: Schema = None)

Create a saveframe by loading in a file. Specify csv=True is the file is a CSV file. If the_file starts with http://, https://, or ftp:// then we will use those protocols to attempt to open the file. the_file can be a string path, pathlib.Path object, or an open file handle.

Setting convert_data_types to True will automatically convert the data loaded from the file into the corresponding python type as determined by loading the standard BMRB schema. This would mean that all floats will be represented as decimal.Decimal objects, all integers will be python int objects, strings and vars will remain strings, and dates will become datetime.date objects. When printing str() is called on all objects. Other that converting uppercase “E”s in scientific notation floats to lowercase “e”s this should not cause any change in the way re-printed NMR-STAR objects are displayed. Specify a custom schema object to use using the schema parameter.

Setting raise_parse_warnings to True will result in the raising of a ParsingError rather than logging a warning when non-valid (but ignorable) issues are found.

classmethod from_json(json_dict: dict | str)

Create a saveframe from JSON (serialized or unserialized JSON).

classmethod from_scratch(sf_name: str, tag_prefix: str = None, source: str = 'from_scratch()')

Create an empty saveframe that you can programmatically add to. You may also pass the tag prefix as the second argument. If you do not pass the tag prefix it will be set the first time you add a tag.

classmethod from_string(the_string: str, csv: bool = False, convert_data_types: bool = False, raise_parse_warnings: bool = False, schema: Schema = None)

Create a saveframe by parsing a string. Specify csv=True is the string is in CSV format and not NMR-STAR format.

Setting convert_data_types to True will automatically convert the data loaded from the file into the corresponding python type as determined by loading the standard BMRB schema. This would mean that all floats will be represented as decimal.Decimal objects, all integers will be python int objects, strings and vars will remain strings, and dates will become datetime.date objects. When printing str() is called on all objects. Other that converting uppercase “E”s in scientific notation floats to lowercase “e”s this should not cause any change in the way re-printed NMR-STAR objects are displayed. Specify a custom schema object to use using the schema parameter.

Setting raise_parse_warnings to True will result in the raising of a ParsingError rather than logging a warning when non-valid (but ignorable) issues are found.

classmethod from_template(category: str, name: str = None, entry_id: str | int = None, all_tags: bool = False, default_values: bool = False, schema: Schema = None)

Create a saveframe that has all of the tags and loops from the schema present. No values will be assigned. Specify the category when calling this method. Optionally also provide the name of the saveframe as the ‘name’ argument.

The optional argument ‘all_tags’ forces all tags to be included rather than just the mandatory tags.

The optional argument ‘default_values’ will insert the default values from the schema.

get_data_as_csv(header: bool = True, show_category: bool = True) → str

Return the data contained in the loops, properly CSVd, as a string. Set header to False omit the header. Set show_category to False to omit the loop category from the headers.

get_json(serialize: bool = True) → dict | str

Returns the saveframe in JSON format. If serialize is set to False a dictionary representation of the saveframe that is serializeable is returned.

get_loop(name: str) → Loop

Return a loop based on the loop name (category).

get_loop_by_category(name: str) → Loop

Deprecated. Please use pynmrstar.Saveframe.get_loop() instead.

get_tag(query: str, whole_tag: bool = False) → list

Allows fetching the value of a tag by tag name. Returns a list of all matching tag values.

Specify whole_tag=True and the [tag_name, tag_value] pair will be returned instead of just the value

property loop_dict: Dict[str, Loop]

Returns a hash of loop category -> loop.

loop_iterator() → Iterable[Loop]

Returns an iterator for saveframe loops.

property name: Any

Returns the name of the saveframe.

print_tree() → None

Prints a summary, tree style, of the loops in the saveframe.

remove_loop(item: str | List[str] | Tuple[str] | Loop | List[Loop] | Tuple[Loop]) → None

Removes one or more loops from the saveframe. You can remove loops either by passing the loop object itself, the loop category (as a string), or a list or tuple of either.

remove_tag(item: str | List[str] | Tuple[str]) → None

Removes one or more tags from the saveframe based on tag name(s). Provide either a tag name or a list or tuple containing tag names.

set_tag_prefix(tag_prefix: str) → None

Set the tag prefix for this saveframe.

sort_tags(schema: Schema = None) → None

Sort the tags so they are in the same order as a BMRB schema. Will automatically use the standard schema if none is provided.

property tag_dict: Dict[str, str]

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

tag_iterator() → Iterable[Tuple[str, str]]

Returns an iterator for saveframe tags.

validate(validate_schema: bool = True, schema: Schema = None, validate_star: bool = True)

Validate a saveframe in a variety of ways. Returns a list of errors found. 0-length list indicates no errors found. By default all validation modes are enabled.

validate_schema - Determines if the entry is validated against the NMR-STAR schema. You can pass your own custom schema if desired, otherwise the schema will be fetched from the BMRB servers.

validate_star - Determines if the STAR syntax checks are ran.

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

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

Optionally specify: show_comments=False to disable the comments that are by default inserted. Ignored when writing json. skip_empty_loops=False to force printing loops with no tags at all (loops with null tags are still printed) skip_empty_tags=True will omit tags in the saveframes and loops which have no non-null values. format_=json to write to the file in JSON format.

Loop class

class pynmrstar.Loop(**kwargs)

A BMRB loop object. Create using the class methods, see below.

__contains__(item: Any) → bool

Check if the loop contains one or more tags.

__eq__(other) → bool

Returns True if this loop is equal to another loop, False if it is different.

__getitem__(item: int | str | List[str] | Tuple[str]) → list

Get the indicated row from the data array.

__hash__ = None

__init__(**kwargs) → None

You should not directly instantiate a Loop using this method. Instead use the class methods:

Loop.from_scratch(), Loop.from_string(), Loop.from_template(), Loop.from_file(), Loop.from_json()

__iter__() → Generator[List[Any], Any, None]

Yields each of the rows contained within the loop.

__len__() → int

Return the number of rows of data.

__lt__(other) → bool

Returns True if this loop sorts lower than the compared loop, false otherwise.

__repr__() → str

Returns a description of the loop.

__setitem__(key: str, item: Any) → None

Set all of the instances of a tag to the provided value. If there are 5 rows of data in the loop, you will need to assign a list with 5 elements.

__str__(skip_empty_loops: bool = False, skip_empty_tags: bool = False) → str

Returns the loop in STAR format as a string.

__weakref__

list of weak references to the object

add_data(data: Dict[str, Any] | List[Dict[str, Any]] | Dict[str, List[Any]] | List[List[Any]] | List[Any], rearrange: bool = False, convert_data_types: bool = False, schema: Schema | None = None) → None

Add data to a loop.

You can supply data in four canonical formats. Formats #1 and #2 are the most convenient; the others are retained mainly for legacy code.

1. Row‑oriented dictionaries (preferred) • a list of dictionaries, where each dictionary represents one row:

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

2. Column‑oriented dictionary of lists A dictionary mapping each tag to a list of values (or to a single scalar):

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

   All value‑lists must be the same length; that length determines the number of rows created.

3. Matrix of values A list of lists whose inner order exactly matches the loop’s current tag order:

   [['Jeff', 'Connecticut'],
    ['Chad', 'Madison']]
   

4. Flat list of values A single list whose length is either: • exactly the number of tags (adds one row), or • any multiple of that length when rearrange=True:

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

   This form is discouraged and kept only for backward compatibility.

Parameters:

• data – The data to add, in any of the formats described above.

• rearrange – Only used with format #4. When True the flat list is split into evenly sized rows. Rarely needed outside of old parsers.

• convert_data_types – If True each value is converted to the type defined in schema before insertion.

• schema – A pynmrstar.Schema instance used when convert_data_types is True.

add_data_by_tag(tag_name: str, value) → None

Deprecated: It is recommended to use add_data() instead for most use cases.

Add data to the loop one element at a time, based on tag. Useful when adding data from SANS parsers.

add_missing_tags(schema: Schema = None, all_tags: bool = False) → None

Automatically adds any missing tags (according to the schema), sorts the tags, and renumbers the tags by ordinal.

add_tag(name: str | List[str], ignore_duplicates: bool = False, update_data: bool = False) → None

Add a tag to the tag name list. Does a bit of validation and parsing. Set ignore_duplicates to true to ignore attempts to add the same tag more than once rather than raise an exception.

You can also pass a list of tag names to add more than one tag at a time.

Adding a tag will update the data array to match by adding None values to the rows if you specify update_data=True.

property category: str | None

The loop category (tag prefix).

clear_data() → None

Erases all data in this loop. Does not erase the tag names or loop category.

compare(other) → List[str]

Returns the differences between two loops as a list. Order of loops being compared does not make a difference on the specific errors detected.

delete_data_by_tag_value(tag: str, value: Any, index_tag: str = None) → List[List[Any]]

Deprecated. Please use py:meth:pynmrstar.Loop.remove_data_by_tag_value instead.

delete_tag(tag: str | List[str]) → None

Deprecated. Please use py:meth:pynmrstar.Loop.remove_tag instead.

property empty: bool

Check if the loop has no data.

filter(tag_list: str | List[str] | Tuple[str], ignore_missing_tags: bool = False)

Returns a new loop containing only the specified tags. Specify ignore_missing_tags=True to bypass missing tags rather than raising an error.

format(skip_empty_loops: bool = True, skip_empty_tags: bool = False) → str

The same as calling str(Loop), except that you can pass options to customize how the loop is printed.

skip_empty_loops will omit printing loops with no tags at all. (A loop with null tags is not “empty”.) skip_empty_tags will omit tags in the loop which have no non-null values.

classmethod from_file(the_file: str | Path | TextIO | BinaryIO, csv: bool = False, convert_data_types: bool = False, raise_parse_warnings: bool = False, schema: Schema = None)

Create a loop by loading in a file. Specify csv=True if the file is a CSV file. If the_file starts with http://, https://, or ftp:// then we will use those protocols to attempt to open the file. the_file can be a string path, pathlib.Path object, or an open file handle.

Setting convert_data_types to True will automatically convert the data loaded from the file into the corresponding python type as determined by loading the standard BMRB schema. This would mean that all floats will be represented as decimal.Decimal objects, all integers will be python int objects, strings and vars will remain strings, and dates will become datetime.date objects. When printing str() is called on all objects. Other that converting uppercase “E”s in scientific notation floats to lowercase “e”s this should not cause any change in the way re-printed NMR-STAR objects are displayed. Specify a custom schema object to use using the schema parameter.

Setting raise_parse_warnings to True will result in the raising of a ParsingError rather than logging a warning when non-valid (but ignorable) issues are found.

classmethod from_json(json_dict: dict | str)

Create a loop from JSON (serialized or unserialized JSON).

classmethod from_scratch(category: str = None, source: str = 'from_scratch()')

Create an empty saveframe that you can programmatically add to. You may also pass the tag prefix as the second argument. If you do not pass the tag prefix it will be set the first time you add a tag.

classmethod from_string(the_string: str, csv: bool = False, convert_data_types: bool = False, raise_parse_warnings: bool = False, schema: Schema = None)

Create a loop by parsing a string. Specify csv=True if the string is in CSV format and not NMR-STAR format.

Setting convert_data_types to True will automatically convert the data loaded from the file into the corresponding python type as determined by loading the standard BMRB schema. This would mean that all floats will be represented as decimal.Decimal objects, all integers will be python int objects, strings and vars will remain strings, and dates will become datetime.date objects. When printing str() is called on all objects. Other that converting uppercase “E”s in scientific notation floats to lowercase “e”s this should not cause any change in the way re-printed NMR-STAR objects are displayed. Specify a custom schema object to use using the schema parameter.

Setting raise_parse_warnings to True will result in the raising of a ParsingError rather than logging a warning when non-valid (but ignorable) issues are found.

classmethod from_template(tag_prefix: str, all_tags: bool = False, schema: Schema = None)

Create a loop that has all of the tags from the schema present. No values will be assigned. Specify the tag prefix of the loop.

The optional argument all_tags forces all tags to be included rather than just the mandatory tags.

get_data_as_csv(header: bool = True, show_category: bool = True) → str

Return the data contained in the loops, properly CSVd, as a string. Set header to False to omit the header. Set show_category to false to omit the loop category from the headers.

get_json(serialize: bool = True) → dict | str

Returns the loop in JSON format. If serialize is set to False a dictionary representation of the loop that is serializeable is returned.

get_tag(tags: str | List[str] | None = None, whole_tag: bool = False, dict_result: bool = False) → List[Any] | List[Dict[str, Any]]

Provided a tag name (or a list of tag names) return the selected tags by row as a list of lists. Leave tags unset to fetch all tags.

If whole_tag=True return the full tag name along with the tag value, or if dict_result=True, as the tag key.

If dict_result=True, return the tags as a list of dictionaries in which the tag value points to the tag. Uses the specified capitalization of the tag unless whole_tag is True, in which case it will use the capitalization found in the loop.

get_tag_names() → List[str]

Return the tag names for this entry with the category included. Throws ValueError if the category was never set.

To get the tags without the category, just access them directly using the “tags” attribute.

To fetch tag values use get_tag().

print_tree() → None

Prints a summary, tree style, of the loop.

remove_data_by_tag_value(tag: str, value: Any, index_tag: str = None) → List[List[Any]]

Removes all rows which contain the provided value in the provided tag name. If index_tag is provided, that tag is renumbered starting with 1. Returns the deleted rows.

remove_tag(tag: str | List[str]) → None

Removes one or more tags from the loop based on tag name. Also removes any data for the given tag. Provide either a tag or list of tags.

renumber_rows(index_tag: str, start_value: int = 1, maintain_ordering: bool = False)

Renumber a given tag incrementally. Set start_value to initial value if 1 is not acceptable. Set maintain_ordering to preserve sequence with offset.

E.g. 2,3,3,5 would become 1,2,2,4.

set_category(category: str) → None

Set the category of the loop. Useful if you didn’t know the category at loop creation time.

sort_rows(tags: str | List[str], key: Callable = None) → None

Sort the data in the rows by their values for a given tag or tags. Specify the tags using their names or ordinals. Accepts a list or an int/float. By default we will sort numerically. If that fails we do a string sort. Supply a function as key and we will order the elements based on the keys it provides. See the help for sorted() for more details. If you provide multiple tags to sort by, they are interpreted as increasing order of sort priority.

sort_tags(schema: Schema = None) → None

Rearranges the tag names and data in the loop to match the order from the schema. Uses the BMRB schema unless one is provided.

tag_index(tag_name: str) → int | None

Helper method to do a case-insensitive check for the presence of a given tag in this loop. Returns the index of the tag if found and None if not found.

This is useful if you need to get the index of a certain tag to iterate through the data and modify it.

validate(validate_schema: bool = True, schema: Schema = None, validate_star: bool = True, category: str = None) → List[str]

Validate a loop in a variety of ways. Returns a list of errors found. 0-length list indicates no errors found. By default all validation modes are enabled.

validate_schema - Determines if the entry is validated against the NMR-STAR schema. You can pass your own custom schema if desired, otherwise the schema will be fetched from the BMRB servers.

validate_star - Determines if the STAR syntax checks are ran.

Schema class

class pynmrstar.Schema(schema_file: str | IO = None)

A BMRB schema. Used to validate NMR-STAR files. Unless you need to choose a specific schema version, PyNMR-STAR will automatically load a schema for you. If you do need a specific schema version, you can create an object of this class and then pass it to the methods which allow the specification of a schema.

__init__(schema_file: str | IO = None) → None

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.

add_tag(tag: str, tag_type: str, null_allowed: bool, sf_category: str, loop_flag: bool, after: str = None)

Adds the specified tag to the tag dictionary. You must provide:

1. The full tag as such:

   “_Entry_interview.Sf_category”

2. The tag type which is one of the following:

   “INTEGER” “FLOAT” “CHAR(len)” “VARCHAR(len)” “TEXT” “DATETIME year to day”

3. A python True/False that indicates whether null values are allowed.

4. The sf_category of the parent saveframe.

5. A True/False value which indicates if this tag is a loop tag.

6. Optional: The tag to order this tag behind when normalizing saveframes.

string_representation(search: bool = None) → str

Prints all the tags in the schema if search is not specified and prints the tags that contain the search string if it is.

Exceptions

class pynmrstar.exceptions.ParsingError(message, line_number: int = None)

Indicates that something went wrong when parsing NMR-STAR data. A line number on which the exception occurred will be provided if possible.

class pynmrstar.exceptions.InvalidStateError(message)

Indicates that the data as exists in the PyNMRSTAR objects is not consistent with the NMR-STAR format or dictionary. This often means that internal PyNMRSTAR attributes were modified directly rather than using the appropriate getters/setters, since the library attempts to prevent actions which would lead to such states.

Utilities

This file contains various helper functions.

pynmrstar.utils.diff(entry1: Entry, entry2: Entry) → None

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

pynmrstar.utils.iter_entries(metabolomics: bool = False) → Iterable[Entry]

Returns a generator that will yield an Entry object for every macromolecule entry in the current BMRB database. Perfect for performing an operation across the entire BMRB database. Set metabolomics=True in order to get all the entries in the metabolomics database.

pynmrstar.utils.validate(entry_to_validate: Entry, schema: Schema = None) → None

Prints a validation report of an object.