From 6d353a1cb78d6bf6528128ffe2cc9c50d45b9818 Mon Sep 17 00:00:00 2001 From: Jacan Chaplais <31956735+jacanchaplais@users.noreply.github.com> Date: Thu, 23 Feb 2023 15:28:42 +0000 Subject: [PATCH] Add version information to docstrings via Sphinx directives #101 (#102) * added directives to top level data structures #101 * corrected MaskGroup directive #101 * documented method and attr updates in AdjacencyList #101 * added whitespace before directives #101 * added method documentation #101 * removed janky hard_vertex attribute * updated string literal param docstring #101 * docstring format corrections #101 * remove versionadded for delta_R #101 * added sphinx version directives #101 * export parton_hadron_distance #101 * matrix docstring formatting enhancements #101 * improved inline formatting of docstrings #101 * docstring formatting corrections #101 * docstring corrections #101 --- graphicle/base.py | 2 + graphicle/calculate.py | 72 +++++------ graphicle/data.py | 270 +++++++++++++++++++++++++++++------------ graphicle/matrix.py | 83 ++++++++----- graphicle/select.py | 40 +++--- graphicle/transform.py | 28 +++-- 6 files changed, 326 insertions(+), 169 deletions(-) diff --git a/graphicle/base.py b/graphicle/base.py index 3d94188..7808a27 100644 --- a/graphicle/base.py +++ b/graphicle/base.py @@ -51,6 +51,8 @@ class EventInterface(ty.Protocol): :group: base + .. versionadded:: 0.1.7 + Attributes ---------- pdg : ndarray[int32] diff --git a/graphicle/calculate.py b/graphicle/calculate.py index d017d30..7ed2ddc 100644 --- a/graphicle/calculate.py +++ b/graphicle/calculate.py @@ -37,6 +37,8 @@ def azimuth_centre(pmu: gcl.MomentumArray, pt_weight: bool = True) -> float: :group: calculate + .. versionadded:: 0.1.7 + Parameters ---------- pmu : MomentumArray @@ -68,7 +70,7 @@ def combined_mass( weight: base.DoubleVector | None = None, ) -> float: """Returns the combined mass of the particles represented in the - provided MomentumArray. + provided ``MomentumArray``. This is done by summing the four momenta, optionally weighting the components, and then taking the inner product of the result with @@ -76,25 +78,27 @@ def combined_mass( :group: calculate + .. versionadded:: 0.1.0 + Parameters ---------- - pmu : MomentumArray, ndarray + pmu : MomentumArray or ndarray[void] Momenta of particles comprising a jet, or an analagous combined object. If a numpy array is passed, it must be structured with - fields (x, y, z, e). - weight : array, optional + fields with names ``('x', 'y', 'z', 'e')``. + weight : ndarray[float64], optional Weights for each particle when reconstructing the jet momentum. May be either structured or unstructured. If unstructured, - ensure the columns are in the order (x, y, z, e). + ensure the columns are in the order ``('x', 'y', 'z', 'e')``. Notes ----- - This does not mask the MomentumArray for you. All filters and cuts - must be applied before passing to this function. + This does not mask the ``MomentumArray`` for you. All filters and + cuts must be applied before passing to this function. In the event of a squared mass below zero (due to numerical fluctuations for very low mass reconstructions), this function will - simply return 0.0. + simply return ``0.0``. """ # sanitizing and combining the inputs if isinstance(pmu, gcl.MomentumArray): @@ -178,37 +182,37 @@ def flow_trace( :group: calculate + .. versionadded:: 0.1.0 + Parameters ---------- graph : Graphicle Full particle event, containing hard partons, showering and hadronisation. - mask : MaskArray, MaskGroup, ndarray + mask : MaskArray or MaskGroup or ndarray[bool_] Boolean mask identifying which particles should have their ancestry traced. - prop : ArrayBase, ndarray - Property to trace back, eg. 4-momentum, charge. - Must be the same shape as arrays stored in graph. - Can be structured, unstructured, or a graphicle array, though - unstructured arrays must be 1d. + prop : ArrayBase or ndarray[any] + Property to trace back, *eg.* 4-momentum, charge, *etc*. Must be + the same shape as arrays stored in graph. Can be structured, + unstructured, or a graphicle array, though unstructured arrays + must be 1D. exclusive : bool - If True, double counting from descendant particles in the hard - event will be switched off. - eg. for event t > b W+, descendants of b will show no - contribution from t, as b is a subset of t. - Default is False. - target : set of ints, optional + If ``True``, double counting from descendant particles in the + hard event will be switched off. *eg.* for event ``t > b W+``, + descendants of ``b`` will show no contribution from ``t``, as + ``b`` is a subset of ``t``. Default is ``False``. + target : set[int], optional Highlights specific partons in the hard event to decompose - properties with respect to. - If left as None, will simply use all partons in hard event, - except for incoming partons. + properties with respect to. If unset, will use all partons in + hard event, except for incoming partons. Returns ------- - trace_array : Dict of arrays - Dictionary of arrays. Keys are parton names, arrays represent - the contributions of hard partons traced down to the properties - of the selected subset of particles specified by mask. + trace_array : dict[str, ndarray] + Keys are parton names, arrays represent the contributions of + hard partons traced down to the properties of the selected + subset of particles specified by mask. """ if isinstance(prop, base.ArrayBase): prop = prop.data @@ -273,9 +277,11 @@ def cluster_pmu( :group: calculate + .. versionadded:: 0.1.4 + Parameters ---------- - pmu: gcl.MomentumArray + pmu: MomentumArray The momenta of each particle in the point cloud. radius : float The radius of the clusters to be produced. @@ -294,7 +300,7 @@ def cluster_pmu( Returns ------- - clusters : gcl.MaskGroup + clusters : MaskGroup MaskGroup object, containing boolean masks over the input data for each jet clustering. @@ -302,10 +308,8 @@ def cluster_pmu( ----- This is a wrapper around FastJet's implementation. - Standard settings: - kt algorithm: p_val = 1 - Cambridge/Aachen algorithm: p_val = 0 - anti-kt algorithm: p_val = -1 + ``p_val`` set to ``-1`` gives anti-kT, ``0`` gives Cambridge-Aachen, + and ``1`` gives kT clusterings. """ pmu_pyjet = pmu.data[["e", "x", "y", "z"]] pmu_pyjet.dtype.names = "E", "px", "py", "pz" @@ -341,7 +345,7 @@ def _root_diff_two_squares( squared difference. This means that root negative squared differences are permitted, but produce negative, rather than imaginary, values. - If `x1` or `x2` is scalar_like (ie. unambiguously cast-able to a + If `x1` or `x2` is scalar_like (*ie.* unambiguously cast-able to a scalar type), it is broadcast for use with each element of the other argument. diff --git a/graphicle/data.py b/graphicle/data.py index 209c0a0..5645940 100644 --- a/graphicle/data.py +++ b/graphicle/data.py @@ -117,6 +117,8 @@ class MomentumElement(ty.NamedTuple): """Named tuple container for the momentum of a single particle. :group: datastructure + + .. versionadded:: 0.2.0 """ x: float @@ -130,6 +132,8 @@ class ColorElement(ty.NamedTuple): particle. :group: datastructure + + .. versionadded:: 0.2.0 """ color: int @@ -141,6 +145,8 @@ class VertexPair(ty.NamedTuple): particle. :group: datastructure + + .. versionadded:: 0.2.0 """ src: int @@ -171,8 +177,8 @@ def _array_ufunc( ufunc : callable Numpy ufunc being called on ``instance``. method : str - Method applied to ``ufunc``, eg. 'reduce' for ``np.add.reduce``, - of which ``np.sum`` is an alias. + Method applied to ``ufunc``, *eg.* ``'reduce'`` for + ``np.add.reduce``, of which ``np.sum`` is an alias. *inputs : tuple[Any] Positional arguments of the ufunc. **kwargs : dict[str, Any] @@ -182,7 +188,7 @@ def _array_ufunc( ------- output : arrays or scalars, or tuple thereof, or None Output of passed ufunc. Type depends on ``method``, ``inputs``, - and ``instance``. If ``method`` is 'reduce' on ``instance`` + and ``instance``. If ``method`` is ``'reduce'`` on ``instance`` with a flat underlying array, then ``output`` will be scalar. If ``ufunc`` maps an array to booleans, ``output`` will be a ``MaskArray``. @@ -382,9 +388,14 @@ class MaskArray(base.MaskBase, base.ArrayBase): :group: datastructure + .. versionadded:: 0.1.0 + + .. versionchanged:: 0.2.0 + Added internal numpy interfaces for greater interoperability. + Parameters ---------- - data : Sequence[bool] + data : sequence[bool] Boolean values consituting the mask. Attributes @@ -505,7 +516,7 @@ def data( def _mask_compat(*masks: base.MaskLike) -> bool: - """Check if a collection of masks are compatible, ie. they must be + """Check if a collection of masks are compatible, *ie.* they must be either numpy boolean arrays, or ``MaskBase`` instances. """ for mask in masks: @@ -521,9 +532,9 @@ def _mask_eq(mask1: base.MaskLike, mask2: base.MaskLike) -> MaskArray: Parameters ---------- - mask1 : base.MaskBase | numpy.ndarray + mask1 : base.MaskBase or ndarray Boolean array to compare against. - mask2 : base.MaskBase | numpy.ndarray + mask2 : base.MaskBase or ndarray The other array. """ if not _mask_compat(mask1, mask2): @@ -542,9 +553,9 @@ def _mask_neq(mask1: base.MaskLike, mask2: base.MaskLike) -> MaskArray: Parameters ---------- - mask1 : base.MaskBase | numpy.ndarray + mask1 : base.MaskBase or ndarray Boolean array to compare against. - mask2 : base.MaskBase | numpy.ndarray + mask2 : base.MaskBase or ndarray The other array. """ if not _mask_compat(mask1, mask2): @@ -588,25 +599,29 @@ class MaskGroup(base.MaskBase, cla.MutableMapping[str, base.MaskBase]): :group: datastructure + .. versionadded:: 0.1.0 + Parameters ---------- _mask_arrays : dict of MaskArrays or array-like objects Dictionary of MaskArray objects to be composed. - agg_op : str or MaskAggOp - Defines the aggregation operation when accessing the `data` - attribute. Options are "and", "or", "none". Default is "and". + agg_op : {'and', 'or', 'none'} + Defines the aggregation operation when accessing the ``data`` + attribute. Default is ``'and'``. Attributes ---------- data : ndarray[bool_] Combination of all masks in group via bitwise AND reduction. + agg_op : MaskAggOp + Aggregation operation set for reduction over constituent masks. names : list[str] Provides the string values of the keys to the top-level nested ``MaskBase`` objects as a list. Will be deprecated in future. ``MaskGroup.keys()`` is preferred. bitwise_or : ndarray[bool_] Bitwise ``OR`` reduction over the nested masks. - bitwise_or : np.ndarray[bool_] + bitwise_and : np.ndarray[bool_] Bitwise ``AND`` reduction over the nested masks. dict : dict[base.MaskBase] Masks nested in a dictionary instead of a ``MaskGroup``. @@ -616,7 +631,10 @@ class MaskGroup(base.MaskBase, cla.MutableMapping[str, base.MaskBase]): from_numpy_structured() Converts a structured boolean array into a ``MaskGroup``. flatten() - Removes any nesting of ``MaskGroup``s within ``MaskGroup``s. + Removes any nesting of ``MaskGroup`` instances within + ``MaskGroup`` instances. + + .. versionadded:: 0.1.11 copy() Copies the ``MaskGroup`` instance. """ @@ -835,35 +853,49 @@ class PdgArray(base.ArrayBase): :group: datastructure + .. versionadded:: 0.1.0 + + .. versionchanged:: 0.2.0 + Added internal numpy interfaces for greater interoperability. + Parameters ---------- - data : Sequence[int] + data : sequence[int] The PDG codes for each particle in the point cloud. Attributes ---------- - name : ndarray + name : ndarray[object] String representation of particle names. - charge : ndarray + charge : ndarray[float64] Charge for each particle in elementary units. - mass : ndarray + mass : ndarray[float64] Mass for each particle in GeV. - mass_bounds : ndarray - Mass upper and lower bounds for each particle in GeV. - quarks : ndarray + mass_bounds : ndarray[void] + Mass upper and lower bounds for each particle in GeV. Structured + array with fields ``('masslower', 'massupper')``. + quarks : ndarray[object] String representation of quark composition for each particle. - width : ndarray + width : ndarray[float64] Width for each particle in GeV. - width_bounds : ndarray + width_bounds : ndarray[void] Width upper and lower bounds for each particle in GeV. - isospin : ndarray + Structured array with fields ``('widthlower', 'widthupper')``. + isospin : ndarray[float64] Isospin for each particle. - g_parity : ndarray + g_parity : ndarray[float64] G-parity for each particle. - space_parity : ndarray + space_parity : ndarray[float64] Spatial parity for each particle. - charge_parity : ndarray + charge_parity : ndarray[float64] Charge parity for each particle. + + Methods + ------- + mask() + Returns ``MaskArray`` to blacklist or whitelist PDGs from event. + copy() + Provides a deepcopy of the data. """ _data: base.IntVector = _array_field(" base.DoubleVector: Notes ----- Infinite values may be encountered if comparing with particles - not present on the eta-phi plane, __ie.__ travelling parallel to + not present on the eta-phi plane, *ie.* travelling parallel to the beam axis. """ with warnings.catch_warnings(): @@ -1264,17 +1313,28 @@ class ColorArray(base.ArrayBase): :group: datastructure + .. versionadded:: 0.1.0 + + .. versionchanged:: 0.2.0 + Added internal numpy interfaces for greater interoperability. + Parameters ---------- - data : np.ndarray[np.int32] + data : ndarray[int32] or ndarray[void] Data representing the QCD color charge of each particle in the point cloud. Given as either a (n, 2)-dimensional numpy array, - or a structured array, with fields "color", "anticolor". + or a structured array, with field names + ``('color', 'anticolor')``. Attributes ---------- - data : ndarray - Structured array containing color / anti-color pairs. + data : ndarray[void] + Structured array containing ``('color', 'anticolor')`` pairs. + + Methods + ------- + copy() + Provides a deepcopy of the data. """ _data: base.VoidVector = _array_field(" coo_array: @property def data(self) -> base.VoidVector: + """Underlying numpy data.""" return self._data.view(self.dtype).reshape(-1) @property def edges(self) -> base.VoidVector: + """Vertex index pairs exposed as a structured numpy array with + fields 'in' and 'out' respectively. + """ return self.data @property @@ -2004,6 +2120,11 @@ class Graphicle: :group: datastructure + .. versionadded:: 0.1.0 + + .. versionchanged:: 0.2.4 + Removed ``hard_vertex`` attribute. + Parameters ---------- particles : ParticleSet @@ -2036,10 +2157,21 @@ class Graphicle: Vertex ids of each particle with at least one edge. hard_mask : MaskGroup Identifies which particles participate in the hard process. - For Pythia, this is split into four categories: incoming, - intermediate, outgoing, outgoing_nonperturbative_diffraction. - hard_vertex : int - Vertex at which the hard process is initiated. + For Pythia, this is split into four categories: + ``'incoming'``, ``'intermediate'``, ``'outgoing'``, and + ``'outgoing_nonperturbative_diffraction'``. + + Methods + ------- + from_numpy() + Constructs ``Graphicle`` instance from numpy arrays. + from_event() + Constructs ``Graphicle`` instance from object implementing the + ``base.EventInterface`` protocol. + + .. versionadded:: 0.1.7 + copy() + Provides a deepcopy of the data. """ particles: ParticleSet = field(default=Factory(ParticleSet)) @@ -2175,19 +2307,3 @@ def edges(self) -> base.VoidVector: @property def nodes(self) -> base.IntVector: return self.adj.nodes - - def _need_attr(self, attr_name: str, task: str) -> None: - if len(getattr(self, attr_name)) == 0: - raise AttributeError( - f"Graphicle object needs '{attr_name}' attribute to {task}." - ) - - @property - def hard_vertex(self) -> int: - """Id of vertex at which hard interaction occurs.""" - for prop in ("status", "edges"): - self._need_attr(attr_name=prop, task="infer hard vertex") - hard_edges = self.edges[self.status.hard_mask] - vertex_array = np.intersect1d(hard_edges["in"], hard_edges["out"]) - central = vertex_array[np.argmin(np.abs(vertex_array))] - return int(central) diff --git a/graphicle/matrix.py b/graphicle/matrix.py index ca0b65f..6f57f35 100644 --- a/graphicle/matrix.py +++ b/graphicle/matrix.py @@ -8,7 +8,13 @@ from . import base -__all__ = ["cut_adj", "knn_adj", "fc_adj", "delta_R_aff"] +__all__ = [ + "cut_adj", + "knn_adj", + "fc_adj", + "delta_R_aff", + "parton_hadron_distance", +] _types = Types() @@ -24,35 +30,37 @@ def cut_adj( towards the neighbours within a cut range, determined from the input affinity matrix. - The cut represents the limiting value of the affinity matrix for + The ``cut`` represents the limiting value of the affinity matrix for elements to form edges in the adjacency matrix. :group: matrix + .. versionadded:: 0.1.0 + Parameters ---------- - matrix : array + matrix : ndarray[float64] Particle affinities. cut : float Value beyond which affinities are not sufficient to form edges. - mode : str + mode : {'max', 'min'} Sets whether affinities should be above or below cut. - 'max' implies matrix < cut, 'min' implies matrix > cut. + 'max' implies ``matrix < cut``, 'min' implies ``matrix > cut``. Default is 'max'. self_loop : bool - If False will remove self-edges. Default is False. + If ``False`` will remove self-edges. Default is ``False``. weighted : bool - If True edges weighted by affinity, if False edge is binary. - Default is False. + If ``True`` edges weighted by affinity, if ``False`` edge is + binary. Default is ``False``. Returns ------- - adj : array + adj : ndarray[bool_] or ndarray[float64] Adjacency matrix representing particle connectivity. Notes ----- - If weighted is False, the returned adjacency matrix will be boolean. + If weighted is ``False``, the returned adjacency matrix will be boolean. """ # form the cut mask if mode == "max": @@ -87,37 +95,40 @@ def knn_adj( row: bool = True, dtype: Optional[npt.DTypeLike] = None, ) -> base.DoubleVector: - """Produce a directed adjacency matrix with outward edges - towards the k nearest neighbours, determined from the input - affinity matrix. + """Produce a directed adjacency matrix with outward edges towards + the ``k`` nearest neighbours, determined from the input affinity + ``matrix``. :group: matrix + .. versionadded:: 0.1.0 + Parameters ---------- - matrix : 2d numpy array - Particle affinities. + matrix : ndarray[float64] + 2D matrix of Particle affinities. k : int Number of nearest neighbours in result. weighted : bool - If True edges weighted by affinity, if False edge is binary. - Default is False. + If ``True`` edges weighted by affinity, if ``False`` edge is + binary. Default is ``False``. self_loop : bool - If False will remove self-edges. Default is False. + If ``False`` will remove self-edges. Default is ``False``. row : bool - If True outward edges given by rows, if False cols. Default is - True. + If ``True`` outward edges given by rows, if ``False`` cols. + Default is ``True``. dtype : dtype-like, optional - Type of output. Must be floating point if weighted is True. + Type of output. Must be floating point if weighted is ``True``. Returns ------- - adj : array + adj : ndarray[bool_] or ndarray[float64] Adjacency matrix representing particle connectivity. Notes ----- - If weighted is False, the returned adjacency matrix will be boolean. + If weighted is ``False``, the returned adjacency matrix will be + boolean. """ axis = 0 # calculate everything row-wise if self_loop is False: @@ -154,6 +165,8 @@ def fc_adj( :group: matrix + .. versionadded:: 0.1.0 + Parameters ---------- num_nodes : int @@ -163,6 +176,12 @@ def fc_adj( ``False``. dtype : dtype-like The dtype of the output array. Default is ``np.bool_``. + + Returns + ------- + adj : ndarray[bool_] or ndarray[float64] + Fully connected Adjacency matrix representing particle + connectivity. """ adj = np.ones((num_nodes, num_nodes), dtype=dtype) if self_loop is False: @@ -172,25 +191,27 @@ def fc_adj( def delta_R_aff(pmu: gcl.MomentumArray) -> base.DoubleVector: """Returns the inter-particle Euclidean distances between particles - internally within the given MomentumArray. + internally within the given ``MomentumArray``. :group: matrix + .. versionadded:: 0.1.0 + Parameters ---------- - pmu : gcl.MomentumArray - Four-momenta. + pmu : MomentumArray + Four-momenta of particle set. Returns ------- - delta_R_matrix : np.ndarray[double] + delta_R_matrix : ndarray[float64] Square symmetric matrix representing the Euclidean distance between every pair of particles in the eta-phi plane. Notes ----- Infinite values may be encountered if particles are travelling - parallel to the beam axis, __ie.__ with infinite pseudorapidity. + parallel to the beam axis, *ie.* with infinite pseudorapidity. """ return pmu.delta_R(pmu) @@ -204,6 +225,10 @@ def parton_hadron_distance( between two sets of 4-momenta. The pt weighting is raised to the power given by ``pt_exp``. + :group: matrix + + .. versionadded:: 0.1.11 + Parameters ---------- parton_pmu, hadron_pmu : MomentumArray @@ -213,7 +238,7 @@ def parton_hadron_distance( Returns ------- - dists : ndarray[double] + dists : ndarray[float64] Distance matrix between ``parton_pmu`` and ``hadron_pmu``, whose number of rows and columns equal to the input sizes, respectively. diff --git a/graphicle/select.py b/graphicle/select.py index c7b2b3b..4f6bbca 100644 --- a/graphicle/select.py +++ b/graphicle/select.py @@ -48,8 +48,8 @@ def fastjet_clusters( eta_cut: ty.Optional[float] = None, top_k: ty.Optional[int] = None, ) -> ty.List[gcl.MaskArray]: - """Clusters particles using the FastJet implementation of the - generalised-kt algorithm. + """Clusters particles using the **FastJet** implementation of the + *generalised-kt algorithm*. :group: select @@ -58,7 +58,7 @@ def fastjet_clusters( Parameters ---------- - pmu: gcl.MomentumArray + pmu: MomentumArray The momenta of each particle in the point cloud. radius : float The radius of the clusters to be produced. @@ -76,7 +76,7 @@ def fastjet_clusters( discarded. top_k : int, optional Only return a maximum ``top_k`` number of jets, sorted by - transverse momentum. ie. if ``top_k`` is 3, only 3 jets with + transverse momentum. *ie.* if ``top_k`` is 3, only 3 jets with highest pt will be given. If ``top_k`` exceeds the number of jets reconstructed, all of the jets will be included. @@ -90,8 +90,8 @@ def fastjet_clusters( ----- This is a wrapper around FastJet's implementation. - ``p_val`` set to ``-1`` gives anti-kT, ``0`` gives Cambridge-Aachen, - and ``1`` gives kT clusterings. + ``p_val`` set to ``-1`` gives **anti-kT**, ``0`` gives + **Cambridge-Aachen**, and ``1`` gives **kT** clusterings. """ pmu_pyjet = pmu.data[["e", "x", "y", "z"]] pmu_pyjet.dtype.names = "E", "px", "py", "pz" @@ -199,16 +199,13 @@ def vtx_pdg_pivot(direction: str): def vertex_descendants(adj: gcl.AdjacencyList, vertex: int) -> gcl.MaskArray: - """Return a mask over a graphicle object, identifying which - particles descend from a given interaction vertex. + """Returns a ``MaskArray`` to select particles which descend from a + given interaction vertex. :group: select .. versionadded:: 0.1.0 - .. versionchanged:: 0.1.11 - Performance enhancements. - Parameters ---------- adj : AdjacencyList @@ -465,8 +462,8 @@ def hard_descendants( target: ty.Optional[ty.Iterable[int]] = None, sign_sensitive: bool = False, ) -> gcl.MaskGroup: - """Returns a MaskGroup over the particles in the graph, where True - indicates a particle descends from a specific hard parton. + """Returns a ``MaskGroup`` instance to select particle descendants + of ``target`` hard partons (by PDG code). :group: select @@ -478,17 +475,18 @@ def hard_descendants( Parameters ---------- graph : Graphicle - Particle graph containing at least PdgArray and StatusArray. + Particle graph containing at least ``PdgArray`` and + ``StatusArray``. target : Iterable[int], optional PDG codes referring to the hard particles for which descendants are obtained. If ``None``, will obtain masks for all intermediate and outgoing hard partons. Default is ``None``. sign_sensitive : bool Indicates whether sign of PDG code should be used when selecting - hard partons, ie. if set to False both particle and - anti-particle partons will be masked, whereas if True only the - partons explicitly matching the target sign will be considered. - Default is False. + hard partons, *ie.* if set to ``False`` both particle and + anti-particle partons will be masked, whereas if ``True`` only + the partons explicitly matching the target sign will be + considered. Default is ``False``. """ hard_vtxs = list() # get the vertices of the hard partons @@ -719,7 +717,7 @@ def leaf_masks(mask_tree: gcl.MaskGroup) -> gcl.MaskGroup: def any_overlap(masks: gcl.MaskGroup) -> bool: - """Given a MaskGroup object, checks if any of the masks overlap + """Given a ``MaskGroup`` object, checks if any of the masks overlap with each other. :group: select @@ -734,8 +732,8 @@ def any_overlap(masks: gcl.MaskGroup) -> bool: Returns ------- any_overlap : bool - True if at least two MaskArrays in MaskGroup have at least one - True element in the same location. + ``True`` if at least two ``MaskArrays`` in ``masks`` have at + least one ``True`` element in the same location. """ combos = it.combinations(masks.dict.values(), 2) pair_checks = map(np.bitwise_and, *zip(*combos)) diff --git a/graphicle/transform.py b/graphicle/transform.py index ff0f06d..4e30183 100644 --- a/graphicle/transform.py +++ b/graphicle/transform.py @@ -4,14 +4,14 @@ Utilities for manipulating the graph structure of particle data. """ -import numpy as np import networkx as _nx +import numpy as np from typicle import Types from typicle.convert import cast_array import graphicle as gcl -from . import base +from . import base __all__ = ["particle_as_node", "centre_angle", "centre_pseudorapidity"] @@ -19,18 +19,25 @@ def particle_as_node(adj_list: gcl.AdjacencyList) -> gcl.AdjacencyList: - """Converts an adjacency list in which the particles are represented - as edges, to one in which the particles are the nodes. - The order of the nodes in the resulting AdjacencyList retains the - same particle ordering of the initial edge list. + """Converts an ``AdjacencyList`` in which the particles are + represented as edges, to one in which the particles are the nodes. + The order of the nodes in the resulting ``AdjacencyList`` retains + the same particle ordering of the initial edge list. :group: transform + .. versionadded:: 0.1.0 + Parameters ---------- adj_list : AdjacencyList The edge-as-particle representation. + Returns + ------- + node_adj : AdjacencyList + The node-as-particle representation. + Examples -------- >>> from graphicle import transform @@ -76,10 +83,13 @@ def check_sign(x): def centre_angle( angle: base.DoubleVector, pt: base.DoubleVector ) -> base.DoubleVector: - """Shifts angles so transverse momentum weighted centroid is at 0. + """Shifts angles so transverse momentum weighted centroid is at + ``0``. :group: transform + .. versionadded:: 0.1.0 + Parameters ---------- angle : array @@ -106,10 +116,12 @@ def centre_angle( def centre_pseudorapidity( eta: base.DoubleVector, pt: base.DoubleVector ) -> base.DoubleVector: - """Shifts pseudorapidities so pt weighted midpoint is at 0. + """Shifts pseudorapidities so pt weighted midpoint is at ``0``. :group: transform + .. versionadded:: 0.1.0 + Parameters ---------- eta : ndarray[float64]