I/O

Saving and loading quartet profile sets.

Profile Set Formats

SqQuartetProfileSet supports two serialization formats via to_psq(), from_psq(), to_profile_list(), and from_profile_list().

I/O module for SqQuartetProfileSet.

Two formats are supported:

psq (default, .psq) — compact JSON, lossless round-trip:

{
    "taxa": ["A", "B", "C", "D"],
    "profiles": [
        {
            "taxa": ["A", "B", "C", "D"],
            "quartets": [
                {"quartet": {"type": "resolved",
                             "split": {"set1": ["A", "B"], "set2": ["C", "D"]}},
                 "weight": 1.0}
            ],
            "reticulation_leaf": null,
            "profile_weight": 0.85
        }
    ]
}

profile_list (.txt) — plain-text, one profile per line:

# Lines starting with '#' are comments.
SQ a b c d [weight]   # split quarnet: split ab|cd
4C a b c d [weight]   # 4-cycle: circular order a,b,c,d; a is the reticulation leaf

physquirrel.datatypes.io.from_profile_list(profile_list_string: str, **kwargs: Any) → SqQuartetProfileSet

Parse a plain-text profile list string into a SqQuartetProfileSet.

Each non-blank, non-comment line must follow one of two formats:

• SQ a b c d [weight] — a split quarnet with split \(ab|cd\). The first two taxon names go on one side of the split, the last two on the other.

• 4C a b c d [weight] — a 4-cycle with circular order \(a,b,c,d\). The first taxon (\(a\)) is treated as the reticulation leaf.

Lines starting with # are treated as comments and ignored. The weight field is optional and defaults to 1.0.

Parameters:

profile_list_string (str) –

A string in the profile list format, as produced by to_profile_list() or written by hand. Example:

# My quartet profiles
SQ Human Chimp Gorilla Orang 0.9
4C Human Chimp Gorilla Macaque 0.6

Return type:

SqQuartetProfileSet

Raises:

• PhyloZooParseError – If a line has too few tokens.

• PhyloZooFormatError – If a line begins with an unrecognised type tag (not SQ or 4C).

physquirrel.datatypes.io.from_psq(psq_string: str, **kwargs: Any) → SqQuartetProfileSet

Parse a JSON string in .psq format into a SqQuartetProfileSet.

Parameters:

psq_string (str) – A JSON string as produced by to_psq() or by saving a profile set with profileset.save("file.psq").

Return type:

SqQuartetProfileSet

Raises:

• PhyloZooParseError – If psq_string is not valid JSON.

• PhyloZooFormatError – If the JSON structure does not match the expected .psq schema.

physquirrel.datatypes.io.to_profile_list(profileset: SqQuartetProfileSet, **kwargs: Any) → str

Serialize a SqQuartetProfileSet to a plain-text string.

The .txt profile list format has one profile per line:

• SQ a b c d weight — split quarnet with split \(ab|cd\).

• 4C a b c d weight — 4-cycle with circular order \(a,b,c,d\); \(a\) is the reticulation leaf (placed first because it is below the hybrid node).

This format is compatible with the quarnet file format used in earlier versions of physquirrel.

Parameters:

profileset (SqQuartetProfileSet) – The profile set to serialize.

Returns:

A plain-text string. Example output for a profile set with one split quarnet and one 4-cycle:

SQ A B C D 0.85
4C A B C E 0.60

Return type:

str

physquirrel.datatypes.io.to_psq(profileset: SqQuartetProfileSet, **kwargs: Any) → str

Serialize a SqQuartetProfileSet to a JSON string.

The resulting string uses the .psq format, which stores the full taxon set, per-profile quartet weights, reticulation leaf assignments, and profile-level confidence weights. Round-tripping via from_psq() is lossless.

Parameters:

profileset (SqQuartetProfileSet) – The profile set to serialize.

Returns:

A compact JSON string. The top-level object has two keys:

• "taxa" — sorted list of all taxon labels.

• "profiles" — list of profile objects, each with:

  • "taxa" — the four taxon labels for this profile.

  • "quartets" — list of {"quartet": ..., "weight": float} entries. A resolved quartet has type "resolved" with a "split" sub-object; a star quartet has type "star" with a "taxa" list.

  • "reticulation_leaf" — taxon label or null.

  • "profile_weight" — confidence weight for this profile.

Return type:

str