morphgen-rates 0.3.0__tar.gz → 0.5.0__tar.gz

{morphgen_rates-0.3.0/src/morphgen_rates.egg-info → morphgen_rates-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: morphgen-rates
-Version: 0.3.0
+Version: 0.5.0
 Summary: Compute bifurcation and annihilation rates from morphology data
 Author-email: Francesco Cavarretta <fcavarretta@ualr.edu>
 Requires-Python: >=3.9

{morphgen_rates-0.3.0 → morphgen_rates-0.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "morphgen-rates"
-version = "0.3.0"
+version = "0.5.0"
 description = "Compute bifurcation and annihilation rates from morphology data"
 authors = [
   { name = "Francesco Cavarretta", email = "fcavarretta@ualr.edu" },

morphgen_rates-0.5.0/src/morphgen_rates/__init__.py

@@ -0,0 +1,4 @@
+from .rates import compute_rates
+from .data import get_data
+from .init_count import compute_init_number_probs
+__all__ = ["compute_rates", "get_data", "compute_init_number_probs"]

morphgen_rates-0.5.0/src/morphgen_rates/data.py

@@ -0,0 +1,145 @@
+import pandas as pd
+from pathlib import Path
+
+
+def _local_data_path(filename='morph_data', ext="csv"):
+  """
+  Build a path like: <this_file_dir>/data/<filename>.<ext>
+
+  Parameters
+  ----------
+  filename : str
+      Base filename (without extension)
+  ext : str, default "csv"
+      File extension (without the dot)
+
+  Returns
+  -------
+  pathlib.Path
+      Full path to the data file
+  """
+  work_dir = Path(__file__).resolve().parent
+  return work_dir / f"{filename}.{ext}"
+
+
+def get_data(area, neuron_type):
+  """
+  Retrieve summary morphology statistics for a given brain area and neuron class.
+
+  This function loads a local CSV dataset, filters rows matching the requested
+  `area` and `neuron_type`, and aggregates statistics by `section_type`. The
+  output is a nested dictionary keyed by section type (e.g., soma, apical, basal),
+  containing:
+
+  - Summary statistics for bifurcation counts and total length
+  - Estimated number of primary neurites at the soma (Count0)
+  - Sholl plot summary statistics (bin size, mean counts, standard deviation)
+
+  Parameters
+  ----------
+  area : str
+      Brain region identifier used in the dataset (must match values in the
+      'area' column of the CSV)
+  neuron_type : str
+      Neuron class identifier used in the dataset (must match values in the
+      'neuron_type' column of the CSV)
+
+  Returns
+  -------
+  dict
+      Nested dictionary structured as:
+
+      data = {
+        "<section_type>": {
+          "bifurcation_count": {"mean": ..., "std": ..., "min": ..., "max": ...},
+          "total_length": {"mean": ..., "std": ..., "min": ..., "max": ...},
+          "primary_count": {"mean": ..., "std": ..., "min": ..., "max": ...},
+          "sholl_plot": {
+            "bin_size": float,
+            "mean": list[float],
+            "std": list[float],
+          },
+        },
+        ...
+      }
+
+      Notes on fields:
+      - `primary_count` corresponds to the row group labeled 'Count0'
+      - Sholl values are collected from rows whose metric name starts with 'Count'
+        (including 'Count0'); users may want to interpret/plot them as a function
+        of radial bin index multiplied by `bin_size`
+
+  Raises
+  ------
+  AssertionError
+      If no rows match the requested `area` and `neuron_type`
+
+  Notes
+  -----
+  - The function expects the local CSV to include at least the following columns:
+      'area', 'neuron_type', 'neuron_name', 'section_type', 'bin_size'
+      plus metric columns including:
+        - 'bifurcation_count'
+        - 'total_length'
+        - 'Count0', 'Count1', ... (Sholl counts per radial bin)
+  - Statistics are computed using `pandas.DataFrame.groupby(...).describe()`.
+    Only the summary columns 'mean', 'std', 'min', 'max' are retained.
+
+  Examples
+  --------
+  >>> data = get_data("CTX", "pyr")
+  >>> data["apical"]["bifurcation_count"]["mean"]
+  42.0
+  >>> data["apical"]["sholl_plot"]["bin_size"]
+  50.0
+  >>> len(data["apical"]["sholl_plot"]["mean"])
+  20
+  """
+  
+  data = {}
+
+  area, neuron_type = parts
+    
+  # load data
+  df = pd.read_csv(_local_data_path(), index_col=0)
+
+  # select specific area and neuron type
+  df = df[(df['area'] == area) & (df['neuron_type'] == neuron_type)]
+
+  # ensure that there are area and neuron_type in the df
+  assert df.shape[0] > 0, "The area {area} or neuron class {neuron_type} are not known"
+  
+  # neuron name unnecessary
+  df.drop(['area', 'neuron_type', 'neuron_name'], axis=1, inplace=True)
+
+  # statistics
+  df = df.groupby('section_type').describe()
+
+  # select only a subset of columns
+  df = df.loc[:, df.columns.get_level_values(1).isin(['mean', 'std', 'min', 'max'])]
+
+  # get subsections
+  for section_type, row in df.iterrows():
+    data[section_type] = {}
+
+    # get statistics
+    for data_type in ['bifurcation_count', 'total_length']:
+      tmp = row.loc[row.index.get_level_values(0) == data_type, :]
+      tmp.index = tmp.index.droplevel(0)
+      data[section_type][data_type] = tmp.to_dict()
+
+    # count neurites at the soma
+    tmp = row.loc[row.index.get_level_values(0) == 'Count0', :]
+    tmp.index = tmp.index.droplevel(0)
+    data[section_type]['primary_count'] = tmp.to_dict()
+    
+    # sholl plots
+    tmp = row.loc[row.index.get_level_values(0).str.startswith('Count'), :]
+    data[section_type]['sholl_plot'] = {
+      'bin_size':row[('bin_size', 'mean')].tolist(),
+      'mean':tmp.loc[tmp.index.get_level_values(1) == 'mean', :].tolist(),
+      'std':tmp.loc[tmp.index.get_level_values(1) == 'std', :].tolist()
+      }
+
+  return data
+

morphgen_rates-0.5.0/src/morphgen_rates/init_count.py

@@ -0,0 +1,208 @@
+from __future__ import annotations
+
+from typing import Dict, Optional, Sequence, Union
+
+import numpy as np
+import pyomo.environ as pyo
+
+
+def compute_init_number_probs(
+    mean_primary_dendrites: float,
+    sd_primary_dendrites: float,
+    min_primary_dendrites: int,
+    max_primary_dendrites: int,
+    *,
+    support_values: Optional[Sequence[float]] = None,
+    epsilon: float = 1e-12,
+    slack_penalty: float = 1e-1,
+    use_variance_form: bool = True,
+    use_abs_slack: bool = False,
+    solver: str = "ipopt",
+    solver_options: Optional[Dict[str, Union[str, int, float]]] = None,
+) -> np.ndarray:
+    """
+    Maximum-entropy PMF for the (discrete) number of primary dendrites.
+
+    This returns a numpy array p of length n = max_primary_dendrites + 1, where:
+      - p[i] is the probability of observing i primary dendrites
+      - p[i] = 0 for i < min_primary_dendrites or i > max_primary_dendrites
+
+    The distribution is obtained by maximizing Shannon entropy:
+        H(p) = -sum_i p[i] * log(p[i])
+
+    Subject to:
+      - Normalization: sum_{i in [min,max]} p[i] = 1
+      - Soft mean constraint (with slack):
+            sum i*p[i] - mean_primary_dendrites = slack_mean
+      - Soft dispersion constraint (with slack):
+        If use_variance_form=True (recommended):
+            sum (i-mean)^2 * p[i] - (sd_primary_dendrites^2) = slack_disp
+        If use_variance_form=False:
+            sqrt( sum (i-mean)^2 * p[i] + tiny ) - sd_primary_dendrites = slack_disp
+
+    The objective is penalized to keep slacks small:
+        maximize  H(p) - slack_penalty * (slack terms)
+
+    Parameters
+    ----------
+    mean_primary_dendrites : float
+        Target mean number of primary dendrites
+    sd_primary_dendrites : float
+        Target standard deviation (>= 0)
+    min_primary_dendrites : int
+        Minimum allowed dendrite count (inclusive)
+    max_primary_dendrites : int
+        Maximum allowed dendrite count (inclusive). Also sets array length n=max+1
+
+    Keyword-only parameters
+    ----------------------
+    support_values : Sequence[float] | None
+        Optional support for indices 0..max. If None, uses support=i (integers).
+        Keep this None if you truly mean "i is the dendrite count".
+    epsilon : float
+        Lower bound on active probabilities to avoid log(0)
+    slack_penalty : float
+        Larger values enforce closer moment matching
+    use_variance_form : bool
+        Recommended True: match variance to sd^2 (smoother than sqrt constraint)
+    use_abs_slack : bool
+        If True, use L1-like slack penalty via +/- variables; otherwise squared (smooth)
+    solver : str
+        Nonlinear solver name (typically "ipopt")
+    solver_options : dict | None
+        Passed to the solver (e.g., {"max_iter": 5000})
+
+    Returns
+    -------
+    np.ndarray
+        Probability vector p with length max_primary_dendrites + 1
+
+    Raises
+    ------
+    ValueError
+        For invalid inputs
+    RuntimeError
+        If the requested solver is not available
+    """
+    if max_primary_dendrites < 0:
+        raise ValueError("max_primary_dendrites must be >= 0")
+    if sd_primary_dendrites < 0:
+        raise ValueError("sd_primary_dendrites must be nonnegative")
+    if not (0 <= min_primary_dendrites <= max_primary_dendrites):
+        raise ValueError("Require 0 <= min_primary_dendrites <= max_primary_dendrites")
+    if slack_penalty <= 0:
+        raise ValueError("slack_penalty must be positive")
+    if epsilon <= 0:
+        raise ValueError("epsilon must be positive")
+
+    n = max_primary_dendrites + 1
+    active = list(range(min_primary_dendrites, max_primary_dendrites + 1))
+
+    # Support values for each index i (default: i itself)
+    if support_values is None:
+        support_values = list(range(n))
+    if len(support_values) != n:
+        raise ValueError("support_values must have length n = max_primary_dendrites + 1")
+
+    support = {i: float(support_values[i]) for i in range(n)}
+    mu = float(mean_primary_dendrites)
+    sd = float(sd_primary_dendrites)
+    target_var = sd * sd
+
+    # -----------------------------
+    # Pyomo model
+    # -----------------------------
+    m = pyo.ConcreteModel()
+    m.A = pyo.Set(initialize=active, ordered=True)
+
+    # Decision variables for active probabilities only
+    m.p = pyo.Var(m.A, domain=pyo.NonNegativeReals, bounds=(epsilon, 1.0))
+
+    # Normalization over active set
+    m.norm = pyo.Constraint(expr=sum(m.p[i] for i in m.A) == 1.0)
+
+    # Moment expressions
+    mean_expr = sum(support[i] * m.p[i] for i in m.A)
+    var_expr = sum((support[i] - mu) ** 2 * m.p[i] for i in m.A)
+
+    # Soft constraints with slack
+    if use_abs_slack:
+        # L1 slack via +/- decomposition
+        m.s_mean_pos = pyo.Var(domain=pyo.NonNegativeReals)
+        m.s_mean_neg = pyo.Var(domain=pyo.NonNegativeReals)
+        m.s_disp_pos = pyo.Var(domain=pyo.NonNegativeReals)
+        m.s_disp_neg = pyo.Var(domain=pyo.NonNegativeReals)
+
+        m.mean_soft = pyo.Constraint(expr=mean_expr - mu == m.s_mean_pos - m.s_mean_neg)
+
+        if use_variance_form:
+            m.disp_soft = pyo.Constraint(expr=var_expr - target_var == m.s_disp_pos - m.s_disp_neg)
+        else:
+            tiny = 1e-18
+            m.disp_soft = pyo.Constraint(
+                expr=pyo.sqrt(var_expr + tiny) - sd == m.s_disp_pos - m.s_disp_neg
+            )
+
+        slack_term = (m.s_mean_pos + m.s_mean_neg) + (m.s_disp_pos + m.s_disp_neg)
+
+    else:
+        # Smooth squared slacks
+        m.s_mean = pyo.Var(domain=pyo.Reals)
+        m.s_disp = pyo.Var(domain=pyo.Reals)
+
+        m.mean_soft = pyo.Constraint(expr=mean_expr - mu == m.s_mean)
+
+        if use_variance_form:
+            m.disp_soft = pyo.Constraint(expr=var_expr - target_var == m.s_disp)
+        else:
+            tiny = 1e-18
+            m.disp_soft = pyo.Constraint(expr=pyo.sqrt(var_expr + tiny) - sd == m.s_disp)
+
+        slack_term = m.s_mean**2 + m.s_disp**2
+
+    # Entropy objective (active probs only; inactive probs are exactly 0)
+    entropy = -sum(m.p[i] * pyo.log(m.p[i]) for i in m.A)
+    m.obj = pyo.Objective(expr=entropy - float(slack_penalty) * slack_term, sense=pyo.maximize)
+
+    # Solve
+    opt = pyo.SolverFactory(solver)
+    if opt is None or not opt.available():
+        raise RuntimeError(
+            f"Solver '{solver}' is not available. Install/configure it (e.g., ipopt) "
+            "or pass a different solver name."
+        )
+    if solver_options:
+        for k, v in solver_options.items():
+            opt.options[k] = v
+
+    res = opt.solve(m, tee=False)
+
+    # -----------------------------
+    # Extract solution into numpy array
+    # -----------------------------
+    p = np.zeros(n, dtype=float)
+    for i in active:
+        p[i] = float(pyo.value(m.p[i]))
+
+    # Optional: renormalize tiny numerical drift (keeps zeros outside band)
+    s = p.sum()
+    if s > 0:
+        p[active] /= s
+
+    return p
+
+
+if __name__ == "__main__":
+    p = maxent_primary_dendrite_pmf(
+        mean_primary_dendrites=2.33,
+        sd_primary_dendrites=1.53,
+        min_primary_dendrites=1,
+        max_primary_dendrites=4,
+        slack_penalty=0.1,
+        use_variance_form=True,
+        use_abs_slack=False,
+        solver="ipopt",
+    )
+    print("p shape:", p.shape)
+    print("sum:", p.sum())
+    print(p)

{morphgen_rates-0.3.0 → morphgen_rates-0.5.0/src/morphgen_rates.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: morphgen-rates
-Version: 0.3.0
+Version: 0.5.0
 Summary: Compute bifurcation and annihilation rates from morphology data
 Author-email: Francesco Cavarretta <fcavarretta@ualr.edu>
 Requires-Python: >=3.9

{morphgen_rates-0.3.0 → morphgen_rates-0.5.0}/src/morphgen_rates.egg-info/SOURCES.txt

@@ -3,10 +3,12 @@ README.md
 pyproject.toml
 src/morphgen_rates/__init__.py
 src/morphgen_rates/data.py
+src/morphgen_rates/init_count.py
 src/morphgen_rates/rates.py
 src/morphgen_rates.egg-info/PKG-INFO
 src/morphgen_rates.egg-info/SOURCES.txt
 src/morphgen_rates.egg-info/dependency_links.txt
 src/morphgen_rates.egg-info/requires.txt
 src/morphgen_rates.egg-info/top_level.txt
-tests/test.py
+tests/test_primary_count.py
+tests/test_rates.py

morphgen_rates-0.5.0/tests/test_primary_count.py

@@ -0,0 +1,38 @@
+"""
+Minimal test example: empirical distribution of primary dendrites.
+
+This script loads summary statistics for aPC pyramidal neurons (apical dendrite),
+extracts the primary dendrite stats (Count0), and converts them into a discrete
+probability distribution using `compute_init_number_probs`.
+
+`probs[i]` is the probability of generating i primary dendrites.
+"""
+
+from morphgen_rates import get_data, compute_init_number_probs
+
+if __name__ == "__main__":
+  # Load summary statistics and select the apical dendrite section
+  data = get_data("aPC", "PYR")["apical_dendrite"]
+
+  # Primary dendrite stats (derived from Count0)
+  stats = data["primary_count"]
+
+  mean_primary = float(stats["mean"])
+  sd_primary   = float(stats["std"])
+  min_primary  = int(stats["min"])
+  max_primary  = int(stats["max"])
+
+  probs = compute_init_number_probs(
+    mean_primary_dendrites=mean_primary,
+    sd_primary_dendrites=sd_primary,
+    min_primary_dendrites=min_primary,
+    max_primary_dendrites=max_primary,
+  )
+
+  print("Primary dendrite stats:")
+  print(f"  mean={mean_primary}, std={sd_primary}, min={min_primary}, max={max_primary}")
+
+  print("\nP(# primary dendrites = i):")
+  for i, p in enumerate(probs):
+    if p > 0:
+      print(f"  i={i}: {p:.6f}")

morphgen_rates-0.5.0/tests/test_rates.py

@@ -0,0 +1,23 @@
+"""
+Minimal test example: compute bifurcation and annihilation rates from packaged data.
+"""
+
+from morphgen_rates import compute_rates, get_data
+
+if __name__ == "__main__":
+  # Load summary statistics for aPC pyramidal neurons and select the apical dendrite section
+  data = get_data("aPC", "PYR")["apical_dendrite"]
+
+  # (Optional) inspect the input dictionary used by the estimator
+  print("Input data keys:", list(data.keys()))
+  print("Sholl bin size:", data["sholl"]["bin_size"])
+
+  # Maximum advancement (distance from soma) allowed for one elongation step
+  max_step_size = 5.0
+
+  # Estimate rates
+  rates = compute_rates(data, max_step_size=max_step_size)
+
+  print("Bifurcation rate:", rates.get("bifurcation_rate"))
+  print("Annihilation rate:", rates.get("annihilation_rate"))
+

morphgen_rates-0.3.0/src/morphgen_rates/__init__.py

@@ -1,3 +0,0 @@
-from .rates import compute_rates
-from .data import get_data
-__all__ = ["compute_rates", "get_data"]

morphgen_rates-0.3.0/src/morphgen_rates/data.py

@@ -1,147 +0,0 @@
-import pandas as pd
-from pathlib import Path
-
-
-def _local_data_path(filename='morph_data', ext="csv"):
-  """
-  Build a path like: <this_file_dir>/data/<filename>.<ext>
-
-  Parameters
-  ----------
-  filename : str
-      Base filename (without extension)
-  ext : str, default "csv"
-      File extension (without the dot)
-
-  Returns
-  -------
-  pathlib.Path
-      Full path to the data file
-  """
-  work_dir = Path(__file__).resolve().parent
-  return work_dir / f"{filename}.{ext}"
-
-
-def get_data(key):
-  """
-  Retrieve a dataset entry using a key-path of the form
-  "<brain region>/<neuron class>/<subcellular section>".
-
-  The argument `data_path` is interpreted as a slash-separated path of keys used
-  to traverse a nested dataset dictionary. The selected dataset is expected to
-  contain both Sholl-plot statistics and bifurcation statistics; when both are
-  available, this function returns a standardized dictionary compatible with
-  `compute_rates`.
-
-  Parameters
-  ----------
-  key : str
-      Dataset identifier expressed as a key path:
-
-      "<brain region>/<neuron class>/<subcellular section>"
-
-      Examples:
-      - "CTX/pyr/apical"
-      - "HPC/pyr/basal"
-
-      Each component is used as a successive key lookup into the nested dataset
-      container.
-
-  Returns
-  -------
-  dict
-      If both Sholl and bifurcation information are present for the selected dataset,
-      returns:
-
-      data = {
-        "sholl": {
-          "bin_size": float,
-          "mean": numpy.ndarray,   # shape (K,)
-          "var":  numpy.ndarray,   # shape (K,)
-        },
-        "bifurcations": {
-          "mean": float,
-          "var":  float,
-        },
-      }
-
-      Where:
-      - `data["sholl"]["bin_size"]` is the spatial bin size used to define Sholl shells
-      - `data["sholl"]["mean"]` is the mean Sholl intersection count per radial bin
-      - `data["sholl"]["var"]` is the variance of the Sholl intersection count per bin
-      - `data["bifurcations"]["mean"]` is the mean bifurcation count
-      - `data["bifurcations"]["var"]` is the variance of the bifurcation count
-
-  Raises
-  ------
-  KeyError
-      If any key along `data_path` is missing (brain region, neuron class, or section)
-  ValueError
-      If the selected dataset does not contain both Sholl and bifurcation data, or
-      if the provided arrays have incompatible shapes
-
-  Notes
-  -----
-  - `data_path` is a *key path*, not a filesystem path
-  - The function assumes the dataset entry referenced by `data_path` includes:
-      - Sholl bin size, mean array, variance array
-      - Bifurcation mean and variance
-
-  Examples
-  --------
-  >>> data = get("CTX/pyr/apical")
-  >>> data["sholl"]["bin_size"]
-  50.0
-  >>> data["bifurcations"]["mean"]
-  12.3
-  """
-  data = {}
-
-  # split the key
-  parts = tuple(p.strip() for p in key.split("/") if p.strip())
-  if len(parts) != 2:
-      raise ValueError(f"Expected key like 'area/neuron_type', got: {key!r}")
-  area, neuron_type = parts
-    
-  # load data
-  df = pd.read_csv(_local_data_path(), index_col=0)
-
-  # select specific area and neuron type
-  df = df[(df['area'] == area) & (df['neuron_type'] == neuron_type)]
-  
-  # neuron name unnecessary
-  df.drop(['area', 'neuron_type', 'neuron_name'], axis=1, inplace=True)
-
-  # statistics
-  df = df.groupby('section_type').describe()
-
-  # select only a subset of columns
-  df = df.loc[:, df.columns.get_level_values(1).isin(['mean', 'std', 'min', 'max'])]
-
-  # get subsections
-  for section_type, row in df.iterrows():
-    data[section_type] = {}
-
-    print()
-
-    # get statistics
-    for data_type in ['bifurcation_count', 'total_length']:
-      tmp = row.loc[row.index.get_level_values(0) == data_type, :]
-      tmp.index = tmp.index.droplevel(0)
-      data[section_type][data_type] = tmp.to_dict()
-
-    # count neurites at the soma
-    tmp = row.loc[row.index.get_level_values(0) == 'Count0', :]
-    tmp.index = tmp.index.droplevel(0)
-    data[section_type]['primary_count'] = tmp.to_dict()
-    
-    # sholl plots
-    tmp = row.loc[row.index.get_level_values(0).str.startswith('Count'), :]
-    data[section_type]['sholl_plot'] = {
-      'bin_size':row[('bin_size', 'mean')].tolist(),
-      'mean':tmp.loc[tmp.index.get_level_values(1) == 'mean', :].tolist(),
-      'std':tmp.loc[tmp.index.get_level_values(1) == 'std', :].tolist()
-      }
-
-  return data
-

morphgen_rates-0.3.0/tests/test.py

@@ -1,14 +0,0 @@
-import pandas as pd
-from morphgen_rates import compute_rates, get_data
-
-# Bundle inputs exactly as loaded (no preprocessing)
-data = get_data('aPC/PYR')['apical_dendrite']
-
-print(data)
-
-max_step_size = 5.
-
-rates = compute_rates(data, max_step_size=max_step_size)
-
-print("Bifurcation rate:", rates.get("bifurcation_rate"))
-print("Annihilation rate:", rates.get("annihilation_rate"))