Skip to content

Metadata reader

convert_category(data, category_name)

Convert a single mmCIF category into a list of dictionaries.

In mmCIF, ? means unknown and . means inapplicable. Both markers are converted to None so that downstream consumers never see raw placeholder strings.

Parameters:

Name Type Description Default
data List[DataContainer]

Parsed mmCIF data blocks.

 required
category_name str

Name of the mmCIF category to extract.

 required

Returns:

Type Description
List[Dict]

List of rows for the selected category, each row represented as a dictionary mapping mmCIF attribute names to their values. Returns an empty list if the category is not present.
Source code in src/rnapolis/metareader.py 
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
def convert_category(data: List[DataContainer], category_name: str) -> List[Dict]:
    """
    Convert a single mmCIF category into a list of dictionaries.

    In mmCIF, ``?`` means *unknown* and ``.`` means *inapplicable*.  Both
    markers are converted to ``None`` so that downstream consumers never
    see raw placeholder strings.

    Args:
        data (List[DataContainer]): Parsed mmCIF data blocks.
        category_name (str): Name of the mmCIF category to extract.

    Returns:
        List of rows for the selected category, each row represented as a dictionary mapping mmCIF attribute names to their values. Returns an empty list if the category is not present.
    """
    category = data[0].getObj(category_name)
    if category:
        result = []
        for row in category.getRowList():
            record = {}
            for attr, value in zip(category.getAttributeList(), row):
                record[attr] = None if value in ("?", ".") else value
            result.append(record)
        return result
    return []

list_metadata(file)

List all metadata categories available in an mmCIF file.

Parameters:

Name Type Description Default
file IO[str]

Open file handle pointing to an mmCIF file.

 required

Returns:

Type Description
List[str]

Names of all mmCIF categories found in the file.
Source code in src/rnapolis/metareader.py 
55
56
57
58
59
60
61
62
63
64
65
66
67
def list_metadata(file: IO[str]) -> List[str]:
    """
    List all metadata categories available in an mmCIF file.

    Args:
        file (IO[str]): Open file handle pointing to an mmCIF file.

    Returns:
        Names of all mmCIF categories found in the file.
    """
    adapter = IoAdapterPy()
    data = adapter.readFile(file.name)
    return data[0].getObjNameList()

main()

Command-line entry point for the metareader tool.

The script:

  • reads an mmCIF file,
  • optionally lists all available metadata categories,
  • extracts selected categories and prints them as JSON,
  • optionally writes each extracted category to a separate CSV file.
Source code in src/rnapolis/metareader.py 
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
def main():
    """Command-line entry point for the ``metareader`` tool.

    The script:

    - reads an mmCIF file,
    - optionally lists all available metadata categories,
    - extracts selected categories and prints them as JSON,
    - optionally writes each extracted category to a separate CSV file.
    """

    parser = argparse.ArgumentParser()
    parser.add_argument("path", help="path to mmCIF file")
    parser.add_argument(
        "--category",
        "-c",
        help="an mmCIF category to extract, you can provide as many as you want (default=struct)",
        action="append",
        default=["struct"],
    )
    parser.add_argument(
        "--list-categories",
        "-l",
        help="read the mmCIF file and list categories available inside",
        action="store_true",
    )
    parser.add_argument(
        "--csv-directory",
        help="directory where to output CSV per each category",
    )
    args = parser.parse_args()

    file = handle_input_file(args.path)

    if args.list_categories:
        for name in list_metadata(file):
            print(name)
    else:
        result = read_metadata(file, args.category)
        print(orjson.dumps(result).decode("utf-8"))

        if args.csv_directory:
            for category in result:
                with open(f"{args.csv_directory}/{category}.csv", "w") as f:
                    df = pd.DataFrame(result[category])
                    df.to_csv(f, index=False)

read_metadata(file, categories)

Read selected metadata categories from an mmCIF file.

Parameters:

Name Type Description Default
file IO[str]

Open file handle pointing to an mmCIF file.

 required
categories List[str]

Names of mmCIF categories to extract (e.g. ["struct"]).

 required

Returns:

Name Type Description
Dict Dict

Mapping from category name to a list of row dictionaries for that category.
Source code in src/rnapolis/metareader.py 
39
40
41
42
43
44
45
46
47
48
49
50
51
52
def read_metadata(file: IO[str], categories: List[str]) -> Dict:
    """
    Read selected metadata categories from an mmCIF file.

    Args:
        file (IO[str]): Open file handle pointing to an mmCIF file.
        categories (List[str]): Names of mmCIF categories to extract (e.g. ``["struct"]``).

    Returns:
        Dict: Mapping from category name to a list of row dictionaries for that category.
    """
    adapter = IoAdapterPy()
    data = adapter.readFile(file.name)
    return {key: convert_category(data, key) for key in categories}