Standardized Numeric

Calcbench extracts all of the GAAP numbers in section 8, face statments and footnotes, of the 10-K/Qs. Face financials from earnings press-releases and 8-Ks are also included.

Standardized

Calcbench standardizes +1000 metrics to handle differences in filers’s tagging. The list of stardized points is @ https://www.calcbench.com/home/standardizedmetrics

calcbench.standardized_numeric.ORDERED_PIT_COLUMNS = ['ticker', 'metric', 'fiscal_year', 'fiscal_period', 'value', 'revision_number', 'preliminary', 'XBRL', 'date_reported', 'filing_type', 'CIK', 'calcbench_entity_id', 'period_start', 'period_end', 'calendar_year', 'calendar_period', 'filing_accession_number', 'trace_url', 'date_modified', 'date_XBRL_confirmed', 'confirming_XBRL_filing_ID', 'original_value']

Fields returned by point-in-time calls

calcbench.standardized_numeric.ORDERED_REGULAR_COLUMNS = ['ticker', 'metric', 'fiscal_year', 'fiscal_period', 'value', 'CIK', 'period_start', 'period_end', 'calendar_year', 'calendar_period']

Fields returned by non-point-in-time calls

calcbench.standardized_numeric.build_data_frame(raw_data, point_in_time)

The order of the columns should remain constant

Return type:

DataFrame

calcbench.standardized_numeric.standardized(company_identifiers=[], metrics=[], fiscal_year=None, fiscal_period=None, start_date=None, end_date=None, point_in_time=False, filing_id=None, pit_V2=None, XBRL_only=False, all_modifications=False, period_type=None, revisions=Revisions.All)

Standardized Numeric Data.

The data behind the multi-company page, https://www.calcbench.com/multi.

Example https://github.com/calcbench/notebooks/blob/master/python_client_api_demo.ipynb

Parameters:

• company_identifiers (Sequence[Union[str, int]]) – Tickers/CIK codes. eg. [‘msft’, ‘goog’, ‘appl’, ‘0000066740’]. If not specified get data for all companies.

• metrics (Sequence[str]) – Standardized metrics. Full list @ https://www.calcbench.com/home/standardizedmetrics eg. [‘revenue’, ‘accountsreceivable’]. If not specified get all metrics.

• fiscal_year (Optional[int]) – Fiscal year for which to get data. If not specified get all history.

• fiscal_period (Union[Period, Literal[0, 1, 2, 3, 4], None]) – Fiscal period for which to get data. If not specified get all history.

• start_date (Union[datetime, date, None]) – Restrict to records modified on or after (inclusive) this date/datetime

• end_date (Union[datetime, date, None]) – Restrict to records modified prior (exclusive) thie date/datetime

• point_in_time (bool) – Include timestamps when data was published and revision chains.

• filing_id (Optional[int]) – Filing ID for which to get data. Get all of the data reported in this filing.

• pit_V2 (Optional[bool]) – Defaults to True, use point in time V2, this only makes sense when point_in_time = True. This will go away at some point.

• XBRL_only (Optional[bool]) – Only get data that appeared in an XBRL document. If supplied with start_date and end_date it will filter by date_XBRL_confirmed, if a filing_id supplied it will filter by confirming_XBRL_filing_ID.

• all_modifications (Optional[bool]) – Include data which was either written, modified, or confirmed as XBRL, in the specified date-range or filing_id.

• period_type (Optional[PeriodType]) – Restrict results to quarterly or annual fiscal periods.

• revisions (Optional[Revisions]) – Restrict results to first or last reported values. Revisions puts you into pit_V2 mode, which means you get data from the standardized table on the back end.

Return type:

DataFrame

Returns:

Dataframe

Standardized data with a timestamp when it was published by Calcbench.

A record is returned for each filing in which a metric value changed (was revised).

If the company files an 8-K with revenue = $100 then a week later files a 10-K with revenue = $100 one record will be returned for that period. It will have preliminary=True and XBRL=True.

If the company files an 8-K with revenue = $100 and then a week later files a 10-K with revenue = $200, two records will be returned. One with revenue = $100, a revision_number=0, date_reported of 8-K, preliminary=True and XBRL=False. You will see a second line with revenue = $200, a revision_number=1, and date_reported of the 10-K, preliminary=False and XBRL=False.

If the value is revised in subsequent XBRL filings you will see a record for each filing with an incremented revision number.

date_downloaded

The timestamp on your computer when you downloaded this data.

Usage:

>>> d = calcbench.standardized(company_identifiers=['msft'],
>>>                                 point_in_time=True,)
>>> )
>>> # Put the data in a format amiable to arithmetic on columns
>>> d = calcbench.standardized(company_identifiers=['msft', 'orcl'], metrics=['StockholdersEquity', 'NetIncome'])
>>> d = d.unstack("metric")["value"]
>>> return_on_equity = d['NetIncome'] / d['StockholdersEquity']

calcbench.standardized_numeric.standardized_raw(company_identifiers=[], metrics=[], start_year=None, start_period=None, end_year=None, end_period=None, entire_universe=False, point_in_time=False, include_trace=False, all_history=False, year=None, period=None, period_type=None, use_fiscal_period=False, all_face=False, all_footnotes=False, filing_id=None, all_non_GAAP=False, all_metrics=False, pit_V2=False, start_date=None, end_date=None, XBRL_only=False, all_modifications=False, revisions=Revisions.All)

Standardized data.

Get standardized data from Calcbench. Each point is standardized by economic concept and time period.

Parameters:

• company_identifiers (Sequence[Union[str, int]]) – a sequence of tickers (or CIK codes), eg [‘msft’, ‘goog’, ‘appl’]

• metrics (Sequence[str]) – a sequence of metrics, see the full list @ https://www.calcbench.com/home/standardizedmetrics eg. [‘revenue’, ‘accountsreceivable’]

• start_year (Optional[int]) – first year of data

• start_period (Union[Period, Literal[0, 1, 2, 3, 4], None]) – first quarter to get, for annual data pass 0, for quarters pass 1, 2, 3, 4

• end_year (Optional[int]) – last year of data

• end_period (Union[Period, Literal[0, 1, 2, 3, 4], None]) – last_quarter to get, for annual data pass 0, for quarters pass 1, 2, 3, 4

• entire_universe (bool) – Get data for all companies, this can take a while, talk to Calcbench before you do this in production.

• include_trace (bool) – Include the facts used to calculate the standardized value.

• year (Optional[int]) – Get data for a single year, defaults to annual data.

• period_type (Optional[PeriodType]) – Either “annual” or “quarterly”

• filing_id (Optional[int]) – Filing id for which to get data. corresponds to the filing_id in the objects returned by the filings API.

• all_non_GAAP (bool) – include all non-GAAP metrics from earnings press releases such as EBITDA_NonGAAP. This is implied when querying by filing_id.

• all_metrics (bool) – All metrics.

• start_date (Union[datetime, date, None]) – points modified from this date (inclusive). If no time is specified all points from that date are returned.

• end_date (Union[datetime, date, None]) – points modified until this date (exclusive). If not time is specified point modified prior to this date are returned.

• XBRL_only (Optional[bool]) – Only get data that appeared in an XBRL document. If supplied with start_date and end_date it will filter by date_XBRL_confirmed, if a filing_id supplied it will filter by confirming_XBRL_filing_ID.

• all_modifications (Optional[bool]) – Include data which was either written, modified, or confirmed as XBRL, in the specified date-range or filing_id.

• revisions (Optional[Revisions]) – Restrict results to first or last reported values. Revisions puts you into pit_V2 mode, which means you get data from the standardized table on the back end.

Return type:

Sequence[StandardizedPoint]

pydantic model calcbench.models.standardized.StandardizedPoint

Replicates MappedDataPoint on the server

field CIK: str [Required]

SEC assigned Central Index Key for reporting company

field XBRL: Optional[bool] = None

Indicates the number was parsed from XBRL.

The case where preliminary and XBRL are both true indicates the number was first parsed from a non-XBRL document then “confirmed” in an XBRL document.

field calcbench_entity_id: Optional[int] = None

Internal Calcbench identifier for reporting company

field calendar_period: Period [Required]

The calendar period for this fact

field calendar_year: int [Required]

The calendar year for this fact. https://knowledge.calcbench.com/hc/en-us/articles/223267767-What-are-Calendar-Years-and-Periods-What-is-TTM-

field confirming_XBRL_filing_ID: Optional[int] = None

The filing_id of the XBRL document which contained this value.

field date_XBRL_confirmed: Optional[datetime] = None

Time at which the point was confirmed by a point from an XBRL filing. If the point originally came from an XBRL filing this will be the original write time. For values originally appearing in press-release, this will be the date of the associated 10-K/Q. If this is null, for points post April 2023, the point has not been confirmed.

field date_modified: Optional[datetime] = None

The datetime Calcbench wrote/modified this value.

Post November 2022 if this differs from the date_reported the fact was modified by Calcbench subsequent to the filing first being processed.

field date_reported: Optional[datetime] = None

Timestamp (EST) when Calcbench finished processing the filing from which this value was parsed.

In some cases, particularly prior to 2015, this will be the filing date of the document as recorded by the SEC. To exclude these points remove points where the hour is 0.

only on PIT points

field filing_accession_number: Optional[str] = None

Accession number as assigned by the SEC for the filing from which this value came.

field filing_id: Optional[int] = None

field filing_type: Optional[str] = None

10-K, 10-Q, 8-K, PRESSRELEASE, etc.

field fiscal_period: Period [Required]

Fiscal period for the fact

field fiscal_year: int [Required]

Fiscal year for the fact

field metric: str [Required]

The metric name, see the definitions @ https://www.calcbench.com/home/standardizedmetrics

field original_value: Optional[float] = None

The value that Calcbench extracted when it first processed the filing.

Post November 2022, if this differs from the value Calcbench the fact was modified by Calcbench subsequent to the filing first being processed.

field period_end: Optional[datetime] = None

Last day of the fiscal period for this fact

field period_start: Optional[datetime] = None

First day of the fiscal period for this fact

field preliminary: bool [Required]

True indicates the number was parsed from non-XBRL 8-K or press release from the wire

field revision_number: Optional[int] = None

0 indicates an original, unrevised value for this fact. 1, 2, 3… indicates subsequent revisions to the fact value. https://knowledge.calcbench.com/hc/en-us/search?utf8=%E2%9C%93&query=revisions&commit=Search

field standardized_id: Optional[int] = None

A unique identifier Calcbench assigns to each standardized value.

field ticker: str [Required]

Ticker of reporting company

field trace_facts: Optional[Sequence[TraceData]] = None

XBRL facts that went into the calculation of this point. Specify include_trace for this field to be populated.

field trace_url: Optional[str] = None

URL for a page showing the source document for this value.

field value: Union[str, float, int, None] = None

The value of the fact. Can be null, at least for dimensional points.

class calcbench.models.revisions.Revisions(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Which version of facts to get.

All = 0

All of the revisions.

AsOriginallyreported = 1

First reported value only

MostRecent = 2

Most recent reported value only

class calcbench.models.period_type.PeriodType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Annual = 'annual'

Annual

Combined = 'combined'

Annual and quarterly

Quarterly = 'quarterly'

Quarterly

TrailingTwelveMonths = 'TTM'

Trailing twelve months

class calcbench.models.period.Period(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Fiscal period.

Annual = 0

Annual data

Failure = -1

Should be few and far between, indicates something went wrong during loading

H1 = 5

First half of year

Other = 9

Irregular period, not one of the above, 18 months for example.

Q1 = 1

First quarter data

Q2 = 2

Second quarter data

Q3 = 3

Third quarter data

Q3Cum = 6

First three quarters of year

Q4 = 4

Fourth quarter data

pydantic model calcbench.models.trace.TraceData

field XBRL_fact_value: Union[str, float, int, None] = None

field dimensions: Optional[str] = None

field fact_id: Optional[int] = None

calcbench XBRL fact ID

field fiscal_period: Optional[Period] = None

fiscal period for this fact

field fiscal_year: Optional[int] = None

fiscal year for this fact

field local_name: Optional[str] = None

The XBRL tag, null for non-XBRL facts

field negative_weight: bool [Required]

field non_XBRL_label: Optional[str] = None

for points extracted from non-XBRL documents