call_report.fca.FCAInstitution#

class call_report.fca.FCAInstitution(*, uninum: int, system: int, district: int, association: int, periods: tuple[PeriodRange, ...], short_name_history: tuple[InstitutionAttributeVersion, ...], mail_addr_history: tuple[InstitutionAttributeVersion, ...], street_addr_history: tuple[InstitutionAttributeVersion, ...], city_history: tuple[InstitutionAttributeVersion, ...], state_history: tuple[InstitutionAttributeVersion, ...], zip_history: tuple[InstitutionAttributeVersion, ...])[source]#

Bases: object

The name and address history of one UNINUM in FCA’s institution roster.

The short name and each address field are held as a tuple of InstitutionAttributeVersion, oldest first. A new entry starts when the value changes, or when the UNINUM reappears after missing some quarters. A value can come back later, for example an address that changes and then changes back.

The SYSTEM, DIST, and ASSOC values must be the same in every quarter for a UNINUM.

Build one from roster rows with from_roster_rows. Building one directly checks that every history covers exactly the quarters in periods.

Attributes:

uninumint: The UNINUM.
systemint: The system code (SYSTEM).
districtint: The district code (DIST).
associationint: The association code (ASSOC).
periodstuple[PeriodRange, …]: The quarters in which this UNINUM appears in the roster, as runs of consecutive quarters, oldest first. More than one run means the UNINUM is missing from the roster for some quarters in between.
short_name_historytuple[InstitutionAttributeVersion, …]: The versions of the short name (SHORTNAME).
mail_addr_historytuple[InstitutionAttributeVersion, …]: The versions of the mailing address (MAIL_ADDR).
street_addr_historytuple[InstitutionAttributeVersion, …]: The versions of the street address (STREET_ADDR).
city_historytuple[InstitutionAttributeVersion, …]: The versions of the city (CITY).
state_historytuple[InstitutionAttributeVersion, …]: The versions of the state (STATE).
zip_historytuple[InstitutionAttributeVersion, …]: The versions of the ZIP code (ZIP).

Raises:

InstitutionError: If periods is empty, or its runs are out of order, overlap, or touch. Also if any history does not cover exactly the quarters in periods, in order, or has two back-to-back entries with the same value.

See also

call_report.fca.institutions.read_institutions: Read one quarter’s roster.

Examples

>>> from call_report.fca import FCAInstitution
>>> row = {
...     "UNINUM": 722825,
...     "SYSTEM": 7,
...     "DIST": 22,
...     "ASSOC": 825,
...     "SHORTNAME": "Mid-America ACA",
...     "MAIL_ADDR": "P.O. Box 34390",
...     "STREET_ADDR": "1601 UPS Drive",
...     "CITY": "Louisville",
...     "STATE": "KY",
...     "ZIP": "40223-4390",
... }
>>> renamed = {**row, "SHORTNAME": "Farm Credit Mid-America ACA"}
>>> institution = FCAInstitution.from_roster_rows(
...     rows=[("2011-09-30", row), ("2011-12-31", renamed)]
... )
>>> [version.value for version in institution.short_name_history]
['Mid-America ACA', 'Farm Credit Mid-America ACA']

classmethod from_roster_rows(*, rows: Iterable[tuple[str | date | ReportingPeriod, Mapping[str, Any]]]) → FCAInstitution[source]#

Build a UNINUM’s history from its roster rows, one per quarter.

Each item pairs a quarter with that quarter’s roster row for this UNINUM. The rows can arrive in any order. Values are kept exactly as FCA published them, except that a missing value (None or a float NaN, as pandas spells it) becomes None.

A row carrying YEAR and MONTH values, as FCA’s own roster does, must name the quarter it is paired with.

Parameters:

rowsIterable[tuple[str | datetime.date | ReportingPeriod, Mapping[str, Any]]]: (period, row) pairs. Each row maps roster column names to values and must include UNINUM, SYSTEM, DIST, ASSOC, SHORTNAME, MAIL_ADDR, STREET_ADDR, CITY, STATE, and ZIP. Other columns are ignored.

Returns:

FCAInstitution: The UNINUM’s history across every quarter in rows.

Raises:

InstitutionError: If rows is empty, names the same quarter twice, or has a row missing a required column or a UNINUM, SYSTEM, DIST, or ASSOC value. Also if the rows hold more than one UNINUM, if SYSTEM, DIST, or ASSOC differ between rows, or if a row’s YEAR and MONTH do not match its quarter.

Examples

>>> from call_report.fca import FCAInstitution
>>> row = {
...     "UNINUM": 722825,
...     "SYSTEM": 7,
...     "DIST": 22,
...     "ASSOC": 825,
...     "SHORTNAME": "Mid-America ACA",
...     "MAIL_ADDR": "P.O. Box 34390",
...     "STREET_ADDR": "1601 UPS Drive",
...     "CITY": "Louisville",
...     "STATE": "KY",
...     "ZIP": "40223-4390",
... }
>>> renamed = {**row, "SHORTNAME": "Farm Credit Mid-America ACA"}
>>> institution = FCAInstitution.from_roster_rows(
...     rows=[("2011-12-31", renamed), ("2011-09-30", row)]
... )
>>> institution.first_period.label, institution.last_period.label
('2011Q3', '2011Q4')

property first_period: ReportingPeriod[source]#

Return the earliest quarter this UNINUM was reported.

This is the start of the earliest of periods.

Returns:

ReportingPeriod: The first quarter of the earliest of periods.

Examples

>>> from call_report.fca import FCAInstitution
>>> row = {
...     "UNINUM": 722825,
...     "SYSTEM": 7,
...     "DIST": 22,
...     "ASSOC": 825,
...     "SHORTNAME": "Mid-America ACA",
...     "MAIL_ADDR": "P.O. Box 34390",
...     "STREET_ADDR": "1601 UPS Drive",
...     "CITY": "Louisville",
...     "STATE": "KY",
...     "ZIP": "40223-4390",
... }
>>> institution = FCAInstitution.from_roster_rows(rows=[("2011-09-30", row)])
>>> institution.first_period.label
'2011Q3'

property last_period: ReportingPeriod[source]#

Return the latest quarter this UNINUM was reported.

This is the end of the latest of periods.

Returns:

ReportingPeriod: The last quarter of the latest of periods.

Examples

>>> from call_report.fca import FCAInstitution
>>> row = {
...     "UNINUM": 722825,
...     "SYSTEM": 7,
...     "DIST": 22,
...     "ASSOC": 825,
...     "SHORTNAME": "Mid-America ACA",
...     "MAIL_ADDR": "P.O. Box 34390",
...     "STREET_ADDR": "1601 UPS Drive",
...     "CITY": "Louisville",
...     "STATE": "KY",
...     "ZIP": "40223-4390",
... }
>>> institution = FCAInstitution.from_roster_rows(
...     rows=[("2011-09-30", row), ("2012-03-31", row)]
... )
>>> institution.last_period.label
'2012Q1'

property most_recent_short_name: str | None[source]#

Return the short name from the last quarter this UNINUM was reported.

This is the value a time series for this UNINUM can carry as one stable label, whatever the short name was in earlier quarters.

Returns:

str or None: The value of the latest short_name_history version.

Examples

>>> from call_report.fca import FCAInstitution
>>> row = {
...     "UNINUM": 722825,
...     "SYSTEM": 7,
...     "DIST": 22,
...     "ASSOC": 825,
...     "SHORTNAME": "Mid-America ACA",
...     "MAIL_ADDR": "P.O. Box 34390",
...     "STREET_ADDR": "1601 UPS Drive",
...     "CITY": "Louisville",
...     "STATE": "KY",
...     "ZIP": "40223-4390",
... }
>>> renamed = {**row, "SHORTNAME": "Farm Credit Mid-America ACA"}
>>> institution = FCAInstitution.from_roster_rows(
...     rows=[("2011-09-30", row), ("2011-12-31", renamed)]
... )
>>> institution.most_recent_short_name
'Farm Credit Mid-America ACA'

property most_recent_mail_addr: str | None[source]#

Return the mailing address from the last quarter this UNINUM was reported.

This is the value a time series for this UNINUM can carry as one stable label, whatever the mailing address was in earlier quarters.

Returns:

str or None: The value of the latest mail_addr_history version.

Examples

>>> from call_report.fca import FCAInstitution
>>> row = {
...     "UNINUM": 722825,
...     "SYSTEM": 7,
...     "DIST": 22,
...     "ASSOC": 825,
...     "SHORTNAME": "Mid-America ACA",
...     "MAIL_ADDR": "P.O. Box 34390",
...     "STREET_ADDR": "1601 UPS Drive",
...     "CITY": "Louisville",
...     "STATE": "KY",
...     "ZIP": "40223-4390",
... }
>>> institution = FCAInstitution.from_roster_rows(rows=[("2011-09-30", row)])
>>> institution.most_recent_mail_addr
'P.O. Box 34390'

property most_recent_street_addr: str | None[source]#

Return the street address from the last quarter this UNINUM was reported.

This is the value a time series for this UNINUM can carry as one stable label, whatever the street address was in earlier quarters.

Returns:

str or None: The value of the latest street_addr_history version.

Examples

>>> from call_report.fca import FCAInstitution
>>> row = {
...     "UNINUM": 722825,
...     "SYSTEM": 7,
...     "DIST": 22,
...     "ASSOC": 825,
...     "SHORTNAME": "Farm Credit Mid-America ACA",
...     "MAIL_ADDR": "P.O. Box 34390",
...     "STREET_ADDR": "1601 UPS Drive",
...     "CITY": "Louisville",
...     "STATE": "KY",
...     "ZIP": "40223-4390",
... }
>>> moved = {**row, "STREET_ADDR": "12501 Lakefront Place", "ZIP": "40299-4894"}
>>> institution = FCAInstitution.from_roster_rows(
...     rows=[("2022-12-31", row), ("2023-03-31", moved)]
... )
>>> institution.most_recent_street_addr
'12501 Lakefront Place'

property most_recent_city: str | None[source]#

Return the city from the last quarter this UNINUM was reported.

This is the value a time series for this UNINUM can carry as one stable label, whatever the city was in earlier quarters.

Returns:

str or None: The value of the latest city_history version.

Examples

>>> from call_report.fca import FCAInstitution
>>> row = {
...     "UNINUM": 722825,
...     "SYSTEM": 7,
...     "DIST": 22,
...     "ASSOC": 825,
...     "SHORTNAME": "Mid-America ACA",
...     "MAIL_ADDR": "P.O. Box 34390",
...     "STREET_ADDR": "1601 UPS Drive",
...     "CITY": "Louisville",
...     "STATE": "KY",
...     "ZIP": "40223-4390",
... }
>>> institution = FCAInstitution.from_roster_rows(rows=[("2011-09-30", row)])
>>> institution.most_recent_city
'Louisville'

property most_recent_state: str | None[source]#

Return the state from the last quarter this UNINUM was reported.

This is the value a time series for this UNINUM can carry as one stable label, whatever the state was in earlier quarters.

Returns:

str or None: The value of the latest state_history version.

Examples

>>> from call_report.fca import FCAInstitution
>>> row = {
...     "UNINUM": 722825,
...     "SYSTEM": 7,
...     "DIST": 22,
...     "ASSOC": 825,
...     "SHORTNAME": "Mid-America ACA",
...     "MAIL_ADDR": "P.O. Box 34390",
...     "STREET_ADDR": "1601 UPS Drive",
...     "CITY": "Louisville",
...     "STATE": "KY",
...     "ZIP": "40223-4390",
... }
>>> institution = FCAInstitution.from_roster_rows(rows=[("2011-09-30", row)])
>>> institution.most_recent_state
'KY'

property most_recent_zip: str | None[source]#

Return the ZIP code from the last quarter this UNINUM was reported.

This is the value a time series for this UNINUM can carry as one stable label, whatever the ZIP code was in earlier quarters.

Returns:

str or None: The value of the latest zip_history version.

Examples

>>> from call_report.fca import FCAInstitution
>>> row = {
...     "UNINUM": 722825,
...     "SYSTEM": 7,
...     "DIST": 22,
...     "ASSOC": 825,
...     "SHORTNAME": "Farm Credit Mid-America ACA",
...     "MAIL_ADDR": "P.O. Box 34390",
...     "STREET_ADDR": "1601 UPS Drive",
...     "CITY": "Louisville",
...     "STATE": "KY",
...     "ZIP": "40223-4390",
... }
>>> moved = {**row, "STREET_ADDR": "12501 Lakefront Place", "ZIP": "40299-4894"}
>>> institution = FCAInstitution.from_roster_rows(
...     rows=[("2022-12-31", row), ("2023-03-31", moved)]
... )
>>> institution.most_recent_zip
'40299-4894'

as_of(*, period: str | date | ReportingPeriod) → FCAInstitutionSnapshot[source]#

Return this UNINUM’s roster values for one quarter.

Each name and address attribute takes the value of the version covering period.

Parameters:

periodstr, datetime.date, or ReportingPeriod: The quarter-end to take the snapshot at.

Returns:

FCAInstitutionSnapshot: The codes, and the name and address values in effect in period.

Raises:

PeriodNotAvailableError: If this UNINUM is not in the roster for period.

Examples

>>> from call_report.fca import FCAInstitution
>>> row = {
...     "UNINUM": 722825,
...     "SYSTEM": 7,
...     "DIST": 22,
...     "ASSOC": 825,
...     "SHORTNAME": "Mid-America ACA",
...     "MAIL_ADDR": "P.O. Box 34390",
...     "STREET_ADDR": "1601 UPS Drive",
...     "CITY": "Louisville",
...     "STATE": "KY",
...     "ZIP": "40223-4390",
... }
>>> renamed = {**row, "SHORTNAME": "Farm Credit Mid-America ACA"}
>>> institution = FCAInstitution.from_roster_rows(
...     rows=[("2011-09-30", row), ("2011-12-31", renamed)]
... )
>>> institution.as_of(period="2011-12-31").short_name
'Farm Credit Mid-America ACA'

to_dataframe(*, backend: Literal['pandas', 'polars', 'pyarrow'] | None = None, dataframe_type: None = None) → NativeDataFrame[source]#

to_dataframe(*, backend: Literal['pandas', 'polars', 'pyarrow'] | None = None, dataframe_type: Literal['pandas']) → pandas.DataFrame

to_dataframe(*, backend: Literal['pandas', 'polars', 'pyarrow'] | None = None, dataframe_type: Literal['pyarrow_table']) → pyarrow.Table

to_dataframe(*, backend: Literal['pandas', 'polars', 'pyarrow'] | None = None, dataframe_type: Literal['polars_dataframe']) → polars.DataFrame

to_dataframe(*, backend: Literal['pandas', 'polars', 'pyarrow'] | None = None, dataframe_type: Literal['polars_lazyframe']) → polars.LazyFrame

Return this UNINUM’s history as a dataframe, one row per quarter.

Each row holds the codes and the name and address values in effect in that quarter, under FCA’s own roster column names. The most_recent_* columns repeat the value from the last quarter this UNINUM was reported on every row, so a time series can carry one stable label. UNINUM and period match the key columns of FCACallReport.to_long_format and FCACallReport.to_wide_format, so the result joins onto call report data directly.

Parameters:

backend{“pandas”, “polars”, “pyarrow”}, optional: The dataframe library used to build the frame. If omitted, uses whatever backend is currently configured via call_report.config.get_config. Most users can leave this at its default.
dataframe_type{“pandas”, “pyarrow_table”, “polars_lazyframe”, “polars_dataframe”}, optional: The dataframe type to convert the result to as a final step, regardless of backend. Leave this None (the default) to get back whatever backend produced. Set it when the code that consumes this result needs a specific type, for example a pandas DataFrame while the package is configured to use polars. The conversion is zero-copy when the requested type already matches.

Returns:

NativeDataFrame: A native dataframe with columns UNINUM, period, SYSTEM, DIST, ASSOC, SHORTNAME, MAIL_ADDR, STREET_ADDR, CITY, STATE, ZIP, most_recent_short_name, most_recent_mail_addr, most_recent_street_addr, most_recent_city, most_recent_state, and most_recent_zip, ordered by period.