XBRL is a data format used by companies, mainly for financial reporting in their 10-Q and 10-K filings. edgartools can extract data from XBRL files into dataframes as well as into custom Python classes that allow you to manipulate and visualize the data inside.
While the primary usage of XBRL is for reporting financial data, particularly for 10K and 10Q filings, it is also used to report for other non-financial filings such as 424B offerings. The edgartools data model is flexible enough to accommodate a wide variation of data across companies and filings when it comes to XBRL.
Filings with XBRL data
When getting filings, you can restrict the filings to only those that contain XBRL by using index="xbrl"
filings = get_filings(index="xbrl")
filings
Each Filing has an xbrl() function that will download and parse the XBRL attached to the filing or None if it does not.
filing = filings[0]
filing.xbrl()
Here you can see the XbrlData object for a 10-K filing. It contains 2 key things - the XBRLInstance object containing the actual data reported in the filings, and a list of statements. A statement is a grouping of facts in a logical way such as a balance sheet or income statement.
XBRLInstance - a container of facts
The main attachment on an XBRL filing is the instance document which is a container for all of the facts reported by the company. This is parsed into an XBRLInstance object that contains a data frame that you can access the data as a data frame using instance.facts.
The structure of the data frame is actually quite complicated since it has columns for different dimensions or time periods. Instead of accessing the data directly you can also use instance.query_facts() to query specific facts for dimensions or time periods.
company = Company("HRL")
financials = company.financials
xb = financials.xbrl_data
instance = xb.instance
df = instance.query_facts(concept = 'us-gaap:NetIncomeLoss')
Sometimes the XBRL facts have dimensions which is a way for companies to partition facts according to some dimension of business interest. To see the available dimensions on an instance, use instance.dimensions.
XBRLData
For more complicated XBRL, some aspects of the data will have to be resolved against the other XBRL files for that filing, such as the presentation and calculation files. In this case, the parser will return an XBRLData container containing the XBRLInstance and the other XBRL files.
These files can include
- presentation: This file describes how the XBRL data is presented in the filing. It is used to resolve the hierarchy of the data.
- calculation: This file describes how the XBRL data is calculated. It is used to resolve the calculations of the data.
- definition: This file describes the definitions of the XBRL data. It is used to resolve the meaning of the data.
- label: This file describes the labels of the XBRL data. It is used to resolve the labels of the data.
edgartools actually parse each of these files and use them to reconstruct the data as close to the original intent as possible. XBRL logic is very complicated and the tool currently does a pretty good job, but there are still improvements to be made.
Statements
Within the data are usually financial statements like the balance sheet and income statement, or other non-financial statements such as auditor information or firm disclosures.
These can be accessed using the get_statement() function. To see the statements that are included in the XBRL data, use XbrlData.statements. This is useful and often necessary since firms will use their own specific names for statements.
xb.statementsShowing a list of statements
You can select an individual statement using the bracket notation. This helps if you don't know the exact name of a statement since companies often name their statements in and non-standard way.
xb.statements[2]
You can access the underlying data in a statement as a dataframe using statement.data or using statement.get_dataframe(). The second option is preferred since the online data often have columns that you may not need to display.
Conclusion
XBRL can be tricky to work with but edgartools makes it easier for you. The tool will also become better over time so keep watching out for improvements and new releases of edgartools. Try edgartools with pip install -U edgartools