Skip to content
Snippets Groups Projects
Commit 930be7b1 authored by Dóra Kocsis's avatar Dóra Kocsis
Browse files

cosmetics to README.md

parent c217ce99
No related branches found
No related tags found
No related merge requests found
Hide whitespace changes
Inline Side-by-side
Showing
with 44 additions and 30 deletions
README.md
+ 44
− 30
View file @ 930be7b1
...@@ -36,7 +36,9 @@ A series identifier (ID) is defined by three values, formatted like this: `provi ...@@ -36,7 +36,9 @@ A series identifier (ID) is defined by three values, formatted like this: `provi
The `fetch_series` function is used to construct the cell array. The `fetch_series` function is used to construct the cell array.
For example, to fetch the time series `EA19.1.0.0.0.ZUTN` from the For example, to fetch the time series `EA19.1.0.0.0.ZUTN` from the
[\"Unemployment rate\" [ZUTN] dataset](https://db.nomics.world/AMECO/ZUTN) [\"Unemployment rate\" [ZUTN] dataset](https://db.nomics.world/AMECO/ZUTN)
belonging to the [AMECO provider](https://db.nomics.world/AMECO): belonging to the [AMECO provider](https://db.nomics.world/AMECO).
Example:
>> df_id = fetch_series('series_ids',"AMECO/ZUTN/EA19.1.0.0.0.ZUTN"); >> df_id = fetch_series('series_ids',"AMECO/ZUTN/EA19.1.0.0.0.ZUTN");
...@@ -71,27 +73,29 @@ The returned data is stored in the `df_id` variable. Its type is a cell array. T ...@@ -71,27 +73,29 @@ The returned data is stored in the `df_id` variable. Its type is a cell array. T
>> >>
In such cell array, you will always find at least those columns: In such cell array, you will always find at least those columns:
* x_frequency: (harmonized frequency generated by DBnomics) * `x_frequency`: (harmonized frequency generated by DBnomics)
* provider_code * `provider_code`
* dataset_code * `dataset_code`
* dataset_name * `dataset_name`
* series_code * `series_code`
* series_name * `series_name`
* original_period: the period as returned by DBnomics * `original_period`: the `period` as returned by DBnomics
* period: the first day of original_period * `period`: the first day of `original_period`
* original_value (str or float): the observation value as returned by DBnomics, where not available values are represented by "NA" * `original_value` (`str` or `float`): the observation value as returned by DBnomics, where not available values are represented by `"NA"`
* value (float or NaN): the observation value as returned by DBnomics, where not available values are represented by NaN * `value` (`float` or `NaN`): the observation value as returned by DBnomics, where not available values are represented by `NaN`
Followed by dimensions columns, corresponding to the dimensions of the dataset: Followed by dimensions columns, corresponding to the dimensions of the dataset:
* dimensions labels: freq, unit, geo * dimensions labels: `freq`, `unit`, `geo`
* dimensions values labels: Frequency, Unit, Country * dimensions values labels: `Frequency`, `Unit`, `Country`
### Fetch two time series by ID ### Fetch two time series by ID
Again, let's assume that we know which series we want to download. Again, let's assume that we know which series we want to download.
We can reuse the fetch_series function, this time with two series codes. We can reuse the `fetch_series` function, this time with two series codes.
For example, to fetch the time series `EA19.1.0.0.0.ZUTN` and `DNK.1.0.0.0.ZUTN` from the For example, to fetch the time series `EA19.1.0.0.0.ZUTN` and `DNK.1.0.0.0.ZUTN` from the
[\"Unemployment rate\" [ZUTN] dataset](https://db.nomics.world/AMECO/ZUTN) [\"Unemployment rate\" [ZUTN] dataset](https://db.nomics.world/AMECO/ZUTN)
belonging to the [AMECO provider](https://db.nomics.world/AMECO): belonging to the [AMECO provider](https://db.nomics.world/AMECO).
Example:
>> df_ids = fetch_series('series_ids', ["AMECO/ZUTN/EA19.1.0.0.0.ZUTN", "AMECO/ZUTN/DNK.1.0.0.0.ZUTN"]); >> df_ids = fetch_series('series_ids', ["AMECO/ZUTN/EA19.1.0.0.0.ZUTN", "AMECO/ZUTN/DNK.1.0.0.0.ZUTN"]);
...@@ -109,9 +113,9 @@ It is not compatible with all the providers. In particular, only the providers f ...@@ -109,9 +113,9 @@ It is not compatible with all the providers. In particular, only the providers f
* WTO * WTO
Given 3 dimensions "frequency", "country" and "indicator", the user can select: Given 3 dimensions "frequency", "country" and "indicator", the user can select:
* one time series by giving its code: "M.FR.PCPIEC_IX" * one time series by giving its code: `"M.FR.PCPIEC_IX"`
* many series by enumerating dimensions codes: "M.FR+DE.PCPIEC_IX" is equivalent to ["M.FR.PCPIEC_IX", "M.DE.PCPIEC_IX"] * many series by enumerating dimensions codes: `"M.FR+DE.PCPIEC_IX"` is equivalent to `["M.FR.PCPIEC_IX", "M.DE.PCPIEC_IX"]`
* many series by skipping a dimension, repeating "." in the code mask: "M..PCPIEC_IX" is equivalent to ["M.country1.PCPIEC_IX", "M.country2.PCPIEC_IX", ..., "M.countryN.PCPIEC_IX"] * many series by skipping a dimension, repeating "." in the code mask: `"M..PCPIEC_IX"` is equivalent to `["M.country1.PCPIEC_IX", "M.country2.PCPIEC_IX", ..., "M.countryN.PCPIEC_IX"]`
Examples: Examples:
...@@ -123,27 +127,35 @@ Examples: ...@@ -123,27 +127,35 @@ Examples:
Searching by dimension is a less concise way to select time series than using the code mask, but it's universal: Searching by dimension is a less concise way to select time series than using the code mask, but it's universal:
some fetchers are not compatible with the code mask notation. The following example fetches many series from the some fetchers are not compatible with the code mask notation. The following example fetches many series from the
["Doing Business" [DB]](https://db.nomics.world/WB/DB) dataset of the [World Bank](https://db.nomics.world/WB) provider, selecting for time series about France, Italy and Spain (`country` dimension), ["Doing Business" [DB]](https://db.nomics.world/WB/DB) dataset of the [World Bank](https://db.nomics.world/WB) provider, selecting for time series about France, Italy and Spain (`country` dimension),
and the indicator "Procedures required to start a business - Women (number)" (`indicator` dimension): and the indicator "Procedures required to start a business - Women (number)" (`indicator` dimension).
Example:
>> df_dims = fetch_series('provider_code',"WB",'dataset_code',"DB", 'dimensions', '{"country":["ES","FR","IT"],"indicator":["IC.REG.COST.PC.FE.ZS.DRFN"]}'); >> df_dims = fetch_series('provider_code',"WB",'dataset_code',"DB", 'dimensions', '{"country":["ES","FR","IT"],"indicator":["IC.REG.COST.PC.FE.ZS.DRFN"]}');
### Fetch time series by API link ### Fetch time series by API link
When the dimensions, provider, dataset or series codes are unknown, the user can: When the dimensions, provider, dataset or series codes are unknown, the user can:
* go to the page of a dataset on DBnomics website, for example [Doing Business](https://db.nomics.world/WB/DB) * go to the page of a dataset on DBnomics website (eg: [Doing Business](https://db.nomics.world/WB/DB))
* select some dimensions by using the input widgets of the left column * select some dimensions by using the input widgets of the left column
* click on "Copy API link" in the menu of the "Download" button, * click on `Copy API link` in the menu of the `Download` button
* use the `fetch_series_by_api_link` function such as below * use the `fetch_series_by_api_link` function
Example:
>> df_link = fetch_series_by_api_link("https://api.db.nomics.world/v22/series/WB/DB?observations=1&dimensions=%7B%22country%22%3A%5B%22FR%22%2C%22IT%22%2C%22ES%22%5D%2C%22indicator%22%3A%5B%22IC.REG.COST.PC.FE.ZS.DRFN%22%5D%7D"); >> df_link = fetch_series_by_api_link('https://api.db.nomics.world/v22/series/WB/DB/ENF.CONT.COEN.ATDR-AE?observations=1');
### Fetch time series from the cart ### Fetch time series from the cart
On the [cart page](https://db.nomics.world/cart) of the DBnomics website, click on "Copy API link" and copy-paste it as an argument of the fetch_series_by_api_link function. On the [cart page](https://db.nomics.world/cart) of the DBnomics website, click on "Copy API link" and copy-paste it as an argument of the fetch_series_by_api_link function.
Please note that when you update your cart, you have to copy this link again, because the link itself contains the IDs of the series in the cart. Please note that when you update your cart, you have to copy this link again, because the link itself contains the IDs of the series in the cart.
>> df_cart = fetch_series_by_api_link("https://api.db.nomics.world/v22/series?series_ids=AMECO%2FZUTN%2FEA19.1.0.0.0.ZUTN&observations=1"); Example:
>> df_cart = fetch_series_by_api_link('https://api.db.nomics.world/v22/series?series_ids=AMECO%2FZUTN%2FEA19.1.0.0.0.ZUTN&observations=1');
### Fetch time series with different frequencies ### Fetch time series with different frequencies
Example:
>> df_multi_freq = fetch_series('series_ids', ["BEA/NIUnderlyingDetail-U001BC/S315-A",... >> df_multi_freq = fetch_series('series_ids', ["BEA/NIUnderlyingDetail-U001BC/S315-A",...
"BEA/NIUnderlyingDetail-U001BC/S315-Q",... "BEA/NIUnderlyingDetail-U001BC/S315-Q",...
"BEA/NIUnderlyingDetail-U001BC/S315-M"]); "BEA/NIUnderlyingDetail-U001BC/S315-M"]);
...@@ -153,13 +165,15 @@ The routines can interact with the [Time Series Editor](https://editor.nomics.wo ...@@ -153,13 +165,15 @@ The routines can interact with the [Time Series Editor](https://editor.nomics.wo
Available filters are listed on the [filters page](https://editor.nomics.world/filters). Available filters are listed on the [filters page](https://editor.nomics.world/filters).
The Time Series Editor is usable via a web interface ([example with AMECO/ZUTN/EA19.1.0.0.0.ZUTN](https://editor.nomics.world/series?source=dbnomics&series_id=AMECO/ZUTN/EA19.1.0.0.0.ZUTN)) The Time Series Editor is usable via a web interface ([example with AMECO/ZUTN/EA19.1.0.0.0.ZUTN](https://editor.nomics.world/series?source=dbnomics&series_id=AMECO/ZUTN/EA19.1.0.0.0.ZUTN))
but you can call it directly from MATLAB. The user is also able to chain many filters. but you can call it directly from MATLAB. The user is also able to chain many filters.
Here is an example of how to interpolate two annual time series with a monthly frequency, using a spline interpolation: Here is an example of how to interpolate two annual time series with a monthly frequency, using a spline interpolation.
Example:
>> filters_ = '[{"code": "interpolate", "parameters": {"frequency": "monthly", "method": "spline"}}]'; >> filters_ = '[{"code": "interpolate", "parameters": {"frequency": "monthly", "method": "spline"}}]';
>> df_filter = fetch_series('series_ids', "AMECO/ZUTN/EA19.1.0.0.0.ZUTN",'dbnomics_filters', filters_); >> df_filter = fetch_series('series_ids', "AMECO/ZUTN/EA19.1.0.0.0.ZUTN",'dbnomics_filters', filters_);
The first row of the final cell array changes when filters are used: The first row of the final cell array changes when filters are used:
* period_middle_day: the middle day of original_period (can be useful when you compare graphically interpolated series and original ones) * `period_middle_day`: the middle day of `original_period` (can be useful when you compare graphically interpolated series and original ones)
* filtered (bool): True if the series is filtered * `filtered` (`bool`): True if the series is filtered
* series_code: same as before for original series, but the suffix _filtered is added for filtered series * `series_code`: same as before for original series, but the suffix `_filtered` is added for filtered series
* series_name: same as before for original series, but the suffix (filtered) is added for filtered series * `series_name`: same as before for original series, but the suffix `(filtered)` is added for filtered series
\ No newline at end of file \ No newline at end of file
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment