growthcharts 0.1.0__py3-none-any.whl → 0.2.0__py3-none-any.whl

growthcharts/infant.py

@@ -1,5 +1,6 @@
 import pandas as pd
 import matplotlib.pyplot as plt
+import json
 import math
 from scipy.stats import norm
 
@@ -66,181 +67,349 @@ class Infant(Patient):
 
         self.hc = hc
 
-    def plot_wtageinf(self, title=None):
+    def plot_wtageinf(self, title=None, figsize=(12,7), show=True, ax=None):
         """
-        Plot weight-for-age growth chart.
+    Plot weight-for-age growth chart for infants.
 
-        Displays percentile curves and overlays patient's weight.
+    This method draws CDC infant weight percentile curves
+    and overlays the patient's weight measurement.
 
-        Args:
-            title (str, optional):
-                Title of the plot.
-        """
+    The resulting figure can be customized, embedded
+    in applications, or exported as an image file.
 
-        df = self.df_wtageinf
+    Args:
+        title (str, optional):
+            Custom title for the chart.
 
-        self.sex = str(self.sex).lower()
+        figsize (tuple, optional):
+            Figure size in inches (width, height).
+            Default is (12, 7).
 
-        if self.sex in ['m', '1']:
-            self.sex = '1'
-        elif self.sex in ['f', '2']:
-            self.sex = '2'
-        else:
-            raise TypeError('define sex as m or f')
+        show (bool, optional):
+            Whether to display the plot using matplotlib.
+            If False, the plot will not be shown.
+            Default is True.
+
+        ax (matplotlib.axes.Axes, optional):
+            Existing matplotlib Axes object for embedding
+            in custom layouts or applications.
 
-        data = df[df['Sex'] == self.sex]
+    Returns:
+        tuple:
+            (fig, ax)
 
-        plt.figure(figsize=(12, 7))
+            fig : matplotlib.figure.Figure
+                The created matplotlib figure.
+
+            ax : matplotlib.axes.Axes
+                The axes containing the plot.
+    """
+
+        df = self.df_wtageinf
+        sex = self._normalize_sex()
+
+        data = df[df['Sex'] == sex]
+
+        if ax is None:
+            fig, ax = plt.subplots(figsize=figsize)
+        else:
+            fig = ax.figure
 
         for i, col in enumerate(self.agecolumns[1:]):
 
             if i in self.highlight_indices:
-                plt.plot(
+                ax.plot(
                     data['Agemos'], data[col],
                     color='gray', linewidth=2,
-                    label=f'{title} {col}'
+                    label=col
                 )
             else:
-                plt.plot(
+                ax.plot(
                     data['Agemos'], data[col],
                     color='lightgray', linewidth=1
                 )
 
         if self.wt is not None:
-            plt.scatter(self.age, self.wt, color='red',
-                        s=100, zorder=5)
+            ax.scatter(
+                self.age, self.wt,
+                color='red', s=100,
+                zorder=5, label="Patient"
+            )
 
-        plt.title(title)
-        plt.xlabel("age(month)")
-        plt.ylabel("Weight(Kg)")
-        plt.grid(True)
-        plt.legend()
-        plt.show()
+        ax.set_title(title or "Infant Weight for Age")
+        ax.set_xlabel("Age (months)")
+        ax.set_ylabel("Weight (Kg)")
+        ax.grid(True)
+        ax.legend()
 
-    def plot_lenageinf(self, title=None):
-        """
-        Plot length-for-age growth chart.
+        if show:
+            plt.show()
 
-        Displays percentile curves and overlays patient's length.
+        return fig, ax
 
-        Args:
-            title (str, optional):
-                Title of the plot.
+
+    def plot_lenageinf(self, title=None, figsize=(12,7), show=True, ax=None):
         """
+    Plot length-for-age growth chart for infants.
 
-        df = self.df_lenageinf
+    This method draws CDC infant length percentile curves
+    and overlays the patient's length measurement.
 
-        self.sex = str(self.sex).lower()
+    The generated figure can be customized, embedded
+    in applications, or saved to disk.
 
-        if self.sex in ['m', '1']:
-            self.sex = '1'
-        elif self.sex in ['f', '2']:
-            self.sex = '2'
-        else:
-            raise TypeError('define sex as m or f')
+    Args:
+        title (str, optional):
+            Custom title for the chart.
 
-        data = df[df['Sex'] == self.sex]
+        figsize (tuple, optional):
+            Figure size in inches (width, height).
+            Default is (12, 7).
 
-        plt.figure(figsize=(14, 10))
+        show (bool, optional):
+            Whether to display the plot using matplotlib.
+            If False, the plot will not be shown.
+            Default is True.
+
+        ax (matplotlib.axes.Axes, optional):
+            Existing matplotlib Axes object for embedding
+            in custom layouts or applications.
+
+    Returns:
+        tuple:
+            (fig, ax)
+
+            fig : matplotlib.figure.Figure
+                The created matplotlib figure.
+
+            ax : matplotlib.axes.Axes
+                The axes containing the plot.
+    """
+
+        df = self.df_lenageinf
+        sex = self._normalize_sex()
+
+        data = df[df['Sex'] == sex]
+
+        if ax is None:
+            fig, ax = plt.subplots(figsize=figsize)
+        else:
+            fig = ax.figure
 
         for i, col in enumerate(self.agecolumns[1:]):
 
             if i in self.highlight_indices:
-                plt.plot(
+                ax.plot(
                     data['Agemos'], data[col],
                     color='gray', linewidth=2,
-                    label=f'{title} {col}'
+                    label=col
                 )
             else:
-                plt.plot(
+                ax.plot(
                     data['Agemos'], data[col],
                     color='lightgray', linewidth=1
                 )
 
         if self.length is not None:
-            plt.scatter(self.age, self.length,
-                        color='red', s=100, zorder=5)
+            ax.scatter(
+                self.age, self.length,
+                color='red', s=100,
+                zorder=5, label="Patient"
+            )
 
-        plt.title(title)
-        plt.xlabel("age(month)")
-        plt.ylabel("Length(cm)")
-        plt.grid(True)
-        plt.legend()
-        plt.show()
+        ax.set_title(title or "Infant Length for Age")
+        ax.set_xlabel("Age (months)")
+        ax.set_ylabel("Length (cm)")
+        ax.grid(True)
+        ax.legend()
 
-    def plot_hcageinf(self, title=None):
-        """
-        Plot head circumference-for-age growth chart.
+        if show:
+            plt.show()
 
-        Displays percentile curves and overlays patient's head circumference.
+        return fig, ax
 
-        Args:
-            title (str, optional):
-                Title of the plot.
+
+    def plot_hcageinf(self, title=None, figsize=(12,7), show=True, ax=None):
         """
+    Plot head circumference-for-age growth chart for infants.
 
-        df = self.df_hcageinf
+    This method draws CDC head circumference percentile curves
+    and overlays the patient's head circumference measurement.
 
-        self.sex = str(self.sex).lower()
+    The output figure can be customized, embedded in apps,
+    or exported as an image file.
 
-        if self.sex in ['m', '1']:
-            self.sex = '1'
-        elif self.sex in ['f', '2']:
-            self.sex = '2'
-        else:
-            raise TypeError('define sex as m or f')
+    Args:
+        title (str, optional):
+            Custom title for the chart.
+
+        figsize (tuple, optional):
+            Figure size in inches (width, height).
+            Default is (12, 7).
+
+        show (bool, optional):
+            Whether to display the plot using matplotlib.
+            If False, the plot will not be shown.
+            Default is True.
 
-        data = df[df['Sex'] == self.sex]
+        ax (matplotlib.axes.Axes, optional):
+            Existing matplotlib Axes object for embedding
+            in custom layouts or applications.
 
-        plt.figure(figsize=(12, 7))
+    Returns:
+        tuple:
+            (fig, ax)
+
+            fig : matplotlib.figure.Figure
+                The created matplotlib figure.
+
+            ax : matplotlib.axes.Axes
+                The axes containing the plot.
+    """
+
+        df = self.df_hcageinf
+        sex = self._normalize_sex()
+
+        data = df[df['Sex'] == sex]
+
+        if ax is None:
+            fig, ax = plt.subplots(figsize=figsize)
+        else:
+            fig = ax.figure
 
         for i, col in enumerate(self.agecolumns[1:]):
 
             if i in self.highlight_indices:
-                plt.plot(
+                ax.plot(
                     data['Agemos'], data[col],
                     color='gray', linewidth=2,
-                    label=f'{title} {col}'
+                    label=col
                 )
             else:
-                plt.plot(
+                ax.plot(
                     data['Agemos'], data[col],
                     color='lightgray', linewidth=1
                 )
 
         if self.hc is not None:
-            plt.scatter(self.age, self.hc,
-                        color='red', s=100, zorder=5)
+            ax.scatter(
+                self.age, self.hc,
+                color='red', s=100,
+                zorder=5, label="Patient"
+            )
+
+        ax.set_title(title or "Head Circumference for Age")
+        ax.set_xlabel("Age (months)")
+        ax.set_ylabel("HC (cm)")
+        ax.grid(True)
+        ax.legend()
+
+        if show:
+            plt.show()
+
+        return fig, ax
+    
+    def plot_wtleninf(self, title=None, figsize=(12,7), show=True, ax=None):
+        """
+    Plot weight-for-length growth chart for infants.
+
+    This method draws CDC weight-for-length percentile curves
+    and overlays the patient's weight and length measurement.
+
+    It is mainly used for nutritional and growth status
+    assessment in infants.
+
+    The generated figure can be customized, embedded in
+    applications, or exported as an image file.
+
+    Args:
+        title (str, optional):
+            Custom title for the chart.
+
+        figsize (tuple, optional):
+            Figure size in inches (width, height).
+            Default is (12, 7).
+
+        show (bool, optional):
+            Whether to display the plot using matplotlib.
+            If False, the plot will not be shown.
+            Default is True.
+
+        ax (matplotlib.axes.Axes, optional):
+            Existing matplotlib Axes object for embedding
+            in custom layouts or applications.
+
+    Returns:
+        tuple:
+            (fig, ax)
+
+            fig : matplotlib.figure.Figure
+                The created matplotlib figure.
+
+            ax : matplotlib.axes.Axes
+                The axes containing the plot.
+    """
+
+        df = self.df_wtleninf
+        sex = self._normalize_sex()
+
+        data = df[df['Sex'] == sex]
+
+        if ax is None:
+            fig, ax = plt.subplots(figsize=figsize)
+        else:
+            fig = ax.figure
+
+        for i, col in enumerate(self.lencolumns[1:]):
+
+            if i in self.highlight_indices:
+                ax.plot(
+                    data['Length'], data[col],
+                    color='gray', linewidth=2,
+                    label=col
+                )
+            else:
+                ax.plot(
+                    data['Length'], data[col],
+                    color='lightgray', linewidth=1
+                )
 
-        plt.title(title)
-        plt.xlabel("age(month)")
-        plt.ylabel("Head Circumference(cm)")
-        plt.grid(True)
-        plt.legend()
-        plt.show()
+        if self.wt is not None and self.length is not None:
+            ax.scatter(
+                self.length, self.wt,
+                color='red', s=100,
+                zorder=5, label="Patient"
+            )
 
-    def analyze_wtageinf(self):
+        ax.set_title(title or "Weight for Length")
+        ax.set_xlabel("Length (cm)")
+        ax.set_ylabel("Weight (Kg)")
+        ax.grid(True)
+        ax.legend()
+
+        if show:
+            plt.show()
+
+        return fig, ax
+
+
+
+    def analyze_wtageinf(self, as_json=False):
         """
-        Analyze weight-for-age using LMS method.
+        Analyze weight-for-age using LMS method (WHO/CDC).
 
         Returns:
-            dict:
-                Z-score and percentile.
+            dict or json:
+                Z-score, percentile, and interpretation.
         """
 
         df = self.df_wtageinf
 
-        self.sex = str(self.sex).lower()
+        sex = self._normalize_sex()
 
-        if self.sex in ['m', '1']:
-            self.sex = '1'
-        elif self.sex in ['f', '2']:
-            self.sex = '2'
-        else:
-            raise TypeError('define sex as m or f')
-
-        df2 = df[df['Sex'] == self.sex]
+        df2 = df[df['Sex'] == sex]
 
+        # Closest age row
         row = df2.iloc[
             (df2['Agemos'] - self.age).abs().argsort()[:1]
         ]
@@ -249,6 +418,7 @@ class Infant(Patient):
         M = float(row['M'].values[0])
         S = float(row['S'].values[0])
 
+        # LMS Z-score
         if L != 0:
             z = ((self.wt / M) ** L - 1) / (L * S)
         else:
@@ -256,133 +426,157 @@ class Infant(Patient):
 
         percentile = norm.cdf(z) * 100
 
-        return {
-            "Z": round(z, 2),
-            "Percentile": round(percentile, 2)
+        result = {
+            "indicator": "Weight-for-Age",
+            "value": round(self.wt, 2),
+            "unit": "kg",
+            "age_months": round(self.age, 2),
+            "sex": "Male" if sex == "1" else "Female",
+
+            "z_score": round(z, 2),
+            "percentile": round(percentile, 1),
+
+            "z_interpretation": self._interpret_z(z),
+            "percentile_interpretation": self._interpret_percentile(percentile)
         }
 
-    def analyze_lenageinf(self):
-        """
-        Analyze length-for-age using LMS method.
+        if as_json:
+            return json.dumps(result, ensure_ascii=False)
 
-        Returns:
-            dict:
-                Z-score and percentile.
-        """
+        return result
 
-        df = self.df_lenageinf
 
-        self.sex = str(self.sex).lower()
+def analyze_lenageinf(self, return_json=False):
+    """
+    Analyze length-for-age using LMS method.
 
-        if self.sex in ['m', '1']:
-            self.sex = '1'
-        elif self.sex in ['f', '2']:
-            self.sex = '2'
-        else:
-            raise TypeError('define sex as m or f')
+    Args:
+        return_json (bool): If True, returns a JSON string. Default False.
 
-        df2 = df[df['Sex'] == self.sex]
+    Returns:
+        dict or JSON: Z-score, percentile, and interpretation.
+    """
+    df = self.df_lenageinf
+    sex = self._normalize_sex()
+    df2 = df[df['Sex'] == sex]
 
-        row = df2.iloc[
-            (df2['Agemos'] - self.age).abs().argsort()[:1]
-        ]
+    row = df2.iloc[(df2['Agemos'] - self.age).abs().argsort()[:1]]
+    L, M, S = float(row['L'].values[0]), float(row['M'].values[0]), float(row['S'].values[0])
 
-        L = float(row['L'].values[0])
-        M = float(row['M'].values[0])
-        S = float(row['S'].values[0])
+    if L != 0:
+        z = ((self.length / M) ** L - 1) / (L * S)
+    else:
+        z = math.log(self.length / M) / S
 
-        if L != 0:
-            z = ((self.length / M) ** L - 1) / (L * S)
-        else:
-            z = math.log(self.length / M) / S
+    percentile = norm.cdf(z) * 100
 
-        percentile = norm.cdf(z) * 100
 
-        return {
-            "Z": round(z, 2),
-            "Percentile": round(percentile, 2)
-        }
+    result = {
+    "indicator": "Length-for-Age",
+    "value": round(self.length, 2),
+    "unit": "cm",
+    "age_months": round(self.age, 2),
+    "sex": "Male" if sex == "1" else "Female",
 
-    def analyze_hcageinf(self):
-        """
-        Analyze head circumference-for-age using LMS method.
+    "z_score": round(z, 2),
+    "percentile": round(percentile, 1),
 
-        Returns:
-            dict:
-                Z-score and percentile.
-        """
+    "z_interpretation": self._interpret_z(z),
+    "percentile_interpretation": self._interpret_percentile(percentile)
+    }
 
-        df = self.df_hcageinf
+    if return_json:
+        import json
+        return json.dumps(result)
 
-        self.sex = str(self.sex).lower()
+    return result
 
-        if self.sex in ['m', '1']:
-            self.sex = '1'
-        elif self.sex in ['f', '2']:
-            self.sex = '2'
-        else:
-            raise TypeError('define sex as m or f')
 
-        df2 = df[df['Sex'] == self.sex]
+def analyze_hcageinf(self, return_json=False):
+    """
+    Analyze head circumference-for-age using LMS method.
 
-        row = df2.iloc[
-            (df2['Agemos'] - self.age).abs().argsort()[:1]
-        ]
+    Args:
+        return_json (bool): If True, returns a JSON string. Default False.
 
-        L = float(row['L'].values[0])
-        M = float(row['M'].values[0])
-        S = float(row['S'].values[0])
+    Returns:
+        dict or JSON: Z-score, percentile, and interpretation.
+    """
+    df = self.df_hcageinf
+    sex = self._normalize_sex()
+    df2 = df[df['Sex'] == sex]
 
-        if L != 0:
-            z = ((self.hc / M) ** L - 1) / (L * S)
-        else:
-            z = math.log(self.hc / M) / S
+    row = df2.iloc[(df2['Agemos'] - self.age).abs().argsort()[:1]]
+    L, M, S = float(row['L'].values[0]), float(row['M'].values[0]), float(row['S'].values[0])
 
-        percentile = norm.cdf(z) * 100
+    if L != 0:
+        z = ((self.hc / M) ** L - 1) / (L * S)
+    else:
+        z = math.log(self.hc / M) / S
 
-        return {
-            "Z": round(z, 2),
-            "Percentile": round(percentile, 2)
-        }
+    percentile = norm.cdf(z) * 100
 
-    def analyze_wtleninf(self):
-        """
-        Analyze weight-for-length using LMS method.
+    result = {
+        "indicator": "Head Circumference-for-Age",
+        "value": round(self.hc, 2),
+        "unit": "cm",
+        "age_months": round(self.age, 2),
+        "sex": "Male" if sex == "1" else "Female",
 
-        Returns:
-            dict:
-                Z-score and percentile.
-        """
+        "z_score": round(z, 2),
+        "percentile": round(percentile, 1),
 
-        df = self.df_wtleninf
+        "z_interpretation": self._interpret_z(z),
+        "percentile_interpretation": self._interpret_percentile(percentile)
+    }
 
-        self.sex = str(self.sex).lower()
+    if return_json:
+        import json
+        return json.dumps(result)
 
-        if self.sex in ['m', '1']:
-            self.sex = '1'
-        elif self.sex in ['f', '2']:
-            self.sex = '2'
-        else:
-            raise TypeError('define sex as m or f')
+    return result
 
-        df2 = df[df['Sex'] == self.sex]
 
-        row = df2.iloc[
-            (df2['Length'] - self.length).abs().argsort()[:1]
-        ]
+def analyze_wtleninf(self, return_json=False):
+    """
+    Analyze weight-for-length using LMS method.
 
-        L = float(row['L'].values[0])
-        M = float(row['M'].values[0])
-        S = float(row['S'].values[0])
+    Args:
+        return_json (bool): If True, returns a JSON string. Default False.
 
-        if L != 0:
-            z = ((self.wt / M) ** L - 1) / (L * S)
-        else:
-            z = math.log(self.wt / M) / S
+    Returns:
+        dict or JSON: Z-score, percentile, and interpretation.
+    """
+    df = self.df_wtleninf
+    sex = self._normalize_sex()
+    df2 = df[df['Sex'] == sex]
 
-        percentile = norm.cdf(z) * 100
+    row = df2.iloc[(df2['Length'] - self.length).abs().argsort()[:1]]
+    L, M, S = float(row['L'].values[0]), float(row['M'].values[0]), float(row['S'].values[0])
 
-        return {
-            "Z": round(z, 2),
-            "Percentile": round(percentile, 2)
-        }
+    if L != 0:
+        z = ((self.wt / M) ** L - 1) / (L * S)
+    else:
+        z = math.log(self.wt / M) / S
+
+    percentile = norm.cdf(z) * 100
+
+    result = {
+        "indicator": "Weight-for-Length",
+        "value": round(self.wt, 2),
+        "unit": None,
+        "length_cm": round(self.length, 2),
+        "sex": "Male" if sex == "1" else "Female",
+
+        "z_score": round(z, 2),
+        "percentile": round(percentile, 1),
+
+        "z_interpretation": self._interpret_z(z),
+        "percentile_interpretation": self._interpret_percentile(percentile)
+    }
+
+    if return_json:
+        import json
+        return json.dumps(result)
+
+    return result