Commit 930be7b1 authored by Dóra Kocsis's avatar Dóra Kocsis

cosmetics to README.md

parent c217ce99
......@@ -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.
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)
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");
......@@ -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:
* x_frequency: (harmonized frequency generated by DBnomics)
* provider_code
* dataset_code
* dataset_name
* series_code
* series_name
* original_period: the period as returned by DBnomics
* 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"
* value (float or NaN): the observation value as returned by DBnomics, where not available values are represented by NaN
* `x_frequency`: (harmonized frequency generated by DBnomics)
* `provider_code`
* `dataset_code`
* `dataset_name`
* `series_code`
* `series_name`
* `original_period`: the `period` as returned by DBnomics
* `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"`
* `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:
* dimensions labels: freq, unit, geo
* dimensions values labels: Frequency, Unit, Country
* dimensions labels: `freq`, `unit`, `geo`
* dimensions values labels: `Frequency`, `Unit`, `Country`
### Fetch two time series by ID
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
[\"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"]);
......@@ -109,9 +113,9 @@ It is not compatible with all the providers. In particular, only the providers f
* WTO
Given 3 dimensions "frequency", "country" and "indicator", the user can select:
* 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 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"]
* 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 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:
......@@ -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:
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),
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"]}');
### Fetch time series by API link
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)
When the dimensions, provider, dataset or series codes are unknown, the user can:
* 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
* click on "Copy API link" in the menu of the "Download" button,
* use the `fetch_series_by_api_link` function such as below
* click on `Copy API link` in the menu of the `Download` button
* 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
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.
>> 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
Example:
>> df_multi_freq = fetch_series('series_ids', ["BEA/NIUnderlyingDetail-U001BC/S315-A",...
"BEA/NIUnderlyingDetail-U001BC/S315-Q",...
"BEA/NIUnderlyingDetail-U001BC/S315-M"]);
......@@ -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).
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.
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"}}]';
>> 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:
* 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
* 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
\ No newline at end of file
* `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
* `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
\ No newline at end of file
Markdown is supported
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