microdf-python 0.4.4__py3-none-any.whl → 0.4.6__py3-none-any.whl

microdf/__init__.py

@@ -1,5 +1,5 @@
 from .agg import agg, combine_base_reform, pctchg_base_reform
-from .chart_utils import dollar_format, currency_format
+from .chart_utils import currency_format, dollar_format
 from .charts import quantile_pct_chg_plot
 from .concat import concat
 from .constants import (
@@ -25,6 +25,7 @@ from .custom_taxes import (
     add_ftt,
     add_vat,
 )
+from .generic import MicroDataFrame, MicroSeries
 from .income_measures import cash_income, market_income, tpc_eci
 from .inequality import (
     bottom_50_pct_share,
@@ -32,19 +33,19 @@ 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 .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
@@ -72,7 +73,6 @@ from .weighted import (
     weighted_quantile,
     weighted_sum,
 )
-from .generic import MicroDataFrame, MicroSeries
 
 name = "microdf"
 __version__ = "0.1.0"

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/chart_utils.py

@@ -1,28 +1,33 @@
-def dollar_format(suffix=""):
+from typing import Optional
+
+from matplotlib.ticker import FuncFormatter
+
+
+def dollar_format(suffix: Optional[str] = "") -> "FuncFormatter":
     """Dollar formatter for matplotlib.
 
     :param suffix: Suffix to append, e.g. 'B'. Defaults to ''.
     :returns: FuncFormatter.
-
     """
     return currency_format(currency="USD", suffix=suffix)
 
 
-def currency_format(currency="USD", suffix=""):
+def currency_format(
+    currency: Optional[str] = "USD", suffix: Optional[str] = ""
+) -> "FuncFormatter":
     """Currency formatter for matplotlib.
 
     :param currency: Name of the currency, e.g. 'USD', 'GBP'.
     :param suffix: Suffix to append, e.g. 'B'. Defaults to ''.
     :returns: FuncFormatter.
-
     """
     try:
         import matplotlib as mpl
     except ImportError:
         raise ImportError(
-            "The function you've called requires extra dependencies. " +
-            "Please install microdf with the 'charts' extra by running " +
-            "'pip install microdf[charts]'"
+            "The function you've called requires extra dependencies. "
+            + "Please install microdf with the 'charts' extra by running "
+            + "'pip install microdf[charts]'"
         )
 
     prefix = {"USD": "$", "GBP": "£"}[currency]

microdf/charts.py

@@ -1,9 +1,18 @@
 import numpy as np
+import pandas as pd
 
 import microdf as mdf
 
 
-def quantile_pct_chg_plot(df1, df2, col1, col2, w1=None, w2=None, q=None):
+def quantile_pct_chg_plot(
+    df1: pd.DataFrame,
+    df2: pd.DataFrame,
+    col1: str,
+    col2: str,
+    w1: str = None,
+    w2: str = None,
+    q: np.ndarray = None,
+):
     """Create stem plot with percent change in decile boundaries.
 
     :param df1: DataFrame with first set of values.
@@ -14,17 +23,16 @@ def quantile_pct_chg_plot(df1, df2, col1, col2, w1=None, w2=None, q=None):
     :param w2: Name of weight column in df2.
     :param q: Quantiles. Defaults to decile boundaries.
     :returns: Axis.
-
     """
     try:
-        import seaborn as sns
         import matplotlib as mpl
         import matplotlib.pyplot as plt
+        import seaborn as sns
     except ImportError:
         raise ImportError(
-            "The function you've called requires extra dependencies. " +
-            "Please install microdf with the 'charts' extra by running " +
-            "'pip install microdf[charts]'"
+            "The function you've called requires extra dependencies. "
+            + "Please install microdf with the 'charts' extra by running "
+            + "'pip install microdf[charts]'"
         )
 
     if q is None:
@@ -41,9 +49,7 @@ def quantile_pct_chg_plot(df1, df2, col1, col2, w1=None, w2=None, q=None):
     )
     # Plot.
     fig, ax = plt.subplots()
-    markerline, stemlines, baseline = ax.stem(
-        df.index_newline, df.pct_chg
-    )
+    markerline, stemlines, baseline = ax.stem(df.index_newline, df.pct_chg)
     plt.setp(baseline, color="gray", linewidth=0)
     ax.yaxis.set_major_locator(mpl.ticker.MaxNLocator(integer=True))
     ax.yaxis.set_major_formatter(mpl.ticker.PercentFormatter(xmax=100))

microdf/concat.py

@@ -1,12 +1,15 @@
-import pandas as pd
 import inspect
+
+import pandas as pd
+
 import microdf as mdf
+from microdf.generic 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