microdf-python 0.4.3__py3-none-any.whl → 0.4.5__py3-none-any.whl

microdf/__init__.py

@@ -1,6 +1,4 @@
 from .agg import agg, combine_base_reform, pctchg_base_reform
-from .chart_utils import dollar_format, currency_format
-from .charts import quantile_pct_chg_plot
 from .concat import concat
 from .constants import (
     BENS,
@@ -32,21 +30,22 @@ from .inequality import (
     gini,
     t10_b50,
     top_0_1_pct_share,
-    top_10_pct_share,
     top_1_pct_share,
+    top_10_pct_share,
     top_50_pct_share,
     top_x_pct_share,
 )
 from .io import read_stata_zip
+from .microdataframe import MicroDataFrame, MicroDataFrameGroupBy
+from .microseries import MicroSeries, MicroSeriesGroupBy
 from .poverty import (
-    fpl,
-    poverty_rate,
+    deep_poverty_gap,
     deep_poverty_rate,
+    fpl,
     poverty_gap,
+    poverty_rate,
     squared_poverty_gap,
-    deep_poverty_gap,
 )
-from .style import AXIS_COLOR, DPI, GRID_COLOR, TITLE_COLOR, set_plot_style
 from .tax import mtr, tax_from_mtrs
 from .taxcalc import (
     add_weighted_metrics,
@@ -72,7 +71,6 @@ from .weighted import (
     weighted_quantile,
     weighted_sum,
 )
-from .generic import MicroDataFrame, MicroSeries
 
 name = "microdf"
 __version__ = "0.1.0"
@@ -82,11 +80,6 @@ __all__ = [
     "combine_base_reform",
     "pctchg_base_reform",
     "agg",
-    # chart_utils.py
-    "dollar_format",
-    "currency_format",
-    # charts.py
-    "quantile_pct_chg_plot",
     # concat.py
     "concat",
     # constants.py
@@ -133,12 +126,6 @@ __all__ = [
     "poverty_gap",
     "squared_poverty_gap",
     "deep_poverty_gap",
-    # style.py
-    "AXIS_COLOR",
-    "DPI",
-    "GRID_COLOR",
-    "TITLE_COLOR",
-    "set_plot_style",
     # tax.py
     "mtr",
     "tax_from_mtrs",
@@ -164,7 +151,10 @@ __all__ = [
     "weighted_median",
     "add_weighted_quantiles",
     "quantile_chg",
-    # generic.py
+    # microseries.py
     "MicroSeries",
+    "MicroSeriesGroupBy",
+    # microdataframe.py
     "MicroDataFrame",
+    "MicroDataFrameGroupBy",
 ]

microdf/_optional.py

@@ -2,7 +2,7 @@ import distutils.version
 import importlib
 import types
 import warnings
-
+from typing import Optional, Union
 
 # Adapted from:
 # https://github.com/pandas-dev/pandas/blob/master/pandas/compat/_optional.py
@@ -31,14 +31,13 @@ def _get_version(module: types.ModuleType) -> str:
 
 def import_optional_dependency(
     name: str,
-    extra: str = "",
-    raise_on_missing: bool = True,
-    on_version: str = "raise",
-):
-    """Import an optional dependency.
-    By default, if a dependency is missing an ImportError with a nice
-    message will be raised. If a dependency is present, but too old,
-    we raise.
+    extra: Optional[str] = "",
+    raise_on_missing: Optional[bool] = True,
+    on_version: Optional[str] = "raise",
+) -> Union[types.ModuleType, None]:
+    """Import an optional dependency. By default, if a dependency is missing an
+    ImportError with a nice message will be raised. If a dependency is present,
+    but too old, we raise.
 
     :param name: The module name. This should be top-level only, so that the
         version may be checked.

microdf/agg.py

@@ -1,15 +1,16 @@
-import pandas as pd
 from typing import Optional
 
+import pandas as pd
+
 import microdf as mdf
 
 
 def combine_base_reform(
     base: pd.DataFrame,
     reform: pd.DataFrame,
-    base_cols: Optional[list],
-    cols: Optional[list],
-    reform_cols: Optional[list],
+    base_cols: Optional[list] = None,
+    cols: Optional[list] = None,
+    reform_cols: Optional[list] = None,
 ) -> pd.DataFrame:
     """Combine base and reform with certain columns.
 
@@ -25,7 +26,6 @@ def combine_base_reform(
     :type reform_cols: list, optional
     :returns: DataFrame with columns for base ("_base") and reform ("_reform").
     :rtype: pd.DataFrame
-
     """
     all_base_cols = mdf.listify([base_cols] + [cols])
     all_reform_cols = mdf.listify([reform_cols] + [cols])
@@ -35,17 +35,15 @@ def combine_base_reform(
 
 
 def pctchg_base_reform(combined: pd.DataFrame, metric: str) -> pd.Series:
-    """Calculates the percentage change in a metric for a combined
-        dataset.
+    """Calculates the percentage change in a metric for a combined dataset.
 
     :param combined: Combined DataFrame with _base and _reform columns.
     :type combined: pd.DataFrame
-    :param metric: String of the column to calculate the difference.
-        Must exist as metric_m_base and metric_m_reform in combined.
+    :param metric: String of the column to calculate the difference. Must exist
+        as metric_m_base and metric_m_reform in combined.
     :type metric: str
     :returns: Series with percentage change.
     :rtype: pd.Series
-
     """
     return combined[metric + "_m_reform"] / combined[metric + "_m_base"] - 1
 
@@ -55,8 +53,8 @@ def agg(
     reform: pd.DataFrame,
     groupby: str,
     metrics: list,
-    base_metrics: Optional[list],
-    reform_metrics: Optional[list],
+    base_metrics: Optional[list] = None,
+    reform_metrics: Optional[list] = None,
 ) -> pd.DataFrame:
     """Aggregates differences between base and reform.
 
@@ -67,8 +65,8 @@ def agg(
     :param groupby: Variable in base to group on.
     :type groupby: str
     :param metrics: List of variables to agg and calculate the % change of.
-        These should have associated weighted columns ending in _m in base
-        and reform.
+        These should have associated weighted columns ending in _m in base and
+        reform.
     :type metrics: list
     :param base_metrics: List of variables from base to sum.
     :type base_metrics: Optional[list]
@@ -76,7 +74,6 @@ def agg(
     :type reform_metrics: Optional[list]
     :returns: DataFrame with groupby and metrics, and _pctchg metrics.
     :rtype: pd.DataFrame
-
     """
     metrics = mdf.listify(metrics)
     metrics_m = [i + "_m" for i in metrics]

microdf/concat.py

@@ -1,12 +1,15 @@
-import pandas as pd
 import inspect
+
+import pandas as pd
+
 import microdf as mdf
+from microdf.microdataframe import MicroDataFrame
 
 
-def concat(*args, **kwargs):
-    """Concatenates MicroDataFrame objects, preserving weights.
-    If concatenating horizontally, the first set of weights are used.
-    All args and kwargs are passed to pd.concat.
+def concat(*args, **kwargs) -> "MicroDataFrame":
+    """Concatenates MicroDataFrame objects, preserving weights. If
+    concatenating horizontally, the first set of weights are used. All args and
+    kwargs are passed to pd.concat.
 
     :return: MicroDataFrame with concatenated weights.
     :rtype: mdf.MicroDataFrame

microdf/custom_taxes.py

@@ -1,13 +1,14 @@
-"""
-Functions and data for estimating taxes outside the income tax system.
+"""Functions and data for estimating taxes outside the income tax system.
+
 Examples include value added tax, financial transaction tax, and carbon tax.
 """
 
-import microdf as mdf
+from typing import Optional
 
 import numpy as np
 import pandas as pd
 
+import microdf as mdf
 
 # Source:
 # https://www.taxpolicycenter.org/briefing-book/who-would-bear-burden-vat
@@ -35,24 +36,24 @@ FTT_INCIDENCE /= 100
 
 
 def add_custom_tax(
-    df,
-    segment_income,
-    w,
-    base_income,
-    incidence,
-    name,
-    total=None,
-    ratio=None,
-    verbose=True,
-):
+    df: pd.DataFrame,
+    segment_income: str,
+    w: str,
+    base_income: str,
+    incidence: pd.Series,
+    name: str,
+    total: Optional[float] = None,
+    ratio: Optional[float] = None,
+    verbose: Optional[bool] = True,
+) -> None:
     """Add a custom tax based on incidence analysis driven by percentiles.
 
     :param df: DataFrame.
     :param segment_income: Income measure used to segment tax units into
-            quantiles.
+        quantiles.
     :param w: Weight used to segment into quantiles (either s006 or XTOT_m).
     :param base_income: Income measure by which incidence is multiplied to
-            estimate liability.
+        estimate liability.
     :param incidence: pandas Series indexed on the floor of an income
         percentile, with values for the tax rate.
     :param name: Name of the column to add.
@@ -60,13 +61,12 @@ def add_custom_tax(
         liabilities are calculated only based on the incidence schedule.
         (Default value = None)
     :param ratio: Ratio to adjust the tax by, compared to the original tax.
-        This acts as a multiplier for the incidence argument.
-        (Default value = None)
+        This acts as a multiplier for the incidence argument. (Default value =
+        None)
     :param verbose: Whether to print the tax adjustment factor if needed.
         Defaults to True.
     :returns: Nothing. Adds the column name to df representing the tax
         liability. df is also sorted by segment_income.
-
     """
     if ratio is not None:
         incidence = incidence * ratio
@@ -95,14 +95,14 @@ def add_custom_tax(
 
 
 def add_vat(
-    df,
-    segment_income="tpc_eci",
-    w="XTOT_m",
-    base_income="aftertax_income",
-    incidence=VAT_INCIDENCE,
-    name="vat",
-    **kwargs
-):
+    df: pd.DataFrame,
+    segment_income: Optional[str] = "tpc_eci",
+    w: Optional[str] = "XTOT_m",
+    base_income: Optional[str] = "aftertax_income",
+    incidence: Optional[pd.Series] = VAT_INCIDENCE,
+    name: Optional[str] = "vat",
+    **kwargs,
+) -> None:
     """Add value added tax based on incidence estimate from Tax Policy Center.
 
     :param df: DataFrame with columns for tpc_eci, XTOT_m, and aftertax_income.
@@ -111,11 +111,9 @@ def add_vat(
     :param w: Default value = "XTOT_m")
     :param base_income: Default value = "aftertax_income")
     :param incidence: Default value = VAT_INCIDENCE)
-    :param name: Default value = "vat")
-    :param **kwargs: Other arguments passed to add_custom_tax().
-    :returns: Nothing. Adds vat to df.
-        df is also sorted by tpc_eci.
-
+    :param name: Default value = "vat") :param **kwargs: Other arguments passed
+        to add_custom_tax().
+    :returns: Nothing. Adds vat to df. df is also sorted by tpc_eci.
     """
     add_custom_tax(
         df, segment_income, w, base_income, incidence, name, **kwargs
@@ -123,14 +121,14 @@ def add_vat(
 
 
 def add_carbon_tax(
-    df,
-    segment_income="tpc_eci",
-    w="XTOT_m",
-    base_income="aftertax_income",
-    incidence=CARBON_TAX_INCIDENCE,
-    name="carbon_tax",
-    **kwargs
-):
+    df: pd.DataFrame,
+    segment_income: Optional[str] = "tpc_eci",
+    w: Optional[str] = "XTOT_m",
+    base_income: Optional[str] = "aftertax_income",
+    incidence: Optional[pd.Series] = CARBON_TAX_INCIDENCE,
+    name: Optional[str] = "carbon_tax",
+    **kwargs,
+) -> None:
     """Add carbon tax based on incidence estimate from the US Treasury
     Department.
 
@@ -140,11 +138,9 @@ def add_carbon_tax(
     :param w: Default value = "XTOT_m")
     :param base_income: Default value = "aftertax_income")
     :param incidence: Default value = CARBON_TAX_INCIDENCE)
-    :param name: Default value = "carbon_tax")
-    :param **kwargs: Other arguments passed to add_custom_tax().
-    :returns: Nothing. Adds carbon_tax to df.
-        df is also sorted by tpc_eci.
-
+    :param name: Default value = "carbon_tax") :param **kwargs: Other arguments
+        passed to add_custom_tax().
+    :returns: Nothing. Adds carbon_tax to df. df is also sorted by tpc_eci.
     """
     add_custom_tax(
         df, segment_income, w, base_income, incidence, name, **kwargs
@@ -152,14 +148,14 @@ def add_carbon_tax(
 
 
 def add_ftt(
-    df,
-    segment_income="tpc_eci",
-    w="XTOT_m",
-    base_income="aftertax_income",
-    incidence=FTT_INCIDENCE,
-    name="ftt",
-    **kwargs
-):
+    df: pd.DataFrame,
+    segment_income: Optional[str] = "tpc_eci",
+    w: Optional[str] = "XTOT_m",
+    base_income: Optional[str] = "aftertax_income",
+    incidence: Optional[pd.Series] = FTT_INCIDENCE,
+    name: Optional[str] = "ftt",
+    **kwargs,
+) -> None:
     """Add financial transaction tax based on incidence estimate from Tax
     Policy Center.
 
@@ -169,11 +165,9 @@ def add_ftt(
     :param w: Default value = "XTOT_m")
     :param base_income: Default value = "aftertax_income")
     :param incidence: Default value = FTT_INCIDENCE)
-    :param name: Default value = "ftt")
-    :param **kwargs: Other arguments passed to add_custom_tax().
-    :returns: Nothing. Adds ftt to df.
-        df is also sorted by tpc_eci.
-
+    :param name: Default value = "ftt") :param **kwargs: Other arguments passed
+        to add_custom_tax().
+    :returns: Nothing. Adds ftt to df. df is also sorted by tpc_eci.
     """
     add_custom_tax(
         df, segment_income, w, base_income, incidence, name, **kwargs

microdf/income_measures.py

@@ -1,3 +1,5 @@
+import pandas as pd
+
 import microdf as mdf
 
 # See
@@ -5,7 +7,7 @@ import microdf as mdf
 # for a comparison of income measures used here.
 
 
-def cash_income(df):
+def cash_income(df: pd.DataFrame) -> pd.Series:
     """Calculates income after taxes and cash transfers.
 
     Defined as aftertax_income minus non-cash benefits.
@@ -22,7 +24,6 @@ def cash_income(df):
             * vet_ben
             * wic_ben
     :returns: A pandas Series with the cash income for each row in df.
-
     """
     return (
         df.aftertax_income
@@ -38,27 +39,25 @@ def cash_income(df):
     )
 
 
-def tpc_eci(df):
+def tpc_eci(df: pd.DataFrame) -> pd.Series:
     """Approximates Tax Policy Center's Expanded Cash Income measure.
 
     Subtracts WIC, housing assistance, veteran's benefits, Medicare, and
-    Medicaid from expanded_income. ECI adds income measures not modeled in
-    Tax-Calculator, so these are ignored and will create a discrepancy
-    compared to TPC's ECI.
+    Medicaid from expanded_income. ECI adds income measures not modeled in Tax-
+    Calculator, so these are ignored and will create a discrepancy compared to
+    TPC's ECI.
 
     :param df: DataFrame with columns from Tax-Calculator.
     :returns: pandas Series with TPC's ECI.
-
     """
     return df.expanded_income - df[mdf.ECI_REMOVE_COLS].sum(axis=1)
 
 
-def market_income(df):
-    """Approximates CBO's market income concept, which is income
-        before social insurance, means-tested transfers, and taxes.
+def market_income(df: pd.DataFrame) -> pd.Series:
+    """Approximates CBO's market income concept, which is income before social
+    insurance, means-tested transfers, and taxes.
 
     :param df: DataFrame with expanded_income and benefits.
     :returns: pandas Series of the same length as df.
-
     """
     return df.expanded_income - df[mdf.BENS].sum(axis=1)

microdf/inequality.py

@@ -1,9 +1,18 @@
+from typing import List, Optional, Union
+
 import numpy as np
+import pandas as pd
 
 import microdf as mdf
 
 
-def gini(df, col, w=None, negatives=None, groupby=None):
+def gini(
+    df: pd.DataFrame,
+    col: str,
+    w: Optional[str] = None,
+    negatives: Optional[str] = None,
+    groupby: Optional[Union[str, List[str]]] = None,
+) -> float:
     """Calculates Gini index.
 
     :param df: DataFrame.
@@ -18,10 +27,14 @@ def gini(df, col, w=None, negatives=None, groupby=None):
         Defaults to None, which leaves negative values as they are.
     :param groupby: Column, or list of columns, to group by.
     :returns: A float, the Gini index.
-
     """
 
-    def _gini(df, col, w=None, negatives=None):
+    def _gini(
+        df: pd.DataFrame,
+        col: str,
+        w: Optional[str] = None,
+        negatives: Optional[str] = None,
+    ) -> float:
         # Requires float numpy arrays (not pandas Series or lists) to work.
         x = np.array(df[col]).astype("float")
         if negatives == "zero":
@@ -50,7 +63,13 @@ def gini(df, col, w=None, negatives=None, groupby=None):
     return df.groupby(groupby).apply(lambda x: _gini(x, col, w, negatives))
 
 
-def top_x_pct_share(df, col, top_x_pct, w=None, groupby=None):
+def top_x_pct_share(
+    df: pd.DataFrame,
+    col: str,
+    top_x_pct: float,
+    w: Optional[str] = None,
+    groupby: Optional[Union[str, List[str]]] = None,
+) -> float:
     """Calculates top x% share.
 
     :param df: DataFrame.
@@ -59,10 +78,11 @@ def top_x_pct_share(df, col, top_x_pct, w=None, groupby=None):
     :param w: Column representing weight in df.
     :param groupby: Column, or list of columns, to group by.
     :returns: The share of w-weighted val held by the top x%.
-
     """
 
-    def _top_x_pct_share(df, col, top_x_pct, w=None):
+    def _top_x_pct_share(
+        df: pd.DataFrame, col: str, top_x_pct: float, w: Optional[str] = None
+    ) -> float:
         threshold = mdf.weighted_quantile(df, col, w, 1 - top_x_pct)
         top_x_pct_sum = mdf.weighted_sum(df[df[col] >= threshold], col, w)
         total_sum = mdf.weighted_sum(df, col, w)
@@ -75,7 +95,13 @@ def top_x_pct_share(df, col, top_x_pct, w=None, groupby=None):
     )
 
 
-def bottom_x_pct_share(df, col, bottom_x_pct, w=None, groupby=None):
+def bottom_x_pct_share(
+    df: pd.DataFrame,
+    col: str,
+    bottom_x_pct: float,
+    w: Optional[str] = None,
+    groupby: Optional[Union[str, List[str]]] = None,
+) -> float:
     """Calculates bottom x% share.
 
     :param df: DataFrame.
@@ -84,12 +110,16 @@ def bottom_x_pct_share(df, col, bottom_x_pct, w=None, groupby=None):
     :param w: Column representing weight in df.
     :param groupby: Column, or list of columns, to group by.
     :returns: The share of w-weighted val held by the bottom x%.
-
     """
     return 1 - top_x_pct_share(df, col, 1 - bottom_x_pct, w, groupby)
 
 
-def bottom_50_pct_share(df, col, w=None, groupby=None):
+def bottom_50_pct_share(
+    df: pd.DataFrame,
+    col: str,
+    w: Optional[str] = None,
+    groupby: Optional[Union[str, List[str]]] = None,
+) -> float:
     """Calculates bottom 50% share.
 
     :param df: DataFrame.
@@ -97,12 +127,16 @@ def bottom_50_pct_share(df, col, w=None, groupby=None):
     :param w: Column representing weight in df.
     :param groupby: Column, or list of columns, to group by.
     :returns: The share of w-weighted val held by the bottom 50%.
-
     """
     return bottom_x_pct_share(df, col, 0.5, w, groupby)
 
 
-def top_50_pct_share(df, col, w=None, groupby=None):
+def top_50_pct_share(
+    df: pd.DataFrame,
+    col: str,
+    w: Optional[str] = None,
+    groupby: Optional[Union[str, List[str]]] = None,
+) -> float:
     """Calculates top 50% share.
 
     :param df: DataFrame.
@@ -110,12 +144,16 @@ def top_50_pct_share(df, col, w=None, groupby=None):
     :param w: Column representing weight in df.
     :param groupby: Column, or list of columns, to group by.
     :returns: The share of w-weighted val held by the top 50%.
-
     """
     return top_x_pct_share(df, col, 0.5, w, groupby)
 
 
-def top_10_pct_share(df, col, w=None, groupby=None):
+def top_10_pct_share(
+    df: pd.DataFrame,
+    col: str,
+    w: Optional[str] = None,
+    groupby: Optional[Union[str, List[str]]] = None,
+) -> float:
     """Calculates top 10% share.
 
     :param df: DataFrame.
@@ -123,12 +161,16 @@ def top_10_pct_share(df, col, w=None, groupby=None):
     :param w: Column representing weight in df.
     :param groupby: Column, or list of columns, to group by.
     :returns: The share of w-weighted val held by the top 10%.
-
     """
     return top_x_pct_share(df, col, 0.1, w, groupby)
 
 
-def top_1_pct_share(df, col, w=None, groupby=None):
+def top_1_pct_share(
+    df: pd.DataFrame,
+    col: str,
+    w: Optional[str] = None,
+    groupby: Optional[Union[str, List[str]]] = None,
+) -> float:
     """Calculates top 1% share.
 
     :param df: DataFrame.
@@ -136,12 +178,16 @@ def top_1_pct_share(df, col, w=None, groupby=None):
     :param w: Column representing weight in df.
     :param groupby: Column, or list of columns, to group by.
     :returns: The share of w-weighted val held by the top 1%.
-
     """
     return top_x_pct_share(df, col, 0.01, w, groupby)
 
 
-def top_0_1_pct_share(df, col, w=None, groupby=None):
+def top_0_1_pct_share(
+    df: pd.DataFrame,
+    col: str,
+    w: Optional[str] = None,
+    groupby: Optional[Union[str, List[str]]] = None,
+) -> float:
     """Calculates top 0.1% share.
 
     :param df: DataFrame.
@@ -149,21 +195,24 @@ def top_0_1_pct_share(df, col, w=None, groupby=None):
     :param w: Column representing weight in df.
     :param groupby: Column, or list of columns, to group by.
     :returns: The share of w-weighted val held by the top 0.1%.
-
     """
     return top_x_pct_share(df, col, 0.001, w, groupby)
 
 
-def t10_b50(df, col, w=None, groupby=None):
+def t10_b50(
+    df: pd.DataFrame,
+    col: str,
+    w: Optional[str] = None,
+    groupby: Optional[Union[str, List[str]]] = None,
+) -> float:
     """Calculates ratio between the top 10% and bottom 50% shares.
 
     :param df: DataFrame.
     :param col: Name of column in df representing value.
     :param w: Column representing weight in df.
     :param groupby: Column, or list of columns, to group by.
-    :returns: The share of w-weighted val held by the top 10% divided by
-        the share of w-weighted val held by the bottom 50%.
-
+    :returns: The share of w-weighted val held by the top 10% divided by the
+        share of w-weighted val held by the bottom 50%.
     """
     t10 = top_10_pct_share(df, col, w, groupby)
     b50 = bottom_50_pct_share(df, col, w, groupby)

microdf/io.py

@@ -1,14 +1,14 @@
 import io
 import zipfile
-import requests
+
 import pandas as pd
+import requests
 
 HEADER = {
-    "User-Agent":
-    "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_5) " +
-    "AppleWebKit/537.36 (KHTML, like Gecko) " +
-    "Chrome/50.0.2661.102 Safari/537.36"
-    }
+    "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_5) "
+    + "AppleWebKit/537.36 (KHTML, like Gecko) "
+    + "Chrome/50.0.2661.102 Safari/537.36"
+}
 
 
 def read_stata_zip(url: str, **kwargs) -> pd.DataFrame:
@@ -19,11 +19,9 @@ def read_stata_zip(url: str, **kwargs) -> pd.DataFrame:
     Pending native support in
     https://github.com/pandas-dev/pandas/issues/26599.
 
-    :param url: URL string of .zip file containing a single
-            .dta file.
-    :param **kwargs: Arguments passed to pandas.read_stata().
+    :param url: URL string of .zip file containing a single .dta file. :param
+        **kwargs: Arguments passed to pandas.read_stata().
     :returns: DataFrame.
-
     """
     r = requests.get(url, headers=HEADER)
     data = io.BytesIO(r.content)