Taxonomy Service#

Module that handles all Factiva Analytics Taxonomies objects within the package. Contains classes and tools that allow to interact with the taxonomies and company identifier endpoints of the Factiva Analytics API.

FactivaTaxonomyCategory#

class factiva.analytics.taxonomy.factiva_taxonomies.FactivaTaxonomyCategories(value)#

Class that provides a unique way to reference the different taxonomy cateories present in Factiva data. Given the fact that the API has two versions of Subjects, Regions and Industries; only the full hierarchy version is implemented. The simple version is a sub-set of the hierarchical dataset.

Examples

Use it directly when needed. Usually as param in FactivaTaxonomy methods.

from factiva.analytics import FactivaTaxonomyCategories
FactivaTaxonomyCategories.SUBJECTS
FactivaTaxonomyCategories.REGIONS
FactivaTaxonomyCategories.COMPANIES
FactivaTaxonomyCategories.INDUSTRIES
FactivaTaxonomyCategories.EXECUTIVES

FactivaTaxonomy#

class factiva.analytics.taxonomy.factiva_taxonomies.FactivaTaxonomy(user_key=None)#

Class that represents the Factiva Taxonomy endpoints in Factiva Analytics.

Subject, industry and region taxonomies have two separate categories in the API. However, current implementation uses only a simplified version where the dataset returns all codes with the minimum set of columns to build a hierarchy.

Parameters:

user_key (str or UserKey) – String containing the 32-character long APi Key or UserKey instance that represents an existing user. If not provided, the constructor will try to obtain its value from the FACTIVA_USERKEY environment variable.

Examples

Creating a taxonomy instance with no user key. Fails if the environment variable FACTIVA_USERKEY is not set.

from factiva.analytics import FactivaTaxonomy
t = FactivaTaxonomy()

Creating a taxonomy instance providing the user key as string

from factiva.analytics import FactivaTaxonomy
t = FactivaTaxonomy(user_key='abcd1234abcd1234abcd1234abcd1234')

Creating a taxonomy instance with an existing UserKey instance

from factiva.analytics import UseKey, FactivaTaxonomy
u = UserKey('abcd1234abcd1234abcd1234abcd1234')
t = FactivaTaxonomy(user_key=u)

With the FactivaTaxonomy instance t, it’s now possible to call any method. Please see below.

download_raw_category(category: FactivaTaxonomyCategories, path=None, file_format='csv') → bool#

Downloads a CSV or AVRO file with the specified taxonomy category. The file columns preserve their original name, thus it may not match the same column naming used in other methods in this FactivaTaxonomy class.

Parameters:

  • category (FactivaTaxonomyCategories) – Enumerator entry that specifies the taxonomy category for which the codes will be retrieved.

  • path (str) – Folder path where the output file will be stored.

  • file_format (str {csv, avro}) – String specifying the download format

Returns:

True if the file is correctly downloaded. False otherwise.

Return type:

bool

Raises:

ValueError: – When the parameter file_fomat is invalid or not a string

Examples

Getting the raw file for the ‘industries’ category

from factiva.analytics import FactivaTaxonomy, FactivaTaxonomyCategories
f = FactivaTaxonomy()
f.download_raw_category(category=FactivaTaxonomyCategories.INDUSTRIES, path='/home/user/')
get_category_codes(category: FactivaTaxonomyCategories) → DataFrame#

Request for available codes in the taxonomy for the specified category.

Important

The taxonomy category FactivaTaxonomyCategories.EXECUTIVES is not currently supported by this operation. Use the download_category_codes() method instead.

Parameters:

category (FactivaTaxonomyCategories) – Enumerator entry that specifies the taxonomy category for which the codes will be retrieved.

Returns:

Dataframe containing the codes for the specified category

Return type:

pandas.DataFrame

Examples

Getting the codes for the ‘industries’ category

from factiva.analytics import FactivaTaxonomy, FactivaTaxonomyCategories
t = FactivaTaxonomy()
industry_codes = t.get_category_codes(FactivaTaxonomyCategories.INDUSTRIES)
industry_codes

              code                descriptor                                        description direct_parent
code
I0              I0               Agriculture  All farming, forestry, commercial fishing, hun...           NaN
I01001      I01001                   Farming  Agricultural crop production, seed supply and ...            i0
I03001      I03001               Aquaculture  The farming of aquatic animals and plants such...        i01001
I0100144  I0100144             Cocoa Growing                               Growing cocoa beans.        i01001
I0100137  I0100137            Coffee Growing                              Growing coffee beans.        i01001
...            ...                       ...                                                ...           ...
I162          I162             Gas Utilities  Operating gas distribution and transmission sy...           i16
IMULTI      IMULTI            Multiutilities  Utility companies with significant presence in...         iutil
I17            I17           Water Utilities  Operating water treatment plants and/or operat...         iutil
IDESAL      IDESAL              Desalination  Desalination is the process of removing salt a...           i17
IDISHEA    IDISHEA  District Heating/Cooling  Heating systems that involve the distribution ...           i17
lookup_code(code: str, category: FactivaTaxonomyCategories) → dict#

Finds the descriptor and other details based on the provide code and category. Returns all available columns for that entry.

Parameters:

  • code (str) – Factiva code for lookup

  • category (FactivaTaxonomyCategories) – Enumerator entry that specifies the taxonomy category for which the codes will be retrieved.

Returns:

Dict containing the code details

Return type:

dict

Important

The return dict structure can vary depending on the passed category and the enabled settings for the used account (e.g. company identifiers like ISIN, CUSIP, etc.).

Raises:

ValueError – When the parameter code is not a string:

Examples

Lookup a code in the ‘subjects’ category

from factiva.analytics import FactivaTaxonomy, FactivaTaxonomyCategories
f = FactivaTaxonomy()
f.lookup_code(code='CWKDIV', category=FactivaTaxonomyCategories.SUBJECTS)

{'code': 'CWKDIV', 'descriptor': 'Workplace Diversity', 'description': 'Diversity and inclusion in the workplace to ensure employees encompass varying traits such as race, gender, ethnicity, age, religion, sexual orientation, socioeconomic background or disability.', 'direct_parent': 'C42'}