Coverage for src/crimepy/nibrs/__init__.py: 100%

1"""Tools for the FBI's National Incident-Based Reporting System (NIBRS). 

2 

3NIBRS records each crime incident that a participating law enforcement 

4agency reports: its offenses, the property involved, its victims, offenders, 

5and arrestees, and arrests for less serious (Group "B") offenses. The FBI 

6publishes a master file of every year's reports from 1991 on, which `crimepy` 

7downloads, parses, and makes into flat tables, each loaded as an 

8`amos.Dataset` (whose `data` is a `pandas` data frame): 

9 

10* `agencies`: one row for each agency (its batch header): location, 

11 population, and months reported. 

12* `administrative`: one row for each incident: date, hour, numbers of 

13 segments, and exceptional clearance. 

14* `offenses`: one row for each offense of an incident: offense, location, 

15 weapons, and bias motivations. 

16* `properties`: one row for each property loss of an incident: type of loss, 

17 description, value, and drugs. 

18* `victims`: one row for each victim: offenses, age, sex, race, injuries, 

19 and relationships to offenders. 

20* `offenders`: one row for each offender: age, sex, race, and ethnicity. 

21* `arrestees`: one row for each arrestee of an incident: date and type of 

22 arrest, offense, and person. 

23* `group_b_arrests`: one row for each arrestee of a Group "B" offense. 

24* `window_clearances`, `window_properties`, and `window_arrestees`: one row 

25 for each partial report of an incident that began before its agency 

26 reported to NIBRS. 

27 

28The tables of an incident share "data_year", "ori", and "incident_number", 

29and `crimepy.nibrs.tables` joins them into tables for analysis (such as one 

30row for each victim with the incident's offenses and agency). 

31 

32Contents: 

33 available_years: the years of master files that the FBI has. 

34 cde: downloads master files from the FBI's Crime Data Explorer. 

35 codes: the labels of the codes in the master files. 

36 convert: converts master files to parquet files. 

37 decode: replaces codes with their labels. 

38 download: downloads master files. 

39 layouts: where each field is in the records of the master files. 

40 load: loads a table of years as an `amos.Dataset` (downloading and 

41 converting them if needed). 

42 load_frame: loads a table of years as a `pandas` data frame. 

43 load_tables: loads several tables of years as `amos` datasets. 

44 munge: makes tables ready for analysis. 

45 read: reads tables straight from a master file. 

46 reader: reads and parses master files. 

47 store: converts master files to parquet files and loads them. 

48 tables: joins the tables of incidents for analysis. 

49 techniques: `amos` techniques for NIBRS data. 

50 

51""" 

52 

53from __future__ import annotations 

54 

55__all__: list[str] = [ 

56 'available_years', 

57 'cde', 

58 'codes', 

59 'convert', 

60 'decode', 

61 'download', 

62 'layouts', 

63 'load', 

64 'load_frame', 

65 'load_tables', 

66 'munge', 

67 'read', 

68 'reader', 

69 'store', 

70 'tables', 

71 'techniques'] 

72 

73from . import cde, codes, layouts, munge, reader, store, tables, techniques 

74from .cde import available_years, download 

75from .munge import decode 

76from .reader import read 

77from .store import convert, load, load_frame, load_tables