Skip to content

Add JSDoc comments to data generation scripts and output files #230

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
fershad merged 6 commits into from
Oct 23, 2024
Merged

Add JSDoc comments to data generation scripts and output files #230

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
eb4e9ff
Add JsDoc comments to generate_average_co2
Malay-dev Oct 12, 2024
29b6755
Add JsDoc comments to generate_marginal_co2
Malay-dev Oct 12, 2024
6b000a0
Add JsDoc comments to average-intensities
Malay-dev Oct 12, 2024
5e58971
Add JsDoc comments to marginal-intensities-2021
Malay-dev Oct 12, 2024
cab18cf
add comments about constants in source files
fershad Oct 23, 2024
21a1a25
add comments to output of generators
fershad Oct 23, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
89 changes: 73 additions & 16 deletions data/functions/generate_average_co2.js
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,16 +1,43 @@
/**
* @fileoverview This script generates average CO2 emissions intensity data for countries using the Ember API.
* It processes the data and saves it in various formats for use in the CO2.js library.
* @author Chris Adams
* @version 1.0.0
*/

const fs = require("fs");

// This URL from Ember returns ALL the data for the country_overview_yearly table
/**
* The URL for the Ember API that provides country overview data on a yearly basis.
* @constant {string}
*/
const sourceURL =
"https://ember-data-api-scg3n.ondigitalocean.app/ember/country_overview_yearly.json?_sort=rowid&_shape=array";

/**
* Object to store the grid intensity results for each country.
* @type {Object.<string, number>}
*/
const gridIntensityResults = {};

/**
* Object to store general results including additional country information.
* @type {Object.<string, Object>}
*/
const generalResults = {};

/**
* The type of intensity data being processed (average or marginal).
* @constant {string}
*/
const type = "average";

/**
* This function generates the average CO2 emissions data for each country.
* It reads the data from the Ember API and saves it in the data/output folder.
* It also saves the data as a minified file in the src/data folder, so that it can be imported into the library.
* Fetches data from the Ember API, processes it to extract the latest average CO2 emissions
* intensity data for each country, and saves the results in various formats.
* @async
* @function
* @returns {Promise<void>}
*/

// Use async/await
Expand All @@ -27,7 +54,10 @@ const type = "average";
const response = await fetch(sourceURL);
const data = await response.json();

// Group data by country_code
/**
* Groups the API data by country code.
* @type {Object.<string, Array>}
*/
const groupedData = await data.reduce((acc, item) => {
const key =
item.country_code === "" ? item.country_or_region : item.country_code;
Expand All @@ -38,7 +68,10 @@ const type = "average";
return acc;
}, {});

// Loop through the grouped data and find the latest year
/**
* Extracts the latest year's data for each country.
* @type {Object.<string, Object>}
*/
const latestData = await Object.keys(groupedData).reduce((acc, key) => {
// Find the last year in the array with emissions intensity data
const latestYear = groupedData[key].reduce((acc, item, index) => {
Expand Down Expand Up @@ -79,24 +112,48 @@ const type = "average";
};
});

// This saves the country code and emissions data only, for use in the CO2.js library
const jsDocComments = `/**
* @fileoverview Minified average CO2 emissions intensity data for countries.
* @generated Generated by generate_average_co2.js
* @version 1.0.0
*/

/**
* @constant {Object.<string, number>} data - Average CO2 emissions intensity data for various countries.
* @constant {string} type - Type of data being represented.
*/`;

/**
* Saves the country code and emissions data for use in the CO2.js library.
* @type {void}
*/
fs.writeFileSync(
"data/output/average-intensities.js",
`const data = ${JSON.stringify(gridIntensityResults, null, " ")};
const type = "${type}";
export { data, type };
export default { data, type };
`
`
const data = ${JSON.stringify(gridIntensityResults, null, " ")};
const type = "${type}";
export { data, type };
export default { data, type };
`
);
// Save a minified version to the src folder so that it can be easily imported into the library
/**
* Saves a minified version of the data for easy import into the library.
* @type {void}
*/
fs.writeFileSync(
"src/data/average-intensities.min.js",
`const data = ${JSON.stringify(gridIntensityResults)}; const type = "${type}"; export { data, type }; export default { data, type };`
`${jsDocComments}
const data = ${JSON.stringify(
gridIntensityResults
)}; const type = "${type}"; export { data, type }; export default { data, type };`
);

// This saves the full data set as a JSON file for reference.
/**
* Saves the full data set as a JSON file for reference.
* @type {void}
*/
fs.writeFileSync(
"data/output/average-intensities.json",
JSON.stringify(generalResults, null, " ")
);
})();
})();
92 changes: 83 additions & 9 deletions data/functions/generate_marginal_co2.js
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,17 +1,66 @@
/**
* @fileoverview This script generates marginal CO2 emissions intensity data for countries using UNFCCC data.
* It processes the data from a CSV file and saves it in various formats for use in the CO2.js library.
* @author Chris Adams
* @version 1.0.0
*/

const fs = require("fs");

/**
* Reads the UNFCCC CSV file containing grid factors data.
* @type {Buffer}
*/
const csv = fs.readFileSync(
"data/IFI_Default_Grid_Factors_2021_v3.1_unfccc.csv"
);

/**
* Utility function to parse CSV rows.
* @type {function}
*/
const parseCSVRow = require("../utils/parseCSVRow");

/**
* Utility function to get country codes.
* @type {function}
*/
const getCountryCodes = require("../utils/getCountryCodes");

/**
* The type of intensity data being processed (marginal).
* @constant {string}
*/
const type = "marginal";

/**
* The source of the data (UNFCCC).
* @constant {string}
*/
const source = "UNFCCC";

/**
* The year of the data.
* @constant {string}
*/
const year = "2021";

/**
* Converts the CSV data to an array of strings, each representing a row.
* @type {string[]}
*/
const array = csv.toString().split("\n");

/* Store the converted result into an array */
/**
* Object to store the converted CSV data.
* @type {Object.<string, Object>}
*/
const csvToJsonResult = {};

/**
* Object to store the grid intensity results for each country.
* @type {Object.<string, string>}
*/
const gridIntensityResults = {};

/* Store the CSV column headers into seprate variable */
Expand Down Expand Up @@ -79,20 +128,45 @@ for (let currentArrayString of array.slice(5)) {
const json = JSON.stringify(csvToJsonResult);
const gridIntensityJson = JSON.stringify(gridIntensityResults);

// This saves the country code and emissions data only, for use in the CO2.js library
const jsDocComments = `/**
* @fileoverview Minified marginal CO2 emissions intensity data for countries (2021).
* @generated Generated by generate_marginal_co2.js
* @version 1.0.0
*/

/**
* @constant {Object.<string, number>} data - Average CO2 emissions intensity data for various countries.
* @constant {string} type - Type of data being represented.
* @constant {string} year - Year for which the data was collected.
*/`;

/**
* Saves the country code and emissions data for use in the CO2.js library.
* @type {void}
*/
fs.writeFileSync(
"data/output/marginal-intensities-2021.js",
`const data = ${gridIntensityJson};
`
const data = ${gridIntensityJson};
const type = "${type}";
const year = "${year}";
export { data, type, year };
export default { data, type, year };`
const year = "${year}";
export { data, type, year };
export default { data, type, year };
`
);
// Save a minified version to the src folder so that it can be easily imported into the library

/**
* Saves a minified version of the data for easy import into the library.
* @type {void}
*/
fs.writeFileSync(
"src/data/marginal-intensities-2021.min.js",
`const data = ${gridIntensityJson}; const type = "${type}"; const year = "${year}"; export { data, type, year }; export default { data, type, year };`
`${jsDocComments}
const data = ${gridIntensityJson}; const type = "${type}"; const year = "${year}"; export { data, type, year }; export default { data, type, year };`
);

// This saves the full data set as a JSON file for reference.
/**
* Saves the full data set as a JSON file for reference.
* @type {void}
*/
fs.writeFileSync("data/output/marginal-intensities-2021.json", json);
10 changes: 10 additions & 0 deletions src/data/average-intensities.min.js
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

11 changes: 11 additions & 0 deletions src/data/marginal-intensities-2021.min.js
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.