call_report.fca.DomainDataset

class call_report.fca.DomainDataset(*, name: str, code_column: str, codes: tuple[DomainDatasetCode, ...], sources: tuple[DomainDatasetSource, ...], derived: tuple[DomainDatasetDerived, ...], split_column: str | None = None)

Bases: object

A curated view assembled from several FCA Call Report schedules.

Returned by get_fca_domain_dataset. Describes which schedules compose the view, which code each row is keyed by, and what every output column is called.

Attributes:

namestr

The dataset’s own name, matching its FCADomainDataset member.

code_columnstr

The value the reshaped frame’s code_column carries. A curated name, not any one schedule’s own code column.

codestuple[DomainDatasetCode, …]

Every code this dataset keys rows by.

sourcestuple[DomainDatasetSource, …]

The schedule groups contributing columns.

derivedtuple[DomainDatasetDerived, …]

Output columns computed from other output columns.

split_columnstr, optional

A second row key column, for a dataset whose source encodes two dimensions in one code. Each contributing code supplies its value through DomainDatasetSource.split_map. None for a dataset whose rows are keyed by code_column alone.

Examples

>>> from call_report.fca import FCADomainDataset, get_fca_domain_dataset
>>> dataset = get_fca_domain_dataset(domain_dataset=FCADomainDataset.LOAN_PORTFOLIO)
>>> dataset.name
'loan_portfolio'

property schedules: tuple[str, ...]

Return every schedule root name this dataset draws on.

Flattens the source groups back into one list, which is what a caller needs to decide which schedules to load. Grouping matters for naming, not for loading.

Returns:

tuple[str, …]

The root names, in declaration order.

Examples

>>> from call_report.fca import FCADomainDataset, get_fca_domain_dataset
>>> dataset = get_fca_domain_dataset(
...     domain_dataset=FCADomainDataset.LOAN_PORTFOLIO
... )
>>> dataset.schedules
('RCF1', 'RIE', 'RIE2')

property total_codes: frozenset[int]

Return the codes that are subtotals rather than members.

A subtotal is either a figure the source reports itself or one this package computes from other codes (see DomainDatasetCode.components). Aggregating over every code without excluding these double counts, so FCACallReport.to_domain_dataset drops them by default.

Returns:

frozenset[int]

Every DomainDatasetCode.code whose is_total is True.

Examples

>>> from call_report.fca import FCADomainDataset, get_fca_domain_dataset
>>> dataset = get_fca_domain_dataset(
...     domain_dataset=FCADomainDataset.LOAN_PORTFOLIO
... )
>>> sorted(dataset.total_codes)
[155]

property derived_codes: tuple[DomainDatasetCode, ...]

Return the codes computed by summing other codes, in order.

A source that breaks a category into parts without reporting the category’s own total leaves a reader to add the parts up. Such a code is computed after the pivot and appended alongside its members, which stay in the result.

Returns:

tuple[DomainDatasetCode, …]

Every code declaring a non-empty DomainDatasetCode.components, in declaration order.

Examples

>>> from call_report.fca import FCADomainDataset, get_fca_domain_dataset
>>> dataset = get_fca_domain_dataset(
...     domain_dataset=FCADomainDataset.LOAN_PERFORMANCE
... )
>>> [(item.code, item.label) for item in dataset.derived_codes]
[(57, 'Nonaccrual: Total')]

property source_by_schedule: Mapping[str, DomainDatasetSource]

Return each schedule’s contributing source group, by root name.

Computed once and cached on this instance, since sources never changes after construction and DomainDataset instances themselves are already cached for the life of the process by get_fca_domain_dataset.

Returns:

Mapping[str, DomainDatasetSource]

Every schedule root name in schedules, mapped to the source group that declares it.

Examples

>>> from call_report.fca import FCADomainDataset, get_fca_domain_dataset
>>> dataset = get_fca_domain_dataset(
...     domain_dataset=FCADomainDataset.LOAN_PORTFOLIO
... )
>>> dataset.source_by_schedule["RCF1"].code_column
'LOANSTATUS'

property remaps_codes: bool

Return whether any source rewrites its schedule’s own row key.

A dataset that remaps codes sums the rows that land on one curated code, since a renumbering that merges two codes into one would otherwise leave two rows where the reshape expects one. A dataset that does not keeps the stricter guarantee that the code grain is already unique. Summing groups by split_column too where there is one, so codes that merge but differ in their split value stay apart.

Returns:

bool

True if at least one source declares a non-empty code_map or split_map.

Examples

>>> from call_report.fca import FCADomainDataset, get_fca_domain_dataset
>>> dataset = get_fca_domain_dataset(
...     domain_dataset=FCADomainDataset.LOAN_PORTFOLIO
... )
>>> dataset.remaps_codes
False

classmethod from_dict(*, data: dict[str, Any]) → DomainDataset

Build a DomainDataset from one shipped definition’s parsed JSON.

Validates invariants a hand-authored definition can violate silently: that no two source groups declare the same output column unless the later one declares continues, that each source’s per-variable code values agree with whether it declares its own code_column, that only a source reporting its own codes remaps them, that a code_map targets codes the dataset declares, that every derived column names a real DerivedOperation, and that a derived column’s components are a non-empty list of real source output columns rather than another derived column’s name.

A definition with a missing or misspelled key also raises SchemaError, and the message names the dataset. The parsers in call_report.core raise the same error for the same problem.

Within one source group, an output column name may repeat across variables. That is deliberate, and is how a schedule split maps to one continuous column. Across source groups, an output column name may repeat only when the later source lists it in continues, for a split whose codedness changed and so cannot be expressed as one group.

Parameters:

datadict[str, Any]

One dataset definition’s parsed JSON.

Returns:

DomainDataset

The parsed definition.

Raises:

SchemaError

If data is malformed (a missing key, or a value of the wrong shape), if two source groups declare the same output column without the later one declaring continues, if a source’s continues names a column it does not itself produce or one no earlier source group produces, if a source’s code_column disagrees with whether its variables declare a code, if a source with no code_column declares a code_map, if a code_map targets a code the dataset does not declare, if a derived column names an operation other than "sum" or "difference", or if a derived column’s components are empty or name something no source produces.

Examples

>>> from call_report.fca._domain_datasets import DomainDataset
>>> data = {
...     "name": "example",
...     "code_column": "SEGMENT",
...     "codes": [{"code": 1, "label": "One", "is_total": False}],
...     "sources": [
...         {
...             "schedules": ["RCF1"],
...             "code_column": "LOANSTATUS",
...             "columns": {"ACCR": {"column": "accruing"}},
...         }
...     ],
...     "derived": [],
... }
>>> DomainDataset.from_dict(data=data).name
'example'