MolClusters 0.7.0__py3-none-any.whl

molclusters/analysis/coordinates.py

@@ -0,0 +1,186 @@
+# SPDX-FileCopyrightText: © 2024 Emanuel Mancio <emanuelmancio@usp.br>
+#
+# SPDX-License-Identifier: LGPL-3.0-or-later
+
+"""Provides `ClusterCoordinates`, the coordinates of the clusters holding solutes (.gro files)."""
+
+import io
+from collections import Counter
+from collections.abc import Iterable
+from pathlib import PurePosixPath
+
+import MDAnalysis as mda
+from loguru import logger
+from MDAnalysis.lib.util import NamedStream
+
+from ..cluster import Cluster
+from ..output import OutputFile
+from .base import Frame, FrameAnalysis, Run
+
+
+class ClusterCoordinates(FrameAnalysis):
+    """Writes the coordinates of every cluster holding a solute, frame by frame.
+
+    Each such cluster, made whole, is appended to ``cls-n<size>.gro`` (the clusters
+    of one size, pooled) and ``cls-id<id>.gro`` (one cluster's own trajectory). When
+    following the solutes, a cluster holding exactly one solute is also appended to
+    ``solute-<resid>.gro``. The files go in the ``folder`` of the output directory.
+
+    Attributes
+    ----------
+    solutes : set[str]
+        The residue names of the solutes.
+    follow : bool
+        Whether to write each solute's cluster to its own file.
+    folder : str
+        The folder of the output directory the files go in.
+    solute_ids : set[int]
+        The resids of the solute molecules, found by `prepare`.
+    follow_skipped : Counter[int]
+        Cluster id -> number of frames it wasn't followed in, for holding more than
+        one solute.
+    """
+
+    def __init__(
+        self,
+        solutes: Iterable[str],
+        *,
+        follow: bool = False,
+        folder: str = "coordinates",
+    ) -> None:
+        """Initialize the analysis.
+
+        Parameters
+        ----------
+        solutes : Iterable[str]
+            The residue names of the solutes.
+        follow : bool
+            Whether to write each solute's cluster to its own file.
+        folder : str
+            The folder of the output directory the files go in ("" for the
+            output directory itself).
+        """
+        self.solutes = set(solutes)
+        self.follow = follow
+        self.folder = folder
+        self.solute_ids: set[int] = set()
+        self.follow_skipped: Counter[int] = Counter()
+
+        self.outputs = (
+            OutputFile(self._file("cls-n<size>.gro")),
+            OutputFile(self._file("cls-id<id>.gro")),
+        )
+        if follow:
+            self.outputs += (OutputFile(self._file("solute-<resid>.gro")),)
+
+    def _file(self, name: str) -> str:
+        """Place the file `name` in `folder`.
+
+        Parameters
+        ----------
+        name : str
+            The file name.
+
+        Returns
+        -------
+        str
+            The file's path relative to the output directory.
+        """
+        return str(PurePosixPath(self.folder, name))
+
+    def prepare(self, run: Run) -> None:
+        """Find the solute molecules.
+
+        Parameters
+        ----------
+        run : Run
+            The run about to start.
+        """
+        self.solute_ids = {
+            int(resid)
+            for name in sorted(self.solutes)
+            for resid in run.universe.select_atoms(f"resname {name}").residues.resids
+        }
+        self.follow_skipped = Counter()
+
+    def analyse(self, frame: Frame) -> None:
+        """Append the clusters of the current frame that hold a solute.
+
+        Parameters
+        ----------
+        frame : Frame
+            The current frame.
+        """
+        for cls in frame.clusters.values():
+            sol_ids = self.solute_ids.intersection(cls.resids)
+            if not sol_ids:
+                continue
+
+            text = self._render(cls, frame.time)
+
+            # pooled by size: an ensemble of what an N-mer looks like, across all
+            # clusters that were ever that size, independent of cluster identity
+            frame.output.append(self._file(f"cls-n{cls.size}.gro"), text)
+
+            # pooled by identity: this specific cluster's own trajectory, tracked
+            # across frames via the dominance algorithm regardless of size changes
+            frame.output.append(self._file(f"cls-id{cls.id}.gro"), text)
+
+            # TODO: change to support merges
+            # FIXME: with changes in config this needs to be updated
+            if self.follow:
+                if len(sol_ids) > 1:
+                    # TODO: make more feature-rich follow procedure
+                    # counted, not logged: `finish` sums them up
+                    self.follow_skipped[cls.id] += 1
+                    continue
+
+                (sol_id,) = sol_ids
+
+                frame.output.append(self._file(f"solute-{sol_id}.gro"), text)
+
+    @staticmethod
+    def _render(cls: Cluster, time: float) -> str:
+        """Render a cluster, made whole, as one frame of a .gro file.
+
+        Parameters
+        ----------
+        cls : Cluster
+            The cluster to render.
+        time : float
+            The time of the current frame, for the title line.
+
+        Returns
+        -------
+        str
+            The frame's text, title line included.
+        """
+        # the GRO writer only writes whole files, so render the frame in memory
+        # (NamedStream keeps the buffer open when the writer closes it)
+        buf = io.StringIO()
+        with (
+            mda.Writer(NamedStream(buf, "cluster.gro"), multiframe=False) as w,
+            cls.whole() as atoms,
+        ):
+            w.write(atoms.sort())
+
+        # replace the writer's fixed "Written by MDAnalysis" title line
+        _, body = buf.getvalue().split("\n", 1)
+        return f"Cluster-{cls.id} - Time = {time}\n{body}"
+
+    def finish(self, run: Run) -> None:
+        """Warn about the frames in which solutes weren't followed.
+
+        Parameters
+        ----------
+        run : Run
+            The run that just ended.
+        """
+        if self.follow_skipped:
+            logger.warning(
+                f"Solutes were not followed in {self.follow_skipped.total()} "
+                f"frame(s) of {len(self.follow_skipped)} cluster(s) holding more than "
+                "one solute: those frames are missing from the solute-<resid>.gro "
+                "files. The cluster ids are logged at DEBUG level (--log-level DEBUG)."
+            )
+            logger.debug(f"Frames not followed, by cluster id: {self.follow_skipped}")

molclusters/analysis/lineage.py

@@ -0,0 +1,306 @@
+# SPDX-FileCopyrightText: © 2026 Emanuel Mancio <emanuelmancio@usp.br>
+#
+# SPDX-License-Identifier: LGPL-3.0-or-later
+
+"""Provides `Lineage`, where the clusters came from, what became of them and when.
+
+It writes cluster_events.csv, the clusters' formations, splits, merges and
+dissolutions frame by frame, and cluster_lifetimes.csv, each cluster's birth,
+end and lifetime.
+"""
+
+import math
+from collections import Counter
+from dataclasses import dataclass
+from typing import Any
+
+import numpy as np
+import pandas as pd
+from loguru import logger
+
+from ..output import OutputFile
+from .base import Frame, FrameAnalysis, Run
+
+EVENTS = "cluster_events.csv"
+LIFETIMES = "cluster_lifetimes.csv"
+
+EVENT_COLUMNS = ["Frame", "Time", "Event", "Cluster", "Other", "NMols"]
+
+LIFETIME_COLUMNS = [
+    "Id",
+    "BirthTime",
+    "DeathTime",
+    "Lifetime",
+    "NFrames",
+    "BornAtStart",
+    "AliveAtEnd",
+    "Origin",
+    "Parents",
+    "Fate",
+    "MergedInto",
+    "BirthSize",
+    "MaxSize",
+    "LastSize",
+]
+
+# what each event row says, for the log
+_DESCRIPTIONS = {
+    "formation": "cluster {cluster} formed of {n} free molecule(s)",
+    "split": "cluster {cluster} split off cluster {other} with {n} molecule(s)",
+    "merge": "cluster {other} merged into cluster {cluster} with {n} molecule(s)",
+    "dissolution": "cluster {cluster} ({n} molecule(s)) dissolved",
+}
+
+
+@dataclass(slots=True)
+class _Life:
+    """What `Lineage` knows of a cluster: its birth, its size so far and its end."""
+
+    birth_time: float
+    born_at_start: bool
+    origin: str
+    parents: tuple[int, ...]
+    birth_size: int
+    max_size: int
+    last_size: int
+    n_frames: int = 1
+    death_time: float = math.nan
+    fate: str = "alive"
+    merged_into: int | None = None
+
+
+class Lineage(FrameAnalysis):
+    """Records where each cluster came from, what became of it, and when.
+
+    Events are read from each frame's `Frame.transition` and stamped with the
+    first frame that shows them, so a cluster's `DeathTime` is the time of the
+    first frame it's gone from, and its lifetime, ``DeathTime - BirthTime``, a
+    whole number of frame spacings (a cluster seen in a single frame lived one
+    spacing).
+
+    cluster_events.csv has one row per event (see `EVENT_COLUMNS`); ``Other`` is
+    the other cluster involved, if any, and ``NMols`` the molecules it concerns:
+
+    - ``formation``: `Cluster` is new, made only of free molecules (``NMols``, its
+      size);
+    - ``split``: `Cluster` is new, and took ``NMols`` molecules from cluster
+      ``Other``. A cluster made of pieces of several clusters has a row for each,
+      and one breaking into several pieces a row for each new piece;
+    - ``merge``: cluster ``Other`` ended, merged into `Cluster` with ``NMols`` of
+      its molecules; a merge of several clusters has a row for each one absorbed;
+    - ``dissolution``: `Cluster` ended without merging (``NMols``, its last size).
+
+    The clusters of the run's first frame have no event: whatever formed them
+    happened before the run.
+
+    cluster_lifetimes.csv has one row per cluster (see `LIFETIME_COLUMNS`):
+    ``Origin`` is "initial" (there at the first frame), "formation" or "split",
+    ``Parents`` the clusters it took molecules from (";"-separated, most
+    molecules first), ``Fate`` "merge", "dissolution" or "alive" (at the last
+    frame), and ``MergedInto`` the cluster that absorbed it. The lifetimes of
+    clusters born at the start or alive at the end are censored: they lived at
+    least that long. One alive at the end has no ``DeathTime``, and its
+    ``Lifetime`` is up to the last frame.
+
+    Each frame's `Frame.transition` also goes in the report (see
+    `report_frame`), for the flows of molecules between clusters.
+
+    Attributes
+    ----------
+    lives : dict[int, _Life]
+        Cluster id -> what is known of the cluster so far, for every cluster seen.
+    """
+
+    __slots__ = ["lives", "_time"]
+
+    outputs = (OutputFile(EVENTS), OutputFile(LIFETIMES))
+
+    def __init__(self) -> None:
+        """Initialize an empty record, started over by `prepare`."""
+        self.lives: dict[int, _Life] = {}
+        self._time = math.nan
+
+    def prepare(self, run: Run) -> None:
+        """Start the record over, and cluster_events.csv with its header.
+
+        Parameters
+        ----------
+        run : Run
+            The run about to start.
+        """
+        self.lives = {}
+        self._time = math.nan
+        run.output.append(EVENTS, ",".join(EVENT_COLUMNS) + "\n")
+
+    def analyse(self, frame: Frame) -> None:
+        """Record the current frame's events, and the clusters' sizes.
+
+        Parameters
+        ----------
+        frame : Frame
+            The current frame.
+        """
+        transition = frame.transition
+        time = float(frame.time)
+        self._time = time
+        rows: list[tuple[str, int, int | None, int]] = []
+
+        for cid in sorted(transition.born):
+            size = frame.clusters[cid].size
+            parents = sorted(
+                ((prev, n) for prev, n in transition.sources(cid).items() if prev),
+                key=lambda source: (-source[1], source[0]),
+            )
+            if frame.index == 0:
+                origin = "initial"
+            elif parents:
+                origin = "split"
+                rows.extend(("split", cid, prev, n) for prev, n in parents)
+            else:
+                origin = "formation"
+                rows.append(("formation", cid, None, size))
+            self.lives[cid] = _Life(
+                birth_time=time,
+                born_at_start=frame.index == 0,
+                origin=origin,
+                parents=tuple(prev for prev, _ in parents),
+                birth_size=size,
+                max_size=size,
+                last_size=size,
+            )
+
+        for lost, into in sorted(transition.merged.items()):
+            rows.append(("merge", into, lost, transition.flows[lost, into]))
+            self._end(lost, time, "merge", into)
+        for cid in sorted(transition.dissolved):
+            rows.append(("dissolution", cid, None, self.lives[cid].last_size))
+            self._end(cid, time, "dissolution")
+
+        for cid, cls in frame.clusters.items():
+            if cid not in transition.born:
+                life = self.lives[cid]
+                life.n_frames += 1
+                life.last_size = cls.size
+                life.max_size = max(life.max_size, life.last_size)
+
+        number = int(frame.universe.coord.frame)
+        for event, cid, other, n in rows:
+            logger.debug(
+                "Frame {}: " + _DESCRIPTIONS[event],
+                number,
+                cluster=cid,
+                other=other,
+                n=n,
+            )
+            other_text = "" if other is None else other
+            frame.output.append(
+                EVENTS, f"{number},{time!r},{event},{cid},{other_text},{n}\n"
+            )
+
+    def report_frame(self, frame: Frame) -> dict[str, Any]:
+        """Give how the frame's clusters came from the previous frame's, for the report.
+
+        Parameters
+        ----------
+        frame : Frame
+            The current frame.
+
+        Returns
+        -------
+        dict[str, Any]
+            The frame's `Frame.transition`, sorted: ``flows``, rows of (previous
+            id, current id, molecules), id 0 for no cluster; ``born``; ``merged``,
+            rows of (absorbed id, id it merged into); and ``dissolved``.
+        """
+        transition = frame.transition
+        return {
+            "flows": [
+                [prev, cur, n] for (prev, cur), n in sorted(transition.flows.items())
+            ],
+            "born": sorted(transition.born),
+            "merged": [list(pair) for pair in sorted(transition.merged.items())],
+            "dissolved": sorted(transition.dissolved),
+        }
+
+    def _end(
+        self, cid: int, time: float, fate: str, merged_into: int | None = None
+    ) -> None:
+        """Record the end of a cluster.
+
+        Parameters
+        ----------
+        cid : int
+            The cluster's id.
+        time : float
+            The time of the first frame without it.
+        fate : str
+            "merge" or "dissolution".
+        merged_into : int | None
+            The cluster that absorbed it, for a merge.
+        """
+        life = self.lives[cid]
+        life.death_time = time
+        life.fate = fate
+        life.merged_into = merged_into
+
+    def lifetimes(self) -> pd.DataFrame:
+        """Tabulate every cluster seen so far, as cluster_lifetimes.csv has them.
+
+        Returns
+        -------
+        pd.DataFrame
+            One row per cluster, by id (see `LIFETIME_COLUMNS`).
+        """
+        rows = [
+            [
+                cid,
+                life.birth_time,
+                life.death_time,
+                (self._time if life.fate == "alive" else life.death_time)
+                - life.birth_time,
+                life.n_frames,
+                life.born_at_start,
+                life.fate == "alive",
+                life.origin,
+                ";".join(map(str, life.parents)),
+                life.fate,
+                life.merged_into,
+                life.birth_size,
+                life.max_size,
+                life.last_size,
+            ]
+            for cid, life in sorted(self.lives.items())
+        ]
+        table = pd.DataFrame(rows, columns=LIFETIME_COLUMNS)
+        table["MergedInto"] = table["MergedInto"].astype("Int64")
+        return table
+
+    def finish(self, run: Run) -> None:
+        """Log a summary of the events and lifetimes, and write cluster_lifetimes.csv.
+
+        Parameters
+        ----------
+        run : Run
+            The run that just ended.
+        """
+        table = self.lifetimes()
+        table.to_csv(run.output.path(LIFETIMES), index=False)
+
+        origins = Counter(table["Origin"])
+        fates = Counter(table["Fate"])
+        message = (
+            f"Cluster lineage: {origins['formation']} cluster(s) formed of free "
+            f"molecules and {origins['split']} split off others; "
+            f"{fates['merge']} merged into another and {fates['dissolution']} "
+            "dissolved."
+        )
+        # lifetimes neither censored at the start nor at the end
+        whole = table[~table["BornAtStart"] & ~table["AliveAtEnd"]]
+        if len(whole):
+            single = int((whole["NFrames"] == 1).sum())
+            message += (
+                f" The {len(whole)} born and ended within the run lived "
+                f"{np.median(whole['Lifetime']):.4g} ps (median); {single} of them "
+                "for a single frame."
+            )
+        logger.info(message)

molclusters/analysis/nucleus.py

@@ -0,0 +1,168 @@
+# SPDX-FileCopyrightText: © 2024 Emanuel Mancio <emanuelmancio@usp.br>
+#
+# SPDX-License-Identifier: LGPL-3.0-or-later
+
+"""Provides `Nucleus`, the nuclei inside the clusters (nucleus_data.csv)."""
+
+import operator
+from collections.abc import Iterable
+from functools import reduce
+from typing import Any
+
+import networkx as nx
+import numpy as np
+import pandas as pd
+
+from ..cluster import Cluster, MolGroup
+from ..output import OutputFile
+from ..report import group_record
+from .base import Frame, FrameAnalysis, Run
+
+COLUMNS = [
+    "Time",
+    "NNuc",
+    "Size",
+    "Radius",
+    "Density",
+    "Charge",
+    "Dipole",
+    "Spher",
+    "Shape",
+]
+
+
+class Nucleus(FrameAnalysis):
+    """Finds the nuclei inside the clusters, frame by frame.
+
+    A nucleus is a connected group, inside a cluster, of molecules with one of the
+    nucleus residue names. Each cluster's nuclei also go in the report (see
+    `report_cluster`).
+
+    Attributes
+    ----------
+    resnames : set[str]
+        The residue names of the molecules that make up nuclei.
+    nuclei : dict[int, list[MolGroup]]
+        Cluster id -> the cluster's nuclei in the current frame (an empty list for
+        a cluster without nuclei), for the analyses after this one.
+    data : np.ndarray
+        One row per frame (see `COLUMNS`): time, the average number of nuclei of
+        the clusters that have any (0 without nuclei), and the nuclei's average
+        size, radius, density, charge, dipole moment, sphericity and shape
+        parameter (NaN without nuclei).
+    """
+
+    outputs = (OutputFile("nucleus_data.csv"),)
+
+    def __init__(self, resnames: Iterable[str]) -> None:
+        """Initialize an empty record, sized by `prepare`.
+
+        Parameters
+        ----------
+        resnames : Iterable[str]
+            The residue names of the molecules that make up nuclei.
+        """
+        self.resnames = set(resnames)
+        self.nuclei: dict[int, list[MolGroup]] = {}
+        self.data = np.full((0, len(COLUMNS)), np.nan)
+
+    def prepare(self, run: Run) -> None:
+        """Make room for every frame of the run.
+
+        Parameters
+        ----------
+        run : Run
+            The run about to start.
+        """
+        self.data = np.full((run.n_frames, len(COLUMNS)), np.nan)
+
+    def analyse(self, frame: Frame) -> None:
+        """Find the nuclei of the current frame and record their averages.
+
+        Parameters
+        ----------
+        frame : Frame
+            The current frame.
+        """
+        self.nuclei = {}
+        n_nucleus = []
+        sizes = []
+        radius = []
+        dipole = []
+        density = []
+        sphericity = []
+        shape = []
+        charge = []
+        for cid, cls in frame.clusters.items():
+            possible_nucleus = [
+                rid
+                for rnm, rid in zip(cls.resnames, cls.resids, strict=True)
+                if rnm in self.resnames
+            ]
+
+            self.nuclei[cid] = []
+            subcomps = nx.induced_subgraph(cls.graph, possible_nucleus)
+            n_nuc = 0
+            for sg in nx.connected_components(subcomps):
+                tp = MolGroup(frame.universe, list(sg))
+
+                n_nuc += 1
+                sizes.append(tp.size)
+                radius.append(tp.radius)
+                dipole.append(tp.dipole_moment)
+                density.append(tp.density)
+                sphericity.append(tp.sphericity)
+                shape.append(tp.shape_parameter)
+                charge.append(tp.charge)
+
+                self.nuclei[cid].append(tp)
+
+            if n_nuc != 0:
+                n_nucleus.append(n_nuc)
+
+        row = self.data[frame.index]
+        row[0] = frame.time
+        row[1] = 0 if len(n_nucleus) == 0 else np.average(n_nucleus)
+        row[2] = np.nan if len(n_nucleus) == 0 else np.average(sizes)
+        row[3] = np.nan if len(n_nucleus) == 0 else np.average(radius)
+        row[4] = np.nan if len(n_nucleus) == 0 else np.average(density)
+        row[5] = np.nan if len(n_nucleus) == 0 else np.average(charge)
+        row[6] = np.nan if len(n_nucleus) == 0 else np.average(dipole)
+        row[7] = np.nan if len(n_nucleus) == 0 else np.average(sphericity)
+        row[8] = np.nan if len(n_nucleus) == 0 else np.average(shape)
+
+    def report_cluster(self, frame: Frame, cluster: Cluster) -> dict[str, Any]:
+        """Give the nuclei of a cluster, for the report.
+
+        Parameters
+        ----------
+        frame : Frame
+            The current frame.
+        cluster : Cluster
+            The cluster.
+
+        Returns
+        -------
+        dict[str, Any]
+            ``nuclei``, one `report.group_record` per nucleus, and
+            ``combined_dipole_moment``, the dipole moment of all of them together
+            (None without nuclei).
+        """
+        nuclei = self.nuclei.get(cluster.id, [])
+        combined = reduce(operator.add, nuclei).dipole_moment if nuclei else None
+        return {
+            "nuclei": [group_record(nucleus) for nucleus in nuclei],
+            "combined_dipole_moment": combined,
+        }
+
+    def finish(self, run: Run) -> None:
+        """Write the record to nucleus_data.csv.
+
+        Parameters
+        ----------
+        run : Run
+            The run that just ended.
+        """
+        pd.DataFrame(self.data, columns=COLUMNS).to_csv(
+            run.output.path("nucleus_data.csv"), index=False
+        )