Skip to content

raxmlng

pypythia.raxmlng.RAxMLNG

Class to interact with the RAxML-NG binary.

Parameters:

Name Type Description Default
exe_path Path

Path to the RAxML-NG executable. Defaults to the binary found in the PATH environment variable.

 DEFAULT_RAXMLNG_EXE

Attributes:

Name Type Description
exe_path Path

Path to the RAxML-NG executable.

Raises:

Type Description
FileNotFoundError

If the RAxML-NG executable is not found.
RuntimeError

If the RAxML-NG executable is not working or is not a RAxML-NG executable.
Source code in pypythia/raxmlng.py 
 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
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
class RAxMLNG:
    """Class to interact with the RAxML-NG binary.

    Args:
        exe_path (pathlib.Path, optional): Path to the RAxML-NG executable. Defaults to the binary found in the PATH environment variable.

    Attributes:
        exe_path (pathlib.Path): Path to the RAxML-NG executable.

    Raises:
        FileNotFoundError: If the RAxML-NG executable is not found.
        RuntimeError: If the RAxML-NG executable is not working or is not a RAxML-NG executable.

    """

    def __init__(self, exe_path: Optional[pathlib.Path] = DEFAULT_RAXMLNG_EXE):
        if exe_path is None or not exe_path.exists():
            raise FileNotFoundError("RAxML-NG executable not found.")

        try:
            out = subprocess.check_output([str(exe_path.absolute())], encoding="utf-8")
        except Exception as e:
            raise RuntimeError(
                f"Your RAxML-NG executable does not seem to work. Running `{exe_path}` failed: {e}"
            ) from e

        if not "RAxML-NG" in out:
            raise RuntimeError(
                f"The given executable `{exe_path}` does not seem to be a RAxML-NG executable."
            )

        self.exe_path = exe_path

    def _base_cmd(
        self, msa_file: pathlib.Path, model: str, prefix: pathlib.Path, **kwargs
    ) -> list[str]:
        additional_settings = []
        for key, value in kwargs.items():
            if value is None:
                additional_settings += [f"--{key}"]
            else:
                additional_settings += [f"--{key}", str(value)]

        return [
            str(self.exe_path.absolute()),
            "--msa",
            str(msa_file.absolute()),
            "--model",
            model,
            "--prefix",
            str(prefix.absolute()),
            *additional_settings,
        ]

    def _run_rfdist(
        self, trees_file: pathlib.Path, prefix: pathlib.Path, **kwargs
    ) -> None:
        additional_settings = []
        for key, value in kwargs.items():
            if value is None:
                additional_settings += [f"--{key}"]
            else:
                additional_settings += [f"--{key}", str(value)]
        cmd = [
            str(self.exe_path.absolute()),
            "--rfdist",
            str(trees_file.absolute()),
            "--prefix",
            str(prefix.absolute()),
            *additional_settings,
        ]
        run_raxmlng_command(cmd)

    def infer_parsimony_trees(
        self,
        msa_file: pathlib.Path,
        model: str,
        prefix: pathlib.Path,
        n_trees: int = 24,
        **kwargs,
    ) -> pathlib.Path:
        """Method that infers n_trees using the RAxML-NG implementation of maximum parsimony.

        Args:
            msa_file (pathlib.Path): Filepath pointing to the MSA file.
            model (str): String representation of the substitution model to use. Needs to be a valid RAxML-NG model.
                For example "GTR+G" for DNA data or "LG+G" for protein data.
            prefix (pathlib.Path): Prefix to use when running RAxML-NG.
            n_trees (int): Number of trees to infer. Defaults to 24.
            **kwargs: Additional arguments to pass to the RAxML-NG command.
                The name of the kwarg needs to be a valid RAxML-NG flag.
                For flags with a value pass it like this: "flag=value", for flags without a value pass it like this: "flag=None".
                See https://github.com/amkozlov/raxml-ng for all options.

        Returns:
            Filepath pointing to the inferred maximum parsimony trees.
        """
        cmd = self._base_cmd(
            msa_file, model, prefix, start=None, tree=f"pars{{{n_trees}}}", **kwargs
        )
        run_raxmlng_command(cmd)
        return pathlib.Path(f"{prefix}.raxml.startTree")

    def get_rfdistance_results(
        self, trees_file: pathlib.Path, prefix: pathlib.Path = None, **kwargs
    ) -> tuple[float, float]:
        """Method that computes the number of unique topologies and the relative RF-Distance for the given set of trees.

        Args:
            trees_file (pathlib.Path): Filepath pointing to the file containing the trees.
            prefix (pathlib.Path, optional): Prefix to use when running RAxML-NG. Defaults to None. If None, a temporary directory is used.
            **kwargs: Additional arguments to pass to the RAxML-NG command.
                The name of the kwarg needs to be a valid RAxML-NG flag.
                For flags with a value pass it like this: "flag=value", for flags without a value pass it like this: "flag=None".
                See

        Returns:
            num_topos (float): Number of unique topologies of the given set of trees.
            rel_rfdist (float): Relative RF-Distance of the given set of trees. Computed as average over all pairwise RF-Distances. Value between 0.0 and 1.0.
        """
        with TemporaryDirectory() as tmpdir:
            tmpdir = pathlib.Path(tmpdir)
            if not prefix:
                prefix = tmpdir / "rfdist"
            self._run_rfdist(trees_file, prefix, **kwargs)
            log_file = pathlib.Path(f"{prefix}.raxml.log")
            return get_raxmlng_rfdist_results(log_file)

get_rfdistance_results(trees_file, prefix=None, **kwargs)

Method that computes the number of unique topologies and the relative RF-Distance for the given set of trees.

Parameters:

Name Type Description Default
trees_file Path

Filepath pointing to the file containing the trees.

 required
prefix Path

Prefix to use when running RAxML-NG. Defaults to None. If None, a temporary directory is used.

 None
**kwargs

Additional arguments to pass to the RAxML-NG command. The name of the kwarg needs to be a valid RAxML-NG flag. For flags with a value pass it like this: "flag=value", for flags without a value pass it like this: "flag=None". See

 {}

Returns:

Name Type Description
num_topos float

Number of unique topologies of the given set of trees.
rel_rfdist float

Relative RF-Distance of the given set of trees. Computed as average over all pairwise RF-Distances. Value between 0.0 and 1.0.
Source code in pypythia/raxmlng.py 
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
def get_rfdistance_results(
    self, trees_file: pathlib.Path, prefix: pathlib.Path = None, **kwargs
) -> tuple[float, float]:
    """Method that computes the number of unique topologies and the relative RF-Distance for the given set of trees.

    Args:
        trees_file (pathlib.Path): Filepath pointing to the file containing the trees.
        prefix (pathlib.Path, optional): Prefix to use when running RAxML-NG. Defaults to None. If None, a temporary directory is used.
        **kwargs: Additional arguments to pass to the RAxML-NG command.
            The name of the kwarg needs to be a valid RAxML-NG flag.
            For flags with a value pass it like this: "flag=value", for flags without a value pass it like this: "flag=None".
            See

    Returns:
        num_topos (float): Number of unique topologies of the given set of trees.
        rel_rfdist (float): Relative RF-Distance of the given set of trees. Computed as average over all pairwise RF-Distances. Value between 0.0 and 1.0.
    """
    with TemporaryDirectory() as tmpdir:
        tmpdir = pathlib.Path(tmpdir)
        if not prefix:
            prefix = tmpdir / "rfdist"
        self._run_rfdist(trees_file, prefix, **kwargs)
        log_file = pathlib.Path(f"{prefix}.raxml.log")
        return get_raxmlng_rfdist_results(log_file)

infer_parsimony_trees(msa_file, model, prefix, n_trees=24, **kwargs)

Method that infers n_trees using the RAxML-NG implementation of maximum parsimony.

Parameters:

Name Type Description Default
msa_file Path

Filepath pointing to the MSA file.

 required
model str

String representation of the substitution model to use. Needs to be a valid RAxML-NG model. For example "GTR+G" for DNA data or "LG+G" for protein data.

 required
prefix Path

Prefix to use when running RAxML-NG.

 required
n_trees int

Number of trees to infer. Defaults to 24.

 24
**kwargs

Additional arguments to pass to the RAxML-NG command. The name of the kwarg needs to be a valid RAxML-NG flag. For flags with a value pass it like this: "flag=value", for flags without a value pass it like this: "flag=None". See https://github.com/amkozlov/raxml-ng for all options.

 {}

Returns:

Type Description
Path

Filepath pointing to the inferred maximum parsimony trees.
Source code in pypythia/raxmlng.py 
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
def infer_parsimony_trees(
    self,
    msa_file: pathlib.Path,
    model: str,
    prefix: pathlib.Path,
    n_trees: int = 24,
    **kwargs,
) -> pathlib.Path:
    """Method that infers n_trees using the RAxML-NG implementation of maximum parsimony.

    Args:
        msa_file (pathlib.Path): Filepath pointing to the MSA file.
        model (str): String representation of the substitution model to use. Needs to be a valid RAxML-NG model.
            For example "GTR+G" for DNA data or "LG+G" for protein data.
        prefix (pathlib.Path): Prefix to use when running RAxML-NG.
        n_trees (int): Number of trees to infer. Defaults to 24.
        **kwargs: Additional arguments to pass to the RAxML-NG command.
            The name of the kwarg needs to be a valid RAxML-NG flag.
            For flags with a value pass it like this: "flag=value", for flags without a value pass it like this: "flag=None".
            See https://github.com/amkozlov/raxml-ng for all options.

    Returns:
        Filepath pointing to the inferred maximum parsimony trees.
    """
    cmd = self._base_cmd(
        msa_file, model, prefix, start=None, tree=f"pars{{{n_trees}}}", **kwargs
    )
    run_raxmlng_command(cmd)
    return pathlib.Path(f"{prefix}.raxml.startTree")

pypythia.raxmlng.run_raxmlng_command(cmd)

Helper method to run a RAxML-NG command.

Parameters:

Name Type Description Default
cmd list

List of strings representing the RAxML-NG command to run.

 required

Raises:

Type Description
RAxMLNGError

If the RAxML-NG command fails with a CalledProcessError.
RuntimeError

If the RAxML-NG command fails with any other error.
Source code in pypythia/raxmlng.py 
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
def run_raxmlng_command(cmd: list[str]) -> None:
    """Helper method to run a RAxML-NG command.

    Args:
        cmd (list): List of strings representing the RAxML-NG command to run.

    Raises:
        RAxMLNGError: If the RAxML-NG command fails with a CalledProcessError.
        RuntimeError: If the RAxML-NG command fails with any other error.
    """
    try:
        subprocess.check_output(cmd, encoding="utf-8")
    except subprocess.CalledProcessError as e:
        raise RAxMLNGError(subprocess_exception=e)
    except Exception as e:
        raise RuntimeError("Running RAxML-NG command failed.") from e

pypythia.raxmlng.get_raxmlng_rfdist_results(log_file)

Method to parse the RAxML-NG log file and extract the number of unique topologies and relative RF-Distance. Args: log_file (pathlib.Path): Filepath pointing to the RAxML-NG log file.

Returns:

Name Type Description
num_topos float

Number of unique topologies of the given set of trees.
rel_rfdist float

Relative RF-Distance of the given set of trees. Computed as average over all pairwise RF-Distances. Value between 0.0 and 1.0.
Source code in pypythia/raxmlng.py 
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
def get_raxmlng_rfdist_results(log_file: pathlib.Path) -> tuple[int, float]:
    """
    Method to parse the RAxML-NG log file and extract the number of unique topologies and relative RF-Distance.
    Args:
        log_file (pathlib.Path): Filepath pointing to the RAxML-NG log file.

    Returns:
        num_topos (float): Number of unique topologies of the given set of trees.
        rel_rfdist (float): Relative RF-Distance of the given set of trees. Computed as average over all pairwise RF-Distances. Value between 0.0 and 1.0.

    """
    rel_rfdist = None
    num_topos = None

    for line in log_file.open().readlines():
        line = line.strip()

        if "Average relative RF distance in this tree set:" in line:
            rel_rfdist = _get_value_from_line(
                line, "Average relative RF distance in this tree set:"
            )
        elif "Number of unique topologies in this tree set:" in line:
            num_topos = _get_value_from_line(
                line, "Number of unique topologies in this tree set:"
            )

    if rel_rfdist is None or num_topos is None:
        raise ValueError("Error parsing raxml-ng log.")

    return int(num_topos), rel_rfdist