@iiasa/ixmp4-ts 0.5.0 → 0.7.0

package/dist/cjs/core/utils.js

@@ -1,6 +1,14 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.toIamcWide = exports.dfToDimensionless = exports.unitToDimensionless = exports.substitudeType = void 0;
+exports.substitudeType = substitudeType;
+exports.unitToDimensionless = unitToDimensionless;
+exports.dfToDimensionless = dfToDimensionless;
+exports.standardizeIamcDf = standardizeIamcDf;
+exports.toIamcWide = toIamcWide;
+exports.withIamcDefault = withIamcDefault;
+exports.getIamcRowIndex = getIamcRowIndex;
+exports.sortTimesWithYearFirst = sortTimesWithYearFirst;
+exports.splitDataFrameByType = splitDataFrameByType;
 const dataframe_1 = require("../dataframe");
 const datapoint_1 = require("../data/iamc/datapoint");
 function substitudeType(df, type) {
@@ -23,91 +31,236 @@ function substitudeType(df, type) {
     }
     return df;
 }
-exports.substitudeType = substitudeType;
 function unitToDimensionless(name) {
     if (name === 'dimensionless') {
         throw new Error("Unit name 'dimensionless' is reserved, use an empty string '' instead.");
     }
     return name === '' ? 'dimensionless' : name;
 }
-exports.unitToDimensionless = unitToDimensionless;
 function dfToDimensionless(df) {
     if (df
         .loc({ columns: ['unit'] })
-        .values.map(toString)
+        .values.map(String)
         .includes('dimensionless')) {
         throw new Error("Unit name 'dimensionless' is reserved, use an empty string '' instead.");
     }
     df.replaceValue('', 'dimensionless', 'unit');
     return df;
 }
-exports.dfToDimensionless = dfToDimensionless;
+/**
+ * Standardizes the columns of a DataFrame in IAMC format.
+ * @param df DataFrame in IAMC format
+ * @returns DataFrame in IAMC format with standardized columns
+ */
+function standardizeIamcDf(df) {
+    if (df.columns.includes('time_series__id')) {
+        df = df.dropColumns(['time_series__id']);
+    }
+    if (df.columns.includes('unit')) {
+        df = df.replaceValue('dimensionless', ' ', 'unit');
+    }
+    // Rename step_category to subannual
+    if (df.columns.includes('step_category')) {
+        df = df.renameColumns({ step_category: 'subannual' });
+    }
+    return df;
+}
+/**
+ * Converts a DataFrame in IAMC long format to wide format.
+ * @param df The DataFrame to convert
+ * @returns A DataFrame in IAMC wide format
+ */
 function toIamcWide(df) {
-    // cannot convert empty dataframe to wide format
+    // empty df: drop long-format columns if present
     if (df.shape[0] === 0) {
-        // drop columns of iamc long format if present
-        if (df.columns.includes('step_year')) {
-            df = df.dropColumns(['step_year']);
-        }
-        if (df.columns.includes('value')) {
-            df = df.dropColumns(['value']);
-        }
-        return df;
-    }
-    // TODO make this work for other types than ANNUAL as well
-    const types = df.columnValues('type');
-    if (types.some((type) => type !== 'ANNUAL')) {
-        throw new Error('Only ANNUAL data is supported for conversion to wide format');
-    }
-    const allYears = [...new Set(df.columnValues('step_year'))];
-    allYears.sort();
-    const stepYearIndex = df.columns.indexOf('step_year');
-    const valueIndex = df.columns.indexOf('value');
-    const newColumnsIndices = df.columns
+        const longCols = [
+            'step_year',
+            'step_datetime',
+            'step_category',
+            'subannual',
+            'value',
+        ];
+        const toDrop = longCols.filter((c) => df.columns.includes(c));
+        return toDrop.length ? df.dropColumns(toDrop) : df;
+    }
+    // column index map
+    const colIdx = Object.fromEntries(df.columns.map((c, i) => [c, i]));
+    // collect unique, non-null times
+    const uniqueNonNull = (arr) => [...new Set(arr.filter((v) => v !== null && v !== undefined))];
+    const years = df.columns.includes('step_year')
+        ? uniqueNonNull(df.columnValues('step_year')).sort((a, b) => a - b)
+        : [];
+    const datetimes = df.columns.includes('step_datetime')
+        ? uniqueNonNull(df.columnValues('step_datetime')).sort()
+        : [];
+    const allTimes = sortTimesWithYearFirst(years, datetimes);
+    // indices to carry over (everything but time and value)
+    const takeOverIdx = df.columns
         .map((_, i) => i)
-        .filter((i) => i !== stepYearIndex && i !== valueIndex);
-    const columns = [];
-    const dtypes = [];
-    for (const index of newColumnsIndices) {
-        columns.push(df.columns[index]);
-        dtypes.push(df.dtypes[index]);
-    }
-    const yearColumnsIndex = new Map();
-    for (const year of allYears) {
-        columns.push(year.toString());
+        .filter((i) => {
+        var _a, _b, _c;
+        return i !== ((_a = colIdx['step_year']) !== null && _a !== void 0 ? _a : -1) &&
+            i !== ((_b = colIdx['step_datetime']) !== null && _b !== void 0 ? _b : -1) &&
+            i !== ((_c = colIdx['value']) !== null && _c !== void 0 ? _c : -1);
+    });
+    // base schema (carry-over columns + dtypes)
+    const columns = takeOverIdx.map((i) => df.columns[i]);
+    const dtypes = takeOverIdx.map((i) => df.dtypes[i]);
+    // add time columns
+    const yearColIdx = new Map();
+    const dtColIdx = new Map();
+    for (const time of allTimes) {
+        columns.push(String(time));
         dtypes.push(dataframe_1.DType.FLOAT32);
-        yearColumnsIndex.set(year, columns.length - 1);
+        const newIdx = columns.length - 1;
+        if (typeof time === 'number')
+            yearColIdx.set(time, newIdx);
+        else
+            dtColIdx.set(time, newIdx);
     }
-    const rowIdentifiers = [
+    // row identifiers: prefer step_category, fall back to subannual if present
+    const stepCategoryCol = df.columns.includes('step_category')
+        ? 'step_category'
+        : df.columns.includes('subannual')
+            ? 'subannual'
+            : undefined;
+    const idCols = [
         'model',
         'scenario',
         'version',
         'region',
         'variable',
         'unit',
-    ].map((col) => df.columns.indexOf(col));
+        'type',
+        stepCategoryCol,
+    ].filter(Boolean);
+    const idIdxs = idCols.map((c) => colIdx[c]);
+    // data mapping
     const dataMap = new Map();
-    for (const row of df.values) {
-        const index = getIamcRowIndex(row, rowIdentifiers);
-        if (dataMap.has(index)) {
-            dataMap.get(index)[yearColumnsIndex.get(row[stepYearIndex])] =
-                row[valueIndex];
+    const yearIdx = colIdx['step_year'];
+    const dtIdx = colIdx['step_datetime'];
+    const valueIdx = colIdx['value'];
+    for (const dfRow of df.values) {
+        const key = getIamcRowIndex(dfRow, idIdxs);
+        let wideRow = dataMap.get(key);
+        if (!wideRow) {
+            wideRow = takeOverIdx
+                .map((i) => dfRow[i])
+                .concat(Array(allTimes.length).fill(null));
+            dataMap.set(key, wideRow);
         }
-        else {
-            const wideRow = row
-                .filter((_, i) => newColumnsIndices.includes(i))
-                .concat(new Array(allYears.length).fill(null));
-            wideRow[yearColumnsIndex.get(row[stepYearIndex])] = row[valueIndex];
-            dataMap.set(index, wideRow);
+        const year = yearIdx !== undefined ? dfRow[yearIdx] : undefined;
+        const dt = dtIdx !== undefined ? dfRow[dtIdx] : undefined;
+        let targetIdx;
+        if (year !== undefined && year !== null)
+            targetIdx = yearColIdx.get(year);
+        else if (dt !== undefined && dt !== null)
+            targetIdx = dtColIdx.get(dt);
+        if (targetIdx !== undefined) {
+            wideRow[targetIdx] = dfRow[valueIdx];
         }
     }
-    const wideIamcData = [];
-    for (const wideRow of dataMap.values()) {
-        wideIamcData.push(wideRow);
-    }
+    const wideIamcData = Array.from(dataMap.values());
     return new dataframe_1.DataFrame(wideIamcData, { columns, dtypes });
 }
-exports.toIamcWide = toIamcWide;
+/**
+ * Generates a unique row index for IAMC data based on the row's identifiers.
+ * @param row The row data as an array
+ * @param rowIdentifiers The indices of the identifiers in the row
+ * @returns A string that uniquely identifies the row
+ */
 function getIamcRowIndex(row, rowIdentifiers) {
     return rowIdentifiers.map((i) => row[i]).join('_');
 }
+/**
+ * Processes the filter to ensure that IAMC filter is enabled by default unless explicitly disabled.
+ * When enabled, only entities with associated datapoints are returned.
+ * @param filter The filter to process
+ * @returns The processed filter with IAMC default settings
+ */
+function withIamcDefault(filter) {
+    if (!filter) {
+        return { iamc: true };
+    }
+    else if (filter.iamc === undefined) {
+        // If the IAMC filter is not explicitly set, default to true
+        filter.iamc = true;
+    }
+    else if (filter.iamc === null) {
+        // If the IAMC filter is explicitly set to null, leave it as is
+        return filter;
+    }
+    return filter;
+}
+function sortTimesWithYearFirst(years, dateTimes) {
+    // Create a combined array with type information
+    const combined = [];
+    // Add years with their metadata
+    for (const year of years) {
+        combined.push({ value: year, isYear: true, year });
+    }
+    // Add datetimes with their extracted year
+    for (const dateTime of dateTimes) {
+        // Extract year from datetime string (format: 2005-03-01T01:00:00)
+        const year = parseInt(dateTime.substring(0, 4), 10);
+        combined.push({ value: dateTime, isYear: false, year });
+    }
+    // Sort by year first, then by type (years before datetimes), then by value
+    combined.sort((a, b) => {
+        // First sort by year
+        if (a.year !== b.year) {
+            return a.year - b.year;
+        }
+        // Within the same year, years come before datetimes
+        if (a.isYear && !b.isYear) {
+            return -1;
+        }
+        if (!a.isYear && b.isYear) {
+            return 1;
+        }
+        // If both are the same type, sort by value
+        if (a.value < b.value) {
+            return -1;
+        }
+        if (a.value > b.value) {
+            return 1;
+        }
+        return 0;
+    });
+    // Return just the values
+    return combined.map((item) => item.value);
+}
+/**
+ * Splits a DataFrame into separate DataFrames based on DataPointType.
+ * @param df The DataFrame to split
+ * @returns An object containing DataFrames for each type present in the data
+ */
+function splitDataFrameByType(df) {
+    const result = {};
+    // If no type column exists, return the original dataframe as annual
+    if (!df.columns.includes('type')) {
+        result.annual = df;
+        return result;
+    }
+    // Get unique types in the dataframe
+    const typeValues = df.columnValues('type');
+    const uniqueTypes = [...new Set(typeValues)];
+    // Filter dataframe for each type present
+    for (const type of uniqueTypes) {
+        const filteredDf = df.query({
+            conditions: { column: 'type', predicate: (value) => value === type },
+        });
+        switch (type) {
+            case datapoint_1.DataPointType.ANNUAL:
+                result.annual = filteredDf;
+                break;
+            case datapoint_1.DataPointType.CATEGORICAL:
+                result.categorical = filteredDf;
+                break;
+            case datapoint_1.DataPointType.DATETIME:
+                result.datetime = filteredDf;
+                break;
+        }
+    }
+    return result;
+}

package/dist/cjs/data/base.js

@@ -26,8 +26,8 @@ class BaseRepository {
         this.enumerationMethod = (_a = this.constructor.enumerationMethod) !== null && _a !== void 0 ? _a : 'PATCH';
     }
     _request(url, method, params, body) {
-        var _a;
         return __awaiter(this, void 0, void 0, function* () {
+            var _a;
             const config = {};
             config.url = url;
             config.method = method;
@@ -80,8 +80,8 @@ class BaseRepository {
     /**
      * Convenience method for requests to the enumeration endpoint.
      */
-    _requestEnumeration(params = {}, body = {}, table = false) {
-        return __awaiter(this, void 0, void 0, function* () {
+    _requestEnumeration() {
+        return __awaiter(this, arguments, void 0, function* (params = {}, body = {}, table = false) {
             params = (0, utils_1.convertToSnakeCase)(params);
             if (body !== undefined && Object.keys(body).length === 0) {
                 body = undefined;
@@ -116,8 +116,12 @@ class BaseRepository {
             }
         });
     }
-    _list({ filter, params, }) {
-        return __awaiter(this, void 0, void 0, function* () {
+    _list(_a) {
+        return __awaiter(this, arguments, void 0, function* ({ filter, params, }) {
+            if (this.enumerationMethod === 'GET') {
+                params = Object.assign(Object.assign({}, params), filter);
+                filter = undefined;
+            }
             const data = yield this._requestEnumeration(params, filter, false);
             const pagination = data.pagination;
             if (pagination !== undefined) {
@@ -129,8 +133,8 @@ class BaseRepository {
             }
         });
     }
-    _tabulate({ filter, params, }) {
-        return __awaiter(this, void 0, void 0, function* () {
+    _tabulate(_a) {
+        return __awaiter(this, arguments, void 0, function* ({ filter, params, }) {
             // TODO: test what happens if we get a number that cannot be represented as float32 (or int32)
             const data = yield this._requestEnumeration(params, filter, true);
             const pagination = data.pagination;
@@ -152,6 +156,24 @@ class BaseRepository {
             }
         });
     }
+    _count(_a) {
+        return __awaiter(this, arguments, void 0, function* ({ filter, params, }) {
+            if (this.enumerationMethod === 'GET') {
+                params = Object.assign(Object.assign(Object.assign({}, params), filter), { limit: 0 });
+                filter = undefined;
+            }
+            else {
+                params = Object.assign(Object.assign({}, params), { limit: 0 });
+            }
+            const data = yield this._requestEnumeration(params, filter, true);
+            if (data === undefined || data.total === undefined) {
+                throw new exceptions_1.UnknownApiError({
+                    message: 'Count result does not contain total count.',
+                });
+            }
+            return data.total;
+        });
+    }
     _bulkUpsert(df, params) {
         return __awaiter(this, void 0, void 0, function* () {
             return yield this._request(`${this.prefix}bulk/`, 'POST', params, (0, utils_1.dfToJson)(df));

package/dist/cjs/data/docs.js

@@ -14,7 +14,7 @@ const base_1 = require("./base");
 class DocsRepository extends base_1.BaseRepository {
     get(dimensionId) {
         return __awaiter(this, void 0, void 0, function* () {
-            return yield this._get({ dimension_id: dimensionId });
+            return yield this._get({ dimensionId });
         });
     }
     set(dimensionId, description) {
@@ -27,7 +27,7 @@ class DocsRepository extends base_1.BaseRepository {
     }
     list(dimensionId) {
         return __awaiter(this, void 0, void 0, function* () {
-            return yield this._list({ filter: { dimension_id: dimensionId } });
+            return yield this._list({ filter: { dimensionId } });
         });
     }
     delete(dimensionId) {

package/dist/cjs/data/iamc/datapoint.js

@@ -18,23 +18,23 @@ var DataPointType;
     DataPointType["DATETIME"] = "DATETIME";
 })(DataPointType || (exports.DataPointType = DataPointType = {}));
 class DataPointRepository extends base_1.BaseRepository {
-    list({ joinParameters = false, filter = {}, } = {
-        joinParameters: false,
-        filter: {},
-    }) {
-        return __awaiter(this, void 0, void 0, function* () {
+    list() {
+        return __awaiter(this, arguments, void 0, function* ({ joinParameters = false, filter = {}, } = {
+            joinParameters: false,
+            filter: {},
+        }) {
             return (yield this._list({
                 filter,
                 params: { joinParameters },
             }));
         });
     }
-    tabulate({ joinParameters = false, joinRuns = false, filter = {}, } = {
-        joinParameters: false,
-        joinRuns: false,
-        filter: {},
-    }) {
-        return __awaiter(this, void 0, void 0, function* () {
+    tabulate() {
+        return __awaiter(this, arguments, void 0, function* ({ joinParameters = false, joinRuns = false, filter = {}, } = {
+            joinParameters: false,
+            joinRuns: false,
+            filter: {},
+        }) {
             return yield this._tabulate({
                 filter,
                 params: {
@@ -44,6 +44,13 @@ class DataPointRepository extends base_1.BaseRepository {
             });
         });
     }
+    count() {
+        return __awaiter(this, arguments, void 0, function* (filter = {}) {
+            return yield this._count({
+                filter,
+            });
+        });
+    }
     bulkUpsert(df) {
         return __awaiter(this, void 0, void 0, function* () {
             yield this._bulkUpsert(df);

package/dist/cjs/data/iamc/timeseries.js

@@ -49,30 +49,30 @@ class TimeSeriesRepository extends base_1.BaseRepository {
             }
         });
     }
-    list({ joinParameters = false, filter = {}, } = {
-        joinParameters: false,
-        filter: {},
-    }) {
-        return __awaiter(this, void 0, void 0, function* () {
+    list() {
+        return __awaiter(this, arguments, void 0, function* ({ joinParameters = false, filter = {}, } = {
+            joinParameters: false,
+            filter: {},
+        }) {
             return (yield this._list({
                 filter,
                 params: { joinParameters },
             }));
         });
     }
-    tabulate({ joinParameters = false, filter = {}, } = {
-        joinParameters: false,
-        filter: {},
-    }) {
-        return __awaiter(this, void 0, void 0, function* () {
+    tabulate() {
+        return __awaiter(this, arguments, void 0, function* ({ joinParameters = false, filter = {}, } = {
+            joinParameters: false,
+            filter: {},
+        }) {
             return yield this._tabulate({
                 filter,
                 params: { joinParameters },
             });
         });
     }
-    bulkUpsert(df, createRelated = false) {
-        return __awaiter(this, void 0, void 0, function* () {
+    bulkUpsert(df_1) {
+        return __awaiter(this, arguments, void 0, function* (df, createRelated = false) {
             yield this._bulkUpsert(df, { create_related: createRelated });
         });
     }

package/dist/cjs/data/iamc/variable.js

@@ -17,16 +17,21 @@ class VariableRepository extends base_1.BaseRepository {
         super(client);
         this.docs = new docs_1.DocsRepository(client, 'docs/iamc/variables/');
     }
-    list(filter = {}) {
-        return __awaiter(this, void 0, void 0, function* () {
+    list() {
+        return __awaiter(this, arguments, void 0, function* (filter = {}) {
             return yield this._list({ filter });
         });
     }
-    tabulate(filter = {}) {
-        return __awaiter(this, void 0, void 0, function* () {
+    tabulate() {
+        return __awaiter(this, arguments, void 0, function* (filter = {}) {
             return yield this._tabulate({ filter });
         });
     }
+    count() {
+        return __awaiter(this, arguments, void 0, function* (filter = {}) {
+            return yield this._count({ filter });
+        });
+    }
     create(name) {
         return __awaiter(this, void 0, void 0, function* () {
             return yield this._post({ name });

package/dist/cjs/data/meta.js

@@ -19,16 +19,21 @@ var MetaIndicatorType;
     MetaIndicatorType["BOOL"] = "BOOL";
 })(MetaIndicatorType || (MetaIndicatorType = {}));
 class MetaIndicatorRepository extends base_1.BaseRepository {
-    list(filter = {}) {
-        return __awaiter(this, void 0, void 0, function* () {
+    list() {
+        return __awaiter(this, arguments, void 0, function* (filter = {}) {
             return yield this._list(filter);
         });
     }
-    tabulate(filter = {}, joinRunIndex) {
-        return __awaiter(this, void 0, void 0, function* () {
+    tabulate() {
+        return __awaiter(this, arguments, void 0, function* (filter = {}, joinRunIndex) {
             return yield this._tabulate({ filter, params: { joinRunIndex } });
         });
     }
+    count() {
+        return __awaiter(this, arguments, void 0, function* (filter = {}) {
+            return yield this._count({ filter });
+        });
+    }
     create(run__id, key, value) {
         return __awaiter(this, void 0, void 0, function* () {
             const res = yield this._post({

package/dist/cjs/data/model.js

@@ -17,16 +17,21 @@ class ModelRepository extends base_1.BaseRepository {
         super(client);
         this.docs = new docs_1.DocsRepository(client, 'docs/models/');
     }
-    list(filter = {}) {
-        return __awaiter(this, void 0, void 0, function* () {
+    list() {
+        return __awaiter(this, arguments, void 0, function* (filter = {}) {
             return yield this._list({ filter });
         });
     }
-    tabulate(filter = {}) {
-        return __awaiter(this, void 0, void 0, function* () {
+    tabulate() {
+        return __awaiter(this, arguments, void 0, function* (filter = {}) {
             return yield this._tabulate({ filter });
         });
     }
+    count() {
+        return __awaiter(this, arguments, void 0, function* (filter = {}) {
+            return yield this._count({ filter });
+        });
+    }
     create(name) {
         return __awaiter(this, void 0, void 0, function* () {
             const res = yield this._post({ name });

package/dist/cjs/data/region.js

@@ -17,17 +17,22 @@ class RegionRepository extends base_1.BaseRepository {
         super(client);
         this.docs = new docs_1.DocsRepository(client, 'docs/regions/');
     }
-    list(filter = {}) {
-        return __awaiter(this, void 0, void 0, function* () {
+    list() {
+        return __awaiter(this, arguments, void 0, function* (filter = {}) {
             const Regions = yield this._list({ filter });
             return Regions;
         });
     }
-    tabulate(filter = {}) {
-        return __awaiter(this, void 0, void 0, function* () {
+    tabulate() {
+        return __awaiter(this, arguments, void 0, function* (filter = {}) {
             return yield this._tabulate({ filter });
         });
     }
+    count() {
+        return __awaiter(this, arguments, void 0, function* (filter = {}) {
+            return yield this._count({ filter });
+        });
+    }
     create(name, hierarchy) {
         return __awaiter(this, void 0, void 0, function* () {
             const res = yield this._post({

package/dist/cjs/data/run.js

@@ -13,16 +13,21 @@ exports.RunRepository = void 0;
 const base_1 = require("./base");
 const exceptions_1 = require("../core/exceptions");
 class RunRepository extends base_1.BaseRepository {
-    list(filter = {}) {
-        return __awaiter(this, void 0, void 0, function* () {
+    list() {
+        return __awaiter(this, arguments, void 0, function* (filter = {}) {
             return yield this._list({ filter });
         });
     }
-    tabulate(filter = {}) {
-        return __awaiter(this, void 0, void 0, function* () {
+    tabulate() {
+        return __awaiter(this, arguments, void 0, function* (filter = {}) {
             return yield this._tabulate({ filter });
         });
     }
+    count() {
+        return __awaiter(this, arguments, void 0, function* (filter = {}) {
+            return yield this._count({ filter });
+        });
+    }
     create(modelName, scenarioName) {
         return __awaiter(this, void 0, void 0, function* () {
             const res = yield this._post({

package/dist/cjs/data/scenario.js

@@ -17,16 +17,21 @@ class ScenarioRepository extends base_1.BaseRepository {
         super(client);
         this.docs = new docs_1.DocsRepository(client, 'docs/scenarios/');
     }
-    list(filter = {}) {
-        return __awaiter(this, void 0, void 0, function* () {
+    list() {
+        return __awaiter(this, arguments, void 0, function* (filter = {}) {
             return (yield this._list({ filter }));
         });
     }
-    tabulate(filter = {}) {
-        return __awaiter(this, void 0, void 0, function* () {
+    tabulate() {
+        return __awaiter(this, arguments, void 0, function* (filter = {}) {
             return yield this._tabulate({ filter });
         });
     }
+    count() {
+        return __awaiter(this, arguments, void 0, function* (filter = {}) {
+            return yield this._count({ filter });
+        });
+    }
     create(name) {
         return __awaiter(this, void 0, void 0, function* () {
             return (yield this._post({ name }));