scfpublic 1.0.1__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
scfpublic/__init__.py ADDED
@@ -0,0 +1,38 @@
1
+ """
2
+ scfpublic
3
+ =================
4
+
5
+ A package for loading the Survey of Consumer Finances and properly applying multiple imputation and sampling variances.
6
+
7
+ Author: Payton Crawford
8
+ """
9
+
10
+ from .scfpublic import download_year, download_years, download_main_extr_years, _get_url, _get_dta_path, _match_vars, _optimize_dtypes, minYear, maxYear, YEARS
11
+ from .scfcombo import scfcombo_result, prepare_scf_data, scf_estimate, scf_mean, scf_quantile, scf_regression, scf_total
12
+ from .cpi import read_excel_from_url, cpi_adjust
13
+ from .util import mconv, aconv
14
+
15
+ __version__ = "0.1.0"
16
+ __all__ = [
17
+ "download_year",
18
+ "download_years",
19
+ "download_main_extr_years",
20
+ "_get_url",
21
+ "_get_dta_path",
22
+ "_match_vars",
23
+ "_optimize_dtypes",
24
+ "minYear",
25
+ "maxYear",
26
+ "YEARS",
27
+ "scfcombo_result",
28
+ "prepare_scf_data",
29
+ "scf_estimate",
30
+ "scf_mean",
31
+ "scf_quantile",
32
+ "scf_regression",
33
+ "scf_total",
34
+ "read_excel_from_url",
35
+ "cpi_adjust",
36
+ "mconv",
37
+ "aconv",
38
+ ]
scfpublic/cpi.py ADDED
@@ -0,0 +1,89 @@
1
+ '''
2
+ Stores cpi adjustment formulas using data from https://www.bls.gov/cpi/research-series/r-cpi-u-rs-home.htm
3
+
4
+ Author: Payton Crawford
5
+ '''
6
+ import pandas as pd
7
+ import requests
8
+ from io import BytesIO
9
+
10
+ # URL for BLS data
11
+ URL = 'https://www.bls.gov/cpi/research-series/r-cpi-u-rs-allitems.xlsx'
12
+
13
+ # Current years of dataset
14
+ minYear = 1989
15
+ maxYear = 2025
16
+ allYears = list(range(minYear,maxYear+1,3))
17
+
18
+ def read_excel_from_url(url: str, sheet_name: int = 0, **kwargs):
19
+ """
20
+ Download Excel file from BLS URL and read into DataFrame.
21
+
22
+ Args:
23
+ url (str): URL of excel file
24
+ sheet_name (int): Sheet name or index (default: 0 = first sheet)
25
+ **kwargs: Additional arguments for pd.read_excel()
26
+
27
+ Returns:
28
+ pd.DataFrame: Pandas dataframe containing Excel file from URL
29
+
30
+ Raises:
31
+ IOError: Failure to download or process BLS file
32
+ """
33
+ try:
34
+ response = requests.get(url, timeout=30)
35
+ response.raise_for_status()
36
+
37
+ # Read Excel from memory
38
+ excel_buffer = BytesIO(response.content)
39
+ df = pd.read_excel(excel_buffer, sheet_name=sheet_name, **kwargs)
40
+
41
+ return df
42
+
43
+ # Failure to download file
44
+ except requests.exceptions.RequestException as e:
45
+ raise IOError(f"Failed to download file: {e}")
46
+ # Error reading in file
47
+ except Exception as e:
48
+ raise IOError(f"Error processing BLS file: {e}")
49
+
50
+ def cpi_adjust(df: pd.DataFrame, base_year: int = maxYear):
51
+ '''
52
+ Appends cpiadj and cpilag variables based on 'year' variable in dataset.
53
+
54
+ Args:
55
+ df (pd.DataFrame): Pandas dataframe to have CPI variables added to
56
+ base_year (int): Year to use as base for for CPI base value (default: 2022)
57
+
58
+ Returns:
59
+ pd.DataFrame: Original dataframe with new cpiadj and cpilag variables merged on year
60
+
61
+ Raises:
62
+ ValueError: Provided invalid year, DataFrame lacks year variable, or DataFrame lacks correct years
63
+ '''
64
+ # Grab years from dataframe
65
+ if 'year' not in df.columns:
66
+ raise ValueError('DataFrame must contain a \'year\' column')
67
+ df_years = df['year'].unique()
68
+
69
+ # Validate base year is in range
70
+ if base_year < minYear or base_year > maxYear:
71
+ raise ValueError(f"base_year must be between {minYear} and {maxYear}, got {base_year}")
72
+
73
+ # Only read in valid years (triennial survey)
74
+ years_in_range = [y for y in df_years if y in allYears]
75
+ if len(years_in_range) == 0:
76
+ raise ValueError(f"No valid years in range {minYear}-{maxYear}")
77
+
78
+ cpi_df = read_excel_from_url(URL, skiprows=5, header=0)
79
+
80
+ cpibase = cpi_df.loc[cpi_df['YEAR'] == base_year, 'SEP'].values[0]
81
+ df['cpiadj'] = None
82
+ df['cpilag'] = None
83
+ for year in years_in_range:
84
+ # CPI Adjustments based on release of survey
85
+ df.loc[df['year']==year, 'cpiadj'] = cpibase / cpi_df.loc[cpi_df['YEAR'] == year, 'SEP'].values[0]
86
+ # CPI Lags from previous year to year of release
87
+ df.loc[df['year']==year, 'cpilag'] = cpi_df.loc[cpi_df['YEAR'] == year, 'AVG'].values[0] / cpi_df.loc[cpi_df['YEAR'] == (year-1), 'AVG'].values[0]
88
+
89
+ return df
@@ -0,0 +1,21 @@
1
+ """
2
+ scfpublic.scfcombo
3
+ =================
4
+
5
+ A package for properly correcting for multiple imputation and sampling variances.
6
+
7
+ Author: Payton Crawford
8
+ """
9
+
10
+ from .scfcombo import scfcombo_result, prepare_scf_data, scf_estimate
11
+ from .stats import scf_mean, scf_quantile, scf_regression, scf_total
12
+
13
+ __all__ = [
14
+ "scfcombo_result",
15
+ "prepare_scf_data",
16
+ "scf_estimate",
17
+ "scf_mean",
18
+ "scf_quantile",
19
+ "scf_regression",
20
+ "scf_total",
21
+ ]