Indicators¶
istacpy.indicators.lite¶
This is a lite version of the rest of the indicators API. It’s a kind of wrapper to facilitate the access to indicators data. It’s not as powerful as the underneath functions but it hides a lot of the business logic of the API, so it’s quite suitable to quickly retrieve information.
An indicator is defined by three dimensions: geographical, time and measure. Through this lite submodule the idea is to reduce these dimensions setting a custom user value for each one:
Import the module¶
First of all, you have to import the right submodule:
>>> from istacpy.indicators.lite import indicators
Look for subjects¶
Indicators are grouped in subjects. For this purpose the function istacpy.indicators.lite.indicators.get_subjects()
is provided. Access easily to these subjects:
>>> indicators.get_subjects()
(('011', 'Territorio y usos del suelo'),
('012', 'Medio ambiente'),
('021', 'Población'),
('022', 'Movimiento natural'),
('023', 'Movimientos migratorios'),
...
Each tuple represents: subject code and subject title. Subjects are sorted by its code.
Look for indicators¶
For this purpose the function istacpy.indicators.lite.indicators.get_indicators()
is provided. Look for indicators using a subject code:
>>> indicators.get_indicators(subject_code='022')
(('DEFUNCIONES', 'Defunciones'),
('DEFUNCIONES_HOMBRES', 'Defunciones. Hombres'),
('DEFUNCIONES_MUJERES', 'Defunciones. Mujeres'),
('MATRIMONIOS_SEXO_DIFERENTE',
'Matrimonios. Entre cónyuges de diferente sexo'),
...
Each tuple represents: indicator code and indicator title. Indicators are sorted by its code. No need to paginate results since all them are retrieved at once.
You can even search for indicators within a certain subject and using a query string. For instance, let’s say you want to find out data about births within the subject with code 022
:
>>> indicators.get_indicators('nacimiento', subject_code='022')
(('NACIMIENTOS', 'Nacimientos'),
('NACIMIENTOS_HOMBRES', 'Nacimientos. Hombres'),
('NACIMIENTOS_MUJERES', 'Nacimientos. Mujeres'),
('TASA_FECUNDIDAD', 'Tasa de fecundidad'),
('TASA_FECUNDIDAD_10A14', 'Tasa de fecundidad. De 10 a 14 años'),
('TASA_FECUNDIDAD_15A19', 'Tasa de fecundidad. De 15 a 19 años'))
You are not restricted to look for indicators always within a subject. For instance, suppose you need to retrieve data about employment:
>>> indicators.get_indicators('empleo')
(('ACCIDENTES_TRABAJO_BAJA', 'Accidentes de trabajo con baja'),
('ACCIDENTES_TRABAJO_BAJA_JORNADAS',
'Accidentes de trabajo con baja. Jornadas no trabajadas'),
('AFILIACIONES', 'Afiliaciones a la Seguridad Social'),
('AFILIACIONES_AGRICULTURA',
'Afiliaciones a la Seguridad Social. Agricultura'),
('AFILIACIONES_ALOJAMIENTO',
'Afiliaciones a la Seguridad Social. Servicios de alojamiento'),
...
Internationalization¶
As seen in previous examples, information is retrieved in Spanish. But it’s also possible to set English as the default language of this lite indicators module:
>>> from istacpy.indicators.lite import i18n
>>> i18n.set_english()
Now you can search indicators using english terms and the returned values will (mostly) be also in english. In the next example indicators about employment will be looked for:
>>> indicators.get_indicators('employment')
(('AFILIACIONES_ASALARIADOS',
'Affiliations to Social Security. Wage employment'),
('AFILIACIONES_ASALARIADOS_HOMBRES',
'Affiliations to Social Security. Wage employment. Men'),
('AFILIACIONES_ASALARIADOS_MUJERES',
'Affiliations to Social Security. Wage employment. Women'),
('AFILIACIONES_AUTONOMOS',
'Affiliations to Social Security. Self-employment'),
('AFILIACIONES_AUTONOMOS_HOMBRES',
'Affiliations to Social Security. Self-employment. Men'),
...
It’s possible to go back and enable again spanish language using i18n.set_spanish()
.
Note
Not all data from API is fully translated to English. So please be patient if it’s the case for you.
Indicator¶
Once you have identified which indicator you want to work with, it’s time to get it from the API. To accomplish it, you will have to use the indicator code. Let’s say you are interested in population, and more precisely, in the POBLACION
indicator:
>>> indicator = indicators.get_indicator('POBLACION')
>>> indicator
POBLACION (Population)
For this purpose the class istacpy.indicators.lite.indicators.Indicator
is provided. You can get more information about this indicator using the next method:
>>> indicator.info()
· Class: istacpy.indicators.lite.indicators.Indicator
· Indicator code: POBLACION
· Title: Population
· Subject: Not available
· Description: Number of persons according to official population figures, referred to 1 January of each year, drawn from the Municipal Population Register
· Geographical granularities: {'COUNTIES': 'C', 'ISLANDS': 'I', 'REGIONS': 'R', 'MUNICIPALITIES': 'M'}
· Time granularities: {'YEARLY': 'Y'}
· Measures: {'ABSOLUTE': 'A', 'ANNUAL_PERCENTAGE_RATE': 'N', 'INTERPERIOD_PERCENTAGE_RATE': 'I', 'ANNUAL_PUNTUAL_RATE': 'M', 'INTERPERIOD_PUNTUAL_RATE': 'J'}
· Available years: 2000,2001,2002,2003,2004,2005,2006,2007,2008,2009,2010,2011,2012,2013,2014,2015,2016,2017,2018,2019
As you can see, every field contains helpful information:
Class: shows the full qualified name of the indicator.
Indicator code: shows the indicator code and can be also independently accessed through the
code
attribute.Title: shows the indicator title (internationalized if proceed) and can be also independently accessed through the
title
attribute.Subject: shows the subject where this indicator is included (internationalized if proceed) and can be also independently accessed through the
subject
attribute.Description: shows the indicator description (internationalized if proceed) and can be also independently accessed through the
description
attribute.Geographical granularities: shows the available geographical granularities for this indicator and can be also independently accessed through the
geographical_granularities
attribute. It’s a dict where keys are granularity codes and values are granularity ids (they will be use later).Time granularities: shows the available time granularities for this indicator and can be also independently accessed through the
time_granularities
attribute. It’s a dict where keys are granularity codes and values are granularity ids (they will be used later).Measures: shows the available measures for this indicator and can be also independently accessed through the
measures
attribute. It’s a dict where keys are measure codes and values are measure ids (they will be used later).Available years: shows the available years (as time dimension) for this indicator and can be also independently accessed through the
available_years
attribute. It’s a list containing the available years for the different combinations of granularities and measures.
Note
It’s possible that some available year has no data for a certain combination of granularities and measures, since available_years
is just a summary of all possible time slots.
Since this object internally uses an istacpy.indicators.indicators method to retrieve data from API, you can always access this information through indicator.api_response
.
Indicator Data¶
Once you have inspected our indicator, you are ready to get some data from it. For this purpose the method istacpy.indicators.lite.indicators.Indicator.get_data()
is provided. Suppose you need to know the evolution of population on every Canary island. Query this through the next sentence:
>>> data = indicator.get_data(geo='I')
>>> data
POBLACION (Población)
<2000,2001,2002,2003,2004,2005,2006,2007,2008,2009,2010,2011,2012,2013,2014,2015,2016,2017,2018,2019>
{'Lanzarote': (96310, 103044, 109942, 114715, 116782, 123039, 127457, 132366, 139506, 141938, 141437, 142517, 142132, 141953, 141940, 143209, 145084, 147023, 149183, 152289), 'Fuerteventura': (60124, 66025, 69762, 74983, 79986, 86642, 89680, 94386, 100929, 103167, 103492, 104072, 106456, 109174, 106930, 107367, 107521, 110299, 113275, 116886), 'Gran Canaria': (741161, 755489, 771333, 789908, 790360, 802247, 807049, 815379, 829597, 838397, 845676, 850391, 852225, 852723, 851157, 847830, 845195, 843158, 846717, 851231), 'Tenerife': (709365, 744076, 778071, 799889, 812839, 838877, 852945, 865070, 886033, 899833, 906854, 908555, 898680, 897582, 889936, 888184, 891111, 894636, 904713, 917841), 'La Gomera': (18300, 18990, 19098, 19580, 21220, 21746, 21952, 22259, 22622, 22769, 22776, 23076, 22350, 21153, 20721, 20783, 20940, 20976, 21136, 21503), 'La Palma': (82483, 84319, 85547, 85631, 84282, 85252, 86062, 85933, 86528, 86996, 87324, 87163, 85468, 85115, 83456, 82346, 81486, 81350, 81863, 82671), 'El Hierro': (8533, 9423, 10002, 10162, 10071, 10477, 10688, 10558, 10753, 10892, 10960, 10995, 11033, 10979, 10675, 10587, 10587, 10679, 10798, 10968)}
For this purpose the class istacpy.indicators.lite.indicators.IndicatorData
is provided. Get more information about this data using the next method:
>>> data.info()
· Class: istacpy.indicators.lite.indicators.IndicatorData
· Indicator code: POBLACION
· Title: Población
· Geographical granularity: ISLANDS
· Time granularity: YEARLY
· Measure: ABSOLUTE
· Index: 2000,2001,2002,2003,2004,2005,2006,2007,2008,2009,2010,2011,2012,2013,2014,2015,2016,2017,2018,2019
· Columns: Lanzarote,Fuerteventura,Gran Canaria,Tenerife,La Gomera,La Palma,El Hierro
· Shape: (20, 7)
· Num. observations: 140
As you can see, every field contains helpful information:
Class: shows the full qualified name of the indicator data.
Indicator code: shows the indicator code and can be also independently accessed through the
code
attribute.Title: shows the indicator title (internationalized if proceed) and can be also independently accessed through the
title
attribute.Geographical granularity: shows the pinned geographical granularity for this dataset and can be also independently accessed through the
geographical_granularity
attribute.Time granularity: shows the pinned time granularity for this dataset and can be also independently accessed through the
time_granularity
attribute.Measure: shows the pinned measure for this dataset and can be also independently accessed through the
measure
attribute.Index: shows the index of the dataset as a tuple of sorted years. It can be also independently accessed through the
index
attribute.Columns: shows the columns of the dataset as a tuple of geographical locations. It can be also independently accessed through the
columns
attribute.Shape: shows a tuple with index size by columns size and can be also independently accessed through the
shape
attribute.Num. observations: shows the total number of observations within the dataset and can be also independently accessed through the
num_observations
attribute.
Although data itself is not shown on info()
calling, it’s always available through .data
attribute:
>>> data.data
{'Lanzarote': (96310,
103044,
109942,
114715,
116782,
123039,
127457,
132366,
139506,
141938,
141437,
142517,
142132,
141953,
141940,
143209,
145084,
147023,
149183,
152289),
'Fuerteventura': (60124,
66025,
69762,
...
Note
Each indicator is linked to an indicator data. So, you can access extra information through this attribute data.indicator
.
Since this object internally uses an istacpy.indicators.indicators method to retrieve data from API, you can always access this information through data.api_response
.
Convert to dataframe¶
In case you are working with Pandas it’s super easy to convert indicator data to dataframe:
>>> data.as_dataframe()
Lanzarote Fuerteventura Gran Canaria Tenerife La Gomera La Palma El Hierro
2000 96310 60124 741161 709365 18300 82483 8533
2001 103044 66025 755489 744076 18990 84319 9423
2002 109942 69762 771333 778071 19098 85547 10002
2003 114715 74983 789908 799889 19580 85631 10162
2004 116782 79986 790360 812839 21220 84282 10071
2005 123039 86642 802247 838877 21746 85252 10477
2006 127457 89680 807049 852945 21952 86062 10688
2007 132366 94386 815379 865070 22259 85933 10558
2008 139506 100929 829597 886033 22622 86528 10753
2009 141938 103167 838397 899833 22769 86996 10892
2010 141437 103492 845676 906854 22776 87324 10960
2011 142517 104072 850391 908555 23076 87163 10995
2012 142132 106456 852225 898680 22350 85468 11033
2013 141953 109174 852723 897582 21153 85115 10979
2014 141940 106930 851157 889936 20721 83456 10675
2015 143209 107367 847830 888184 20783 82346 10587
2016 145084 107521 845195 891111 20940 81486 10587
2017 147023 110299 843158 894636 20976 81350 10679
2018 149183 113275 846717 904713 21136 81863 10798
2019 152289 116886 851231 917841 21503 82671 10968
Important
pip install pandas
is a required dependency in case you want to use .as_dataframe()
method.
For this purpose the method istacpy.indicators.lite.indicators.Indicator.as_dataframe()
is provided.
Convert to list¶
It’s also possible to flatten data and get a list of values as follows:
>>> data.as_list()
[96310,
103044,
109942,
114715,
116782,
123039,
127457,
...
10979,
10675,
10587,
10587,
10679,
10798,
10968]
For this purpose the method istacpy.indicators.lite.indicators.Indicator.as_list()
is provided.
Default values¶
If no arguments are given, you will get data with default granularities and measures. More precisely, returned data will use the following specifications by default:
Geographical granularity: will be set by default as the granularity with the largest available grain.
Time granularity: will be set by default as the granularity with the largest available grain.
Measure: will be set by default as the absolute measure.
For example, you could get data from population indicator as follows (using default values):
>>> data = indicator.get_data()
>>> data
POBLACION (Población)
<2000,2001,2002,2003,2004,2005,2006,2007,2008,2009,2010,2011,2012,2013,2014,2015,2016,2017,2018,2019>
{'Canarias': (1716276, 1781366, 1843755, 1894868, 1915540, 1968280, 1995833, 2025951, 2075968, 2103992, 2118519, 2126769, 2118344, 2118679, 2104815, 2100306, 2101924, 2108121, 2127685, 2153389)}
Check the used values for granularities and measure as follows:
>>> data.geographical_granularity
'REGIONS'
>>> data.time_granularity
'YEARLY'
>>> data.measure
'ABSOLUTE'
Query format¶
One of the most important features of this module is to allow queries in an easy and powerful way. Let’s see distinct use cases to demonstrate its capabitilies.
A population indicator will be used within the next examples:
>>> indicator = indicators.get_indicator('POBLACION')
>>> indicator.info()
· Class: istacpy.indicators.lite.indicators.Indicator
· Indicator code: POBLACION
· Title: Population
· Subject: Not available
· Description: Number of persons according to official population figures, referred to 1 January of each year, drawn from the Municipal Population Register
· Geographical granularities: {'REGIONS': 'R', 'ISLANDS': 'I', 'COUNTIES': 'C', 'MUNICIPALITIES': 'M'}
· Time granularities: {'YEARLY': 'Y'}
· Measures: {'ABSOLUTE': 'A', 'ANNUAL_PERCENTAGE_RATE': 'N', 'INTERPERIOD_PERCENTAGE_RATE': 'I', 'ANNUAL_PUNTUAL_RATE': 'M', 'INTERPERIOD_PUNTUAL_RATE': 'J'}
· Available years: 2000,2001,2002,2003,2004,2005,2006,2007,2008,2009,2010,2011,2012,2013,2014,2015,2016,2017,2018,2019
Evolution of population in counties of Tenerife
>>> data = indicator.get_data(geo='C|Tenerife')
>>> data.info()
· Class: istacpy.indicators.lite.indicators.IndicatorData
· Indicator code: POBLACION
· Title: Population
· Geographical granularity: COUNTIES
· Time granularity: YEARLY
· Measure: ABSOLUTE
· Index: 2000,2001,2002,2003,2004,2005,2006,2007,2008,2009,2010,2011,2012,2013,2014,2015,2016,2017,2018,2019
· Columns: Tenerife - Área Metropolitana,Tenerife Norte - Acentejo,Tenerife Norte - Daute,Tenerife Norte - Icod,Tenerife Norte - Valle de La Orotava,Tenerife Sur - Abona,Tenerife Sur - Suroeste,Tenerife Sur - Valle de Güímar
· Shape: (20, 8)
· Num. observations: 160
Here we used the geo
argument (for geographical granularity), indicating C
for COUNTIES
and filtering by Tenerife. As we described in Default values, measure is set to absolute when no value is provided.
Evolution of population in municipalities of Lanzarote and Fuerteventura
>>> data = indicator.get_data(geo='M|Lanzarote,Fuerteventura')
>>> data.info()
· Class: istacpy.indicators.lite.indicators.IndicatorData
· Indicator code: POBLACION
· Title: Population
· Geographical granularity: MUNICIPALITIES
· Time granularity: YEARLY
· Measure: ABSOLUTE
· Index: 2000,2001,2002,2003,2004,2005,2006,2007,2008,2009,2010,2011,2012,2013,2014,2015,2016,2017,2018,2019
· Columns: Arrecife,Haría,San Bartolomé,Teguise,Tías,Tinajo,Yaiza,Antigua,Betancuria,La Oliva,Pájara,Puerto del Rosario,Tuineje
· Shape: (20, 13)
· Num. observations: 260
Here we used the geo
argument (for geographical granularity), indicating M
for MUNICIPALITIES
and filtering by Lanzarote and Gran Canaria. As we described in Default values, measure is set to absolute when no value is provided.
Comparation of population in counties between 2009 and 2019
>>> data = indicator.get_data(geo='C', time='Y|2009:2019')
>>> data.info()
· Class: istacpy.indicators.lite.indicators.IndicatorData
· Indicator code: POBLACION
· Title: Population
· Geographical granularity: COUNTIES
· Time granularity: YEARLY
· Measure: ABSOLUTE
· Index: 2009,2010,2011,2012,2013,2014,2015,2016,2017,2018,2019
· Columns: Lanzarote - Este,Lanzarote - Norte,Lanzarote - Suroeste,Fuerteventura - Centro,Fuerteventura - Norte,Fuerteventura - Sur,Gran Canaria - Área Metropolitana,Gran Canaria Norte - Centro Norte,Gran Canaria Norte - Noroeste,Gran Canaria Norte - Oeste,Gran Canaria Sur - Sur,Gran Canaria Sur - Sureste,Tenerife - Área Metropolitana,Tenerife Norte - Acentejo,Tenerife Norte - Daute,Tenerife Norte - Icod,Tenerife Norte - Valle de La Orotava,Tenerife Sur - Abona,Tenerife Sur - Suroeste,Tenerife Sur - Valle de Güímar,La Gomera - Norte,La Gomera - Sur,La Palma - Capitalina,La Palma - Noreste,La Palma - Noroeste,La Palma - Valle de Aridane,El Hierro - El Hierro
· Shape: (11, 27)
· Num. observations: 297
Here we used the geo
argument (for geographical granularity), indicating C
for COUNTIES
and time
argument (for time granularity), indicating Y
for YEARLY
and filtering with a range between two years. Range can be either specified with :
or -
. As we described in Default values, measure is set to absolute when no value is provided.
Comparation of population in islands between first and last available years
>>> data = indicator.get_data(geo='I', time='Y|F,L')
>>> data.info()
· Class: istacpy.indicators.lite.indicators.IndicatorData
· Indicator code: POBLACION
· Title: Population
· Geographical granularity: ISLANDS
· Time granularity: YEARLY
· Measure: ABSOLUTE
· Index: 2000,2019
· Columns: Lanzarote,Fuerteventura,Gran Canaria,Tenerife,La Gomera,La Palma,El Hierro
· Shape: (2, 7)
· Num. observations: 14
Here we used the geo
argument (for geographical granularity), indicating I
for ISLANDS
and time
argument (for time granularity) filtering by first available year (denoted by F
) and last available year (denoted by L
). Note that time filter uses a comma indicating separate values. As we described in Default values, measure is set to absolute when no value is provided.
Comparation of population in municipalities of La Gomera between 2005-2010 and 2015-last available year
>>> data = indicator.get_data(geo='M|La Gomera', time='Y|2005:2010,2015:L')
>>> data.info()
· Class: istacpy.indicators.lite.indicators.IndicatorData
· Indicator code: POBLACION
· Title: Population
· Geographical granularity: MUNICIPALITIES
· Time granularity: YEARLY
· Measure: ABSOLUTE
· Index: 2005,2006,2007,2008,2009,2010,2015,2016,2017,2018,2019
· Columns: Agulo,Alajeró,Hermigua,San Sebastián de La Gomera,Valle Gran Rey,Vallehermoso
· Shape: (11, 6)
· Num. observations: 66
Here we used the geo
argument (for geographical granularity), indicating M
for MUNICIPALITIES
and filtering by La Gomera and time
argument (for time granularity) indicating Y
for YEARLY
and filtering by the required ranges. Note that L
stands for last available year and can be used in every expression. As we described in Default values, measure is set to absolute when no value is provided.
Evolution of population in counties of Gran Canaria in annual percentage rate
>>> data = indicator.get_data(geo='C|Gran Canaria', measure='N')
>>> data.info()
· Class: istacpy.indicators.lite.indicators.IndicatorData
· Indicator code: POBLACION
· Title: Population
· Geographical granularity: COUNTIES
· Time granularity: YEARLY
· Measure: ANNUAL_PERCENTAGE_RATE
· Index: 2000,2001,2002,2003,2004,2005,2006,2007,2008,2009,2010,2011,2012,2013,2014,2015,2016,2017,2018,2019
· Columns: Gran Canaria - Área Metropolitana,Gran Canaria Norte - Centro Norte,Gran Canaria Norte - Noroeste,Gran Canaria Norte - Oeste,Gran Canaria Sur - Sur,Gran Canaria Sur - Sureste
· Shape: (20, 6)
· Num. observations: 120
Here we used the geo
argument (for geographical granularity), indicating C
for COUNTIES
and filtering by Gran Canaria and measure
argument (for measure representation) indicating N
for ANNUAL_PERCENTAGE_RATE
. As we described in Default values, time is set to largest grane when no value is provided.
Evolution of vehicles in circulation in every Canary island with monthly values during the last available year
First of all you have to choose the right indicator:
>>> indicator = indicators.get_indicator('PARQUE_VEHICULOS')
>>> indicator.info()
· Class: istacpy.indicators.lite.indicators.Indicator
· Indicator code: PARQUE_VEHICULOS
· Title: National feet of vehicles
· Subject: Not available
· Description: Number of vehicles in circulation according to the fleet prepared by the Spanish Traffic Authority. The reference date is the last day of each month
· Geographical granularities: {'REGIONS': 'R', 'ISLANDS': 'I', 'MUNICIPALITIES': 'M'}
· Time granularities: {'YEARLY': 'Y', 'MONTHLY': 'M'}
· Measures: {'ABSOLUTE': 'A', 'ANNUAL_PERCENTAGE_RATE': 'N', 'INTERPERIOD_PERCENTAGE_RATE': 'I', 'ANNUAL_PUNTUAL_RATE': 'M', 'INTERPERIOD_PUNTUAL_RATE': 'J'}
· Available years: 2005,2006,2007,2008,2009,2010,2011,2012,2013,2014,2015,2016,2017
Now you can make the right query:
>>> data = indicator.get_data(geo='I', time='M|L')
>>> data.info()
· Class: istacpy.indicators.lite.indicators.IndicatorData
· Indicator code: PARQUE_VEHICULOS
· Title: National feet of vehicles
· Geographical granularity: ISLANDS
· Time granularity: MONTHLY
· Measure: ABSOLUTE
· Index: Jan 2017,Feb 2017,Mar 2017,Apr 2017,May 2017,Jun 2017,Jul 2017,Aug 2017,Sep 2017,Oct 2017,Nov 2017,Dec 2017
· Columns: Lanzarote,Fuerteventura,Gran Canaria,Tenerife,La Gomera,La Palma,El Hierro
· Shape: (12, 7)
· Num. observations: 84
>>> data
PARQUE_VEHICULOS (National feet of vehicles)
<Jan 2017,Feb 2017,Mar 2017,Apr 2017,May 2017,Jun 2017,Jul 2017,Aug 2017,Sep 2017,Oct 2017,Nov 2017,Dec 2017>
{'Lanzarote': (119405, 119707, 120112, 120313, 120913, 121656, 122850, 123042, 123401, 123774, 124536, 125137), 'Fuerteventura': (81898, 82203, 82561, 82748, 83077, 83444, 83851, 84170, 84499, 84949, 85208, 85485), 'Gran Canaria': (607174, 608634, 610313, 610878, 612377, 614437, 617703, 619479, 621736, 625164, 626967, 628259), 'Tenerife': (687245, 689104, 691208, 693475, 695655, 697987, 700952, 702968, 704847, 706923, 709383, 710869), 'La Gomera': (14627, 14666, 14684, 14715, 14742, 14771, 14798, 14808, 14838, 14893, 14956, 14984), 'La Palma': (67895, 68034, 68205, 68362, 68532, 68737, 68871, 69037, 69200, 69443, 69679, 69652), 'El Hierro': (8180, 8203, 8218, 8250, 8262, 8286, 8325, 8345, 8378, 8402, 8442, 8451)}
Here we used the geo
argument (for geographical granularity), indicating I
for ISLANDS
and time
argument (for time granularity), indicating M
for MONTHLY
and filtering by L
(for the last available year). As we described in Default values, measure is set to absolute when no value is provided.
Automatic conversion of data¶
API essentially returns string data. This lite module converts values to its proper numeric representation (int
or float
). Besides, it handles possible NaN
values (not a number) when conversion is not possible.
This feature can be illustrated throught a sales of cement indicator. Let’s retrieve some data:
>>> indicator = indicators.get_indicator('CEMENTO_VENTAS')
>>> indicator
CEMENTO_VENTAS (Wholesale of cement)
>>> data = indicator.get_data()
Let’s take a look of the API response:
>>> data.api_response['observation']
['562199.2',
'587198.8',
'527980.0',
'508627.2',
'498687.5',
'451703.5',
'440478.3',
'517181.9',
'678307.4',
'819994.0',
'.']
You can see that values are strings and a dot is also in the list. These values are correctly handled by the lite module, converting them to numeric types and identifying NaN
observations:
>>> data
CEMENTO_VENTAS (Wholesale of cement)
<2009,2010,2011,2012,2013,2014,2015,2016,2017,2018,2019>
{'Canarias': ('NaN', 819994.0, 678307.4, 517181.9, 440478.3, 451703.5, 498687.5, 508627.2, 527980.0, 587198.8, 562199.2)}
Automatic conversion from multipying units¶
There are some indicators whose response from API is based on multiplying units, that is, returned values must be multiplied by this factor to get the real ones.
This module converts automatically these values to stop worrying about factors.
For example, if you are working with unemployed population, this indicator has a thousands multiplying unit. Let’s see how this automatic conversion works:
>>> indicator = indicators.get_indicator('POBLACION_PARADA')
>>> indicator.info()
· Class: istacpy.indicators.lite.indicators.Indicator
· Indicator code: POBLACION_PARADA
· Title: Unemployed population
· Subject: Not available
· Description: Persons aged 16 years and more without work, available to start work and had actively sought work
· Geographical granularities: {'REGIONS': 'R', 'ISLANDS': 'I', 'COUNTIES': 'C'}
· Time granularities: {'QUARTERLY': 'Q'}
· Measures: {'ABSOLUTE': 'A', 'ANNUAL_PERCENTAGE_RATE': 'N', 'INTERPERIOD_PERCENTAGE_RATE': 'I', 'ANNUAL_PUNTUAL_RATE': 'M', 'INTERPERIOD_PUNTUAL_RATE': 'J'}
· Available years: 2002,2003,2004,2005,2006,2007,2008,2009,2010,2011,2012,2013,2014,2015,2016,2017,2018,2019,2020
>>> data = indicator.get_data()
Let’s compare the last three values of data
against the last three raw values from API response:
>>> data.api_response['observation'][-3:][::-1]
['7.62', '9.66', '9.87']
>>> values = data.as_list()
>>> values[:3]
[7620.0, 9660.0, 9870.0]
You can check that values are correctly converted.
Getting raw codes¶
By default, the .get_data()
method provides titles for index and columns (when possible). This behaviour can be changed if you specify =
as a prefix on the query string (for each dimension).
Query in a “normal” way:
>>> indicator = indicators.get_indicator('POBLACION')
>>> data = indicator.get_data(geo='I')
>>> data.columns
('Lanzarote',
'Fuerteventura',
'Gran Canaria',
'Tenerife',
'La Gomera',
'La Palma',
'El Hierro')
Query indicating to return raw codes:
>>> indicator = indicators.get_indicator('POBLACION')
>>> data = indicator.get_data(geo='=I')
>>> data.columns
('ES708', 'ES704', 'ES705', 'ES709', 'ES706', 'ES707', 'ES703')
Note
This can be used in time dimension as well.
istacpy.indicators.geographic¶
- istacpy.indicators.geographic.get_indicators_geographic_granularities()¶
Get geographic granularities
This function returns a list of geographic granularities treated in the ISTAC-indicators database. For example provincial, insular or municipal granularity.
Examples
>>> get_indicators_geographic_granularities()
- istacpy.indicators.geographic.get_indicators_geographical_values(geographicalgranularitycode, subjectcode='', systemcode='')¶
Get geographical values
This function returns values of a geographical granularity that in turn are part of a specific theme or system of indicators.
- Parameters
geographicalgranularitycode (string) – geographical granularity code
subjectcode (string) – subject code
systemcode (string) – system code
Examples
>>> get_indicators_geographical_values("REGIONS") >>> get_indicators_geographical_values( ... "REGIONS", ... subjectcode="051", ... systemcode="C00067A" )
- istacpy.indicators.geographic.get_indicators_subjects()¶
Get subjects
This function returns all subjects which the ISTAC classifies its statistical operations.
Examples
>>> get_indicators_subjects()
- istacpy.indicators.geographic.get_indicators_time_granularities()¶
Get time granularities
This function returns a list of temporary granularity treated in the ISTAC data bank-indicators ordered from highest to lowest granularity. For example annual, quarterly or monthly granularity.
Examples
>>> get_indicators_time_granularities()
istacpy.indicators.indicators¶
Example 1: Get a list of all available indicators:
from istacpy.indicators import indicators
indicators.get_indicators()
Example 2: Get a list of geographic granularities treated in the ISTAC-indicators database. For example provincial, insular or municipal granularity:
from istacpy.indicators import geographic
geographic.get_indicators_geographic_granularities()
- istacpy.indicators.indicators.get_indicators(q='', order='', limit=25, offset=0, fields='', representation='')¶
Get indicators
This function returns a list of indicators published in the ISTAC-indicators database. An indicator is a measure used to know the intensity of a phenomenon in spacetime. This measure can refer to different spatial or temporal granularities.
- Parameters
q (string) – Metadata query on which the searches can be built using
id
,subjectCode
orgeographicValue
.order (string) – Order. Possible values are:
update
andid
. Order criteria areASC
andDESC
.limit (int) – Results limit. By default
limit = 25
.offset (int) – Displacement. Result from which it is returned. By default
offset = 0
.fields (string) – Use of the answer by adding new fields. Possible values are:
+metadata
,+data
and+observationsMetadata
.representation (string) – Allows filtering the observations by their value. Its use only makes sense when
+data
and/or+observationsMetadata
has been included.
Examples
>>> get_indicators( ... q='id IN ("AFILIACIONES", "EMPLEO_REGISTRADO_AGRICULTURA")', ... order="id ASC", ... fields="+data", ... representation="GEOGRAPHICAL[35003|35005], MEASURE[ABSOLUTE]" ... )
- istacpy.indicators.indicators.get_indicators_code(indicatorcode)¶
Get indicators code
This function returns the metadata that describe the characteristics of a specific indicator, allowing the compression of the measured fact; also through the data request the complete data (for all spacetime) of the indicator is provided.
- Parameters
indicatorcode (string) – an indicator code
Examples
>>> get_indicators_code("AFILIACIONES") >>> get_indicators_code("PARO_REGISTRADO")
- istacpy.indicators.indicators.get_indicators_code_data(indicatorcode, representation='', granularity='', fields='')¶
Get indicators code data
This function returns complete data (for all spacetime) of the indicator. On the other hand, metadata describing the characteristics of a specific indicator are offered through the metadata request, allowing the compression of the measured fact.
- Parameters
indicatorcode (string) – an indicator code
representation (string) – Allows filtering the observations by their value.
granularity (string) – Allows to filter the observations through the granularities of the same.
fields (string) – Allows you to customize the response by excluding fields. The possible values are:
-observationsMetadata
.
Examples
>>> get_indicators_code_data("AFILIACIONES")
istacpy.indicators.systems¶
- istacpy.indicators.systems.get_indicators_systems(limit=25, offset=0)¶
Get indicators systems
This function returns a list of indicator systems published in the ISTAC-indicators database. The indicators are simple or compound statistics, however a single indicator can rarely provide useful information about complex phenomena such as the economic situation, living conditions, schooling or others. Indicator systems are generally designed to generate more and more accurate information about the conditions of a phenomenon; and for this they are organized in dimensions or areas of analysis, under which the indicators are integrated.
- Parameters
limit (int) – Results limit. By default
limit = 25
.offset (int) – Displacement. Result from which it is returned. By default
offset = 0
.
Examples
>>> get_indicators_systems()
- istacpy.indicators.systems.get_indicators_systems_code(indicatorsystemcode)¶
Get indicators system code
This function returns metadata of a system of indicators published in the ISTAC-indicators database. The indicators are simple or compound statistics, however a single indicator can rarely provide useful information about complex phenomena such as the economic situation, living conditions, schooling or others.
- Parameters
indicatorsystemcode (string) – an indicator system code
Examples
>>> get_indicators_systems_code("C00075H")
- istacpy.indicators.systems.get_indicators_systems_code_instances(indicatorsystemcode, q='', order='', limit=25, offset=0, fields='', representation='', granularity='')¶
Get indicators system code instances
This function returns instances of indicators associated with a specific indicator system. An instance of an indicator is nothing more than a spatio-temporal query of an indicator when it is incorporated into a specific indicator system.
- Parameters
indicatorsystemcode (string) – with an indicator system code
q (string) – Query of metadata on which the searches can be built are:
id
andgeographicalValue
.order (string) – Order. Possible values are:
update
andid
and order criteria areASC
andDESC
.limit (int) – Results limit. By default
limit = 25
.offset (int) – Displacement. Result from which it is returned. By default
offset = 0
.fields (string) – Use of the answer by adding new fields. Possible values are:
+metadata
,+data
and+observationsMetadata
.representation (string) – Allows filtering the observations by their value. Its use only makes sense when
+data
and/or+observationsMetadata
has been included.granularity (string) – Allows to filter the observations through the granularities of the same. Its use only makes sense when
+data
and/or+observationsMetadata
has been included.
Examples
>>> get_indicators_systems_code_instances("C00075H") >>> get_indicators_systems_code_instances( ... "C00075H", ... q='id EQ "INDICADORES_MUNICIPALES"' ... )
- istacpy.indicators.systems.get_indicators_systems_code_instances_code(indicatorsystemcode, indicatorinstancecode)¶
Get indicators system code instances code
This function returns metadata of an indicator set associated with a specific indicator system. An instance of an indicator is nothing more than a spatio-temporal query of an indicator when it is incorporated into a specific indicator system.
- Parameters
indicatorsystemcode (string) –
indicatorinstancecode (string) –
Examples
>>> get_indicators_systems_code_instances_code( ... "C00075H", ... "21af0477-d63b-493b-ad02-4ab181547223" ... )
- istacpy.indicators.systems.get_indicators_systems_code_instances_code_data(indicatorsystemcode, indicatorinstancecode, representation='', granularity='', fields='')¶
Get indicators system code instances code data
This function returns data of an indicator unit associated with a specific indicator system. An instance of an indicator is nothing more than a spatio-temporal query of an indicator when it is incorporated into a specific indicator system.
- Parameters
indicatorsystemcode (string) – Indicator system code
indicatorinstancecode (string) – Indicator instance code
representation (string) – Allows filtering the observations by their value.
granularity (string) – Allows to filter the observations through the granularities of the same.
fields (string) – Allows you to customize the response by excluding fields. The possible values are:
-observationsMetadata
.
Examples
>>> get_indicators_systems_code_instances_code_data( ... "C00075H", ... "21af0477-d63b-493b-ad02-4ab181547223" ... )