genpeds 1.0__tar.gz

genpeds-1.0/LICENSE.md

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright (c) 2025 Ravan Hawrami
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

genpeds-1.0/PKG-INFO

@@ -0,0 +1,172 @@
+Metadata-Version: 2.4
+Name: genpeds
+Version: 1.0
+Summary: Work with NCES IPEDS data: from admissions to graduation
+Author-email: Ravan Hawrami <ravanhawrami@gmail.com>
+License-Expression: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.13.3
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+Requires-Dist: pandas
+Requires-Dist: numpy
+Requires-Dist: openpyxl
+Requires-Dist: xlrd
+Requires-Dist: requests
+Requires-Dist: bs4
+Requires-Dist: us
+Dynamic: license-file
+
+# genpeds
+A Python package for working with NCES IPEDS data, particularly for studying trends by gender.
+
+The Integrated Postsecondary Education Data System ([IPEDS](https://nces.ed.gov/ipeds/about-ipeds)), ran by the National Center for Education Statistics ([NCES](https://nces.ed.gov/)), is a collection of surveys annually conducted on a range of subjects, from finances and admissions to enrollment and graduation. All postsecondary institutions that participate in federal student aid financial aid programs are required to participate in these surveys.
+
+Per [IPEDS](https://nces.ed.gov/ipeds/about-ipeds):
+> "IPEDS provides basic data needed to describe — and analyze trends in — postsecondary education in the United States, in terms of the numbers of students enrolled, staff employed, dollars expended, and degrees earned. Congress, federal agencies, state governments, education providers, professional associations, private businesses, media, students and parents, and others rely on IPEDS data for this basic information on postsecondary institutions." 
+
+`genpeds` provides a Python API for requesting, and cleaning IPEDS data for a host of subject, particularly for studying college trends by gender.
+
+## Usage
+
+### Install
+```bash
+pip install genpeds
+```
+
+### API
+
+#### Downloading IPEDS Data
+To just request IPEDS data, you can use the `scrape_ipeds_data()` standalone function:
+
+```python
+from genpeds import scrape_ipeds_data
+
+# ex. download Characteristics data for years 2013-2023:
+scrape_ipeds_data(subject='characteristics', 
+                  year_range=(2013,2023),
+                  see_progress=True)
+# if see_progress==True, download confirmation statements will be printed
+
+# for year_range param, you can pass (inclusive) tuple range, list of years, or single year
+# ex. download enrollment data for 1980/1990 and 2015/2016:
+scrape_ipeds_data(subject='enrollment', 
+                  year_range=[1980,1990,2015,2016],
+                  see_progress=True)
+# download completion data for 1990
+scrape_ipeds_data(subject='completion', 
+                  year_range=1990,
+                  see_progress=True)
+```
+
+#### Subject Classes
+If you'd also like to clean data in order to study trends, you can use the various subject classes; you can also just download data with these classes, so it's recommended to primarily use these classes.
+
+```python
+from genpeds import Enrollment
+
+enroll_20s = Enrollment(year_range=(2020,2023)) # enrollment data for the 20s
+
+enroll_20s.get_description() # returns description of subject, enrollment in this case
+
+enroll_20s.get_available_vars() # returns dict of var names and descriptions
+```
+
+The key methods we'll be using 99% of the time are:
+
+- `.scrape()`, which downloads subject data
+- `.clean()`, which cleans subject data
+- `.run()`, which downloads and cleans subject data (along with some further options)
+
+```python
+from genpeds import Graduation
+
+grad_aughts = Graduation(year_range=(2000,2009)) 
+
+grad_aughts.scrape(see_progress=False) # downloads grad data for 2000-2009
+
+grad_df = grad_aughts.clean(degree_level='bach',
+                            rm_disk=True)
+# .clean() returns a Pandas DataFrame 
+# degree_level specifies the level of graduation data
+# rm_disk determines if previously downloaded data should be removed from disk after data is cleaned and returned in a DataFrame
+
+grad_df = grad_aughts.run(degree_level='assc',
+                          see_progress=False,
+                          merge_with_char=True,
+                          rm_disk=False)
+# .run() downloads subject data, then cleans it
+# returns Pandas DataFrame
+# merge_with_char, if True, downloads Characteristics data (e.g., school names, addresses) and merges with subject data
+
+# to look up variable descriptions, you can either use:
+# .get_available_vars() -> dict
+# .lookup_var() -> str
+grad_aughts.lookup_var('gradrate_wtmen')
+# returns: 'Graduation rate for non-Hispanic White men (within 150 percent of normal time taken to graduate).'
+```
+
+### Subjects
+IPEDS [covers](https://nces.ed.gov/ipeds/about-ipeds) eight main subjects:
+1. Institutional Characteristics
+2. Admissions
+3. Enrollment
+4. Degrees and Certificates Conferred
+5. Student Persistence and Success
+6. Institutional Prices
+7. Student Financial Aid
+8. institutional Resources including Human, resources, Finance, and Academic Libraries
+
+`genpeds` currently supports the first five subjects:
+
+- **Characteristics** (e.g., school name, address, longitude/latitude, etc.) (available 1984-2023)
+```python
+from genpeds import scrape_ipeds_data, Characteristics
+
+scrape_ipeds_data(subject='characteristics',
+                  year_range=(1984,2023))
+
+chardat = Characteristics(year_range=(1984,2023))
+```
+- **Admissions** (e.g., SAT/ACT scores, admit rates by gender, etc.) (available 2001-2023)
+```python
+from genpeds import scrape_ipeds_data, Admissions
+
+scrape_ipeds_data(subject='admissions',
+                  year_range=(2001,2023))
+
+admdat = Admissions(year_range=(2001,2023))
+```
+- **Enrollment** (e.g., enrollment by race/gender/level, etc.) (available 1984-2023)
+```python
+from genpeds import scrape_ipeds_data, Enrollment
+
+scrape_ipeds_data(subject='enrollment',
+                  year_range=(1984,2023))
+
+enrolldat = Enrollment(year_range=(1984,2023))
+```
+- **Completion** (e.g., degree completion by race/gender/subject/level, etc.) (available 1984-2023)
+```python
+from genpeds import scrape_ipeds_data, Completion
+
+scrape_ipeds_data(subject='completion',
+                  year_range=(1984,2023))
+
+completedat = Completion(year_range=(1984,2023))
+```
+- **Graduation** (e.g., graduation rate by race/gender/level, etc.) (available 2000-2023)
+```python
+from genpeds import scrape_ipeds_data, Graduation
+
+scrape_ipeds_data(subject='graduation',
+                  year_range=(2000,2023))
+
+graddat = Graduation(year_range=(2000,2023))
+
+grad_df = graddat.run(degree_level='bach',
+                      merge_with_char=True)
+```
+
+In the future, the remaining subjects will likely be added to `genpeds`. But just with the already provided subjects, you can study school-level trends for their male and female students, from admissions to completion.

genpeds-1.0/README.md

@@ -0,0 +1,152 @@
+# genpeds
+A Python package for working with NCES IPEDS data, particularly for studying trends by gender.
+
+The Integrated Postsecondary Education Data System ([IPEDS](https://nces.ed.gov/ipeds/about-ipeds)), ran by the National Center for Education Statistics ([NCES](https://nces.ed.gov/)), is a collection of surveys annually conducted on a range of subjects, from finances and admissions to enrollment and graduation. All postsecondary institutions that participate in federal student aid financial aid programs are required to participate in these surveys.
+
+Per [IPEDS](https://nces.ed.gov/ipeds/about-ipeds):
+> "IPEDS provides basic data needed to describe — and analyze trends in — postsecondary education in the United States, in terms of the numbers of students enrolled, staff employed, dollars expended, and degrees earned. Congress, federal agencies, state governments, education providers, professional associations, private businesses, media, students and parents, and others rely on IPEDS data for this basic information on postsecondary institutions." 
+
+`genpeds` provides a Python API for requesting, and cleaning IPEDS data for a host of subject, particularly for studying college trends by gender.
+
+## Usage
+
+### Install
+```bash
+pip install genpeds
+```
+
+### API
+
+#### Downloading IPEDS Data
+To just request IPEDS data, you can use the `scrape_ipeds_data()` standalone function:
+
+```python
+from genpeds import scrape_ipeds_data
+
+# ex. download Characteristics data for years 2013-2023:
+scrape_ipeds_data(subject='characteristics', 
+                  year_range=(2013,2023),
+                  see_progress=True)
+# if see_progress==True, download confirmation statements will be printed
+
+# for year_range param, you can pass (inclusive) tuple range, list of years, or single year
+# ex. download enrollment data for 1980/1990 and 2015/2016:
+scrape_ipeds_data(subject='enrollment', 
+                  year_range=[1980,1990,2015,2016],
+                  see_progress=True)
+# download completion data for 1990
+scrape_ipeds_data(subject='completion', 
+                  year_range=1990,
+                  see_progress=True)
+```
+
+#### Subject Classes
+If you'd also like to clean data in order to study trends, you can use the various subject classes; you can also just download data with these classes, so it's recommended to primarily use these classes.
+
+```python
+from genpeds import Enrollment
+
+enroll_20s = Enrollment(year_range=(2020,2023)) # enrollment data for the 20s
+
+enroll_20s.get_description() # returns description of subject, enrollment in this case
+
+enroll_20s.get_available_vars() # returns dict of var names and descriptions
+```
+
+The key methods we'll be using 99% of the time are:
+
+- `.scrape()`, which downloads subject data
+- `.clean()`, which cleans subject data
+- `.run()`, which downloads and cleans subject data (along with some further options)
+
+```python
+from genpeds import Graduation
+
+grad_aughts = Graduation(year_range=(2000,2009)) 
+
+grad_aughts.scrape(see_progress=False) # downloads grad data for 2000-2009
+
+grad_df = grad_aughts.clean(degree_level='bach',
+                            rm_disk=True)
+# .clean() returns a Pandas DataFrame 
+# degree_level specifies the level of graduation data
+# rm_disk determines if previously downloaded data should be removed from disk after data is cleaned and returned in a DataFrame
+
+grad_df = grad_aughts.run(degree_level='assc',
+                          see_progress=False,
+                          merge_with_char=True,
+                          rm_disk=False)
+# .run() downloads subject data, then cleans it
+# returns Pandas DataFrame
+# merge_with_char, if True, downloads Characteristics data (e.g., school names, addresses) and merges with subject data
+
+# to look up variable descriptions, you can either use:
+# .get_available_vars() -> dict
+# .lookup_var() -> str
+grad_aughts.lookup_var('gradrate_wtmen')
+# returns: 'Graduation rate for non-Hispanic White men (within 150 percent of normal time taken to graduate).'
+```
+
+### Subjects
+IPEDS [covers](https://nces.ed.gov/ipeds/about-ipeds) eight main subjects:
+1. Institutional Characteristics
+2. Admissions
+3. Enrollment
+4. Degrees and Certificates Conferred
+5. Student Persistence and Success
+6. Institutional Prices
+7. Student Financial Aid
+8. institutional Resources including Human, resources, Finance, and Academic Libraries
+
+`genpeds` currently supports the first five subjects:
+
+- **Characteristics** (e.g., school name, address, longitude/latitude, etc.) (available 1984-2023)
+```python
+from genpeds import scrape_ipeds_data, Characteristics
+
+scrape_ipeds_data(subject='characteristics',
+                  year_range=(1984,2023))
+
+chardat = Characteristics(year_range=(1984,2023))
+```
+- **Admissions** (e.g., SAT/ACT scores, admit rates by gender, etc.) (available 2001-2023)
+```python
+from genpeds import scrape_ipeds_data, Admissions
+
+scrape_ipeds_data(subject='admissions',
+                  year_range=(2001,2023))
+
+admdat = Admissions(year_range=(2001,2023))
+```
+- **Enrollment** (e.g., enrollment by race/gender/level, etc.) (available 1984-2023)
+```python
+from genpeds import scrape_ipeds_data, Enrollment
+
+scrape_ipeds_data(subject='enrollment',
+                  year_range=(1984,2023))
+
+enrolldat = Enrollment(year_range=(1984,2023))
+```
+- **Completion** (e.g., degree completion by race/gender/subject/level, etc.) (available 1984-2023)
+```python
+from genpeds import scrape_ipeds_data, Completion
+
+scrape_ipeds_data(subject='completion',
+                  year_range=(1984,2023))
+
+completedat = Completion(year_range=(1984,2023))
+```
+- **Graduation** (e.g., graduation rate by race/gender/level, etc.) (available 2000-2023)
+```python
+from genpeds import scrape_ipeds_data, Graduation
+
+scrape_ipeds_data(subject='graduation',
+                  year_range=(2000,2023))
+
+graddat = Graduation(year_range=(2000,2023))
+
+grad_df = graddat.run(degree_level='bach',
+                      merge_with_char=True)
+```
+
+In the future, the remaining subjects will likely be added to `genpeds`. But just with the already provided subjects, you can study school-level trends for their male and female students, from admissions to completion.

genpeds-1.0/pyproject.toml

@@ -0,0 +1,24 @@
+[build-system]
+requires = ["setuptools >= 77.0.3"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "genpeds"
+description = "Work with NCES IPEDS data: from admissions to graduation"
+requires-python = ">=3.13.3"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+]
+version = "1.0"
+authors = [{"name" = "Ravan Hawrami", "email" = "ravanhawrami@gmail.com"}]
+readme = {"file" = "README.md", content-type = "text/markdown"}
+dependencies = ["pandas", "numpy", "openpyxl", "xlrd", "requests", "bs4", "us"]
+license = "MIT"
+license-files = ["LICENSE.md"]
+
+[project-urls]
+Homepage = "https://github.com/rhawrami/genpeds"
+
+[project-scripts]
+genpeds-cli = "genpeds.cli:main"

genpeds-1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

genpeds-1.0/src/genpeds/__init__.py

@@ -0,0 +1,16 @@
+'''Work with gendered NCES IPEDS data: from admissions to graduation'''
+
+__version__ = '1.0'
+
+from genpeds.core import Characteristics, Admissions, Enrollment, Completion, Cip, Graduation
+from genpeds.downloader import scrape_ipeds_data
+
+__all__ = [
+    'Characteristics',
+    'Admissions',
+    'Enrollment', 
+    'Completion',
+    'Cip',
+    'Graduation',
+    'scrape_ipeds_data'
+]