Saving and loading analyses

You can serialize analyses to a delimited-text file, and read saved analyses back using the write_analyses and read_analyses functions.

Saving analyses

If you have analyzed one or more passages into two variables sentences and results (like these examples), here’s how to serialize them.

from arsgrammatica import write_analyses, combined_tokengraph

tokengraph = combined_tokengraph(results)
verbalunits = [vu for result in results for vu in result.verbalunits]

warnings = write_analyses(sentences, verbalunits, tokengraph, "analysis.txt")

write_analyses expects sentences, verbal units, and tokens to be separately organized, and writes them to a named file. We already have a sentences variable. We can extract from the results variable separate lists for verbal units (the nested for comprehension) and the token graph (the combined_tokengraph function).

write_analyses returns a list with any warnings encountered in serializing the analyses. We could check those:

for w in warnings:
    print(f"Warning: {w}")

You may also optionally record in a separate block of the delimited-text file the language model and its reasoning as part of the sentence-by-sentence record, using the optional parameters model and reasoning.

import os

warnings = write_analyses(
    sentences, verbalunits, tokengraph, "analysis.txt",
    model=os.environ["MODEL"],
    reasoning=[result.reasoning for result in results],
)

Reading saved analyses

You can read back a flat list of all the four parts of a serialization with the read_analyses function.

from arsgrammatica import read_analyses

tokengraph, verbalunits, sentences, lm_infos = 
    read_analyses("analysis.txt")

To split up the composite token graph by sentence, use split_analysis_by_sentence.

from arsgrammatica import split_analysis_by_sentence
sentencetokens = split_analysis_by_sentence(tokengraph, verbalunits, sentences)

for (sentence_tokengraph, sentence_verbalunits) in 
    zip(sentences, sentencetokens):
    ...  # work with analysis data per sentence

For details of the serialization format, see the reference documentation