@nshiab/simple-data-analysis 5.19.8

package/esm/deps/jsr.io/@nshiab/journalism-dataviz/1.0.10/src/dataviz/helpers/prepChart.js

@@ -0,0 +1,156 @@
+import { max, min } from "d3-array";
+import getColors from "./getColors.js";
+import drawChart from "./drawChart.js";
+import validateDataTypes from "./validateDataTypes.js";
+import { formatDate, formatNumber } from "../../../../../journalism-format/1.1.5/src/index.js";
+export default function prepChart(type, data, x, y, drawFunction, options = {}) {
+    validateDataTypes(data, x, y);
+    const formatX = options.formatX
+        ? options.formatX
+        : data[0][x] instanceof Date
+            ? (d) => formatDate(d, "YYYY-MM-DD", { utc: true })
+            : function (d) {
+                return String(d);
+            };
+    const formatY = options.formatY
+        ? options.formatY
+        : (d) => formatNumber(d);
+    const width = options.width ?? 75;
+    const height = options.height ?? 15;
+    const smallMultiplesPerRow = options.smallMultiplesPerRow ?? 2;
+    const smallMultiples = options.smallMultiples ?? null;
+    const fixedScales = options.fixedScales ?? false;
+    if (typeof smallMultiples === "string") {
+        const categories = Array.from(new Set(data.map((d) => d[smallMultiples])));
+        const colors = getColors(categories);
+        const allLabelsX = [];
+        let xMin;
+        let xMax;
+        let yMin;
+        let yMax;
+        // min and max values for the whole data
+        if (fixedScales) {
+            const xValues = data.map((d) => {
+                const val = d[x];
+                return val instanceof Date ? val.getTime() : val;
+            });
+            xMin = min(xValues);
+            xMax = max(xValues);
+            const yValues = data.map((d) => d[y]);
+            yMin = min(yValues);
+            yMax = max(yValues);
+            if (xMin === undefined ||
+                xMax === undefined ||
+                yMin === undefined ||
+                yMax === undefined) {
+                throw new Error("The min or max value is undefined.");
+            }
+        }
+        if (data.length > Math.round(width / smallMultiplesPerRow)) {
+            if (type === "line") {
+                console.log("\x1b[2m\n/!\\ Number of values greater than width. Averaged values displayed.\x1b[0m");
+            }
+            else if (type === "dot") {
+                console.log("\x1b[2m\n/!\\ Number of values greater than width. Dots might overlap.\x1b[0m");
+            }
+        }
+        const allCharts = colors?.map((c) => {
+            const dataFiltered = data.filter((d) => d[smallMultiples] === c.category);
+            // The min and max values for each small multiple
+            if (!fixedScales) {
+                const xValues = dataFiltered.map((d) => {
+                    const val = d[x];
+                    return val instanceof Date ? val.getTime() : val;
+                });
+                xMin = min(xValues);
+                xMax = max(xValues);
+                const yValues = dataFiltered.map((d) => d[y]);
+                yMin = min(yValues);
+                yMax = max(yValues);
+            }
+            const { chart, xLabels } = drawChart(type, drawFunction, dataFiltered, x, y, c.color, {
+                title: c.category,
+                width: Math.round(width / smallMultiplesPerRow),
+                height: height,
+                formatX: formatX,
+                formatY: formatY,
+                xMin,
+                xMax,
+                yMin,
+                yMax,
+            });
+            allLabelsX.push(...xLabels);
+            return chart;
+        });
+        if (allCharts === undefined) {
+            throw new Error("No data to display.");
+        }
+        // Restructure the charts to make small multiples on multiple columns
+        const allChartsRows = [];
+        for (let i = 0; i < allCharts.length; i += smallMultiplesPerRow) {
+            const charts = allCharts.slice(i, i + smallMultiplesPerRow);
+            const combinedRows = [];
+            for (let j = 0; j < charts.length; j++) {
+                if (j === 0) {
+                    combinedRows.push(...charts[j]);
+                }
+                else {
+                    for (let k = 0; k < charts[j].length; k++) {
+                        combinedRows[k].push(" ".repeat(3), ...charts[j][k]);
+                    }
+                }
+            }
+            allChartsRows.push(...combinedRows);
+            allChartsRows.push(" ".repeat(combinedRows[0].length).split(""));
+        }
+        let chartString = allChartsRows.map((d) => d.join("")).join("\n");
+        const allLabelsXUnique = Array.from(new Set(allLabelsX));
+        for (let i = 0; i < allLabelsXUnique.length; i++) {
+            const regex = new RegExp(allLabelsXUnique[i], "g");
+            chartString = chartString.replace(regex, `\x1b[90m${allLabelsXUnique[i]}\x1b[0m`);
+        }
+        console.log(`\n${chartString}\n`);
+    }
+    else {
+        const xValues = data.map((d) => {
+            const val = d[x];
+            return val instanceof Date ? val.getTime() : val;
+        });
+        const xMin = min(xValues);
+        const xMax = max(xValues);
+        const yValues = data.map((d) => d[y]);
+        const yMin = min(yValues);
+        const yMax = max(yValues);
+        if (xMin === undefined ||
+            xMax === undefined ||
+            yMin === undefined ||
+            yMax === undefined) {
+            throw new Error("The min or max value is undefined.");
+        }
+        if (data.length > width) {
+            if (type === "line") {
+                console.log("\x1b[2m\n/!\\ Number of values greater than width. Averaged values displayed.\x1b[0m");
+            }
+            else if (type === "dot") {
+                console.log("\x1b[2m\n/!\\ Number of values greater than width. Dots might overlap.\x1b[0m");
+            }
+        }
+        const { chart, xLabels } = drawChart(type, drawFunction, data, x, y, "\x1b[38;5;208m", {
+            formatX: formatX,
+            formatY: formatY,
+            width: width,
+            height: height,
+            xMin,
+            xMax,
+            yMin,
+            yMax,
+        });
+        let chartString = chart.map((d) => d.join("")).join("\n");
+        const allLabelsXUnique = Array.from(new Set(xLabels));
+        for (let i = 0; i < allLabelsXUnique.length; i++) {
+            const regex = new RegExp(allLabelsXUnique[i], "g");
+            chartString = chartString.replace(regex, `\x1b[90m${allLabelsXUnique[i]}\x1b[0m`);
+        }
+        console.log(`${chartString}`);
+    }
+}

package/esm/deps/jsr.io/@nshiab/journalism-dataviz/1.0.10/src/dataviz/helpers/validateDataTypes.d.ts

@@ -0,0 +1,4 @@
+export default function validateDataTypes(data: {
+    [key: string]: unknown;
+}[], x: string, y: string): void;
+//# sourceMappingURL=validateDataTypes.d.ts.map

package/esm/deps/jsr.io/@nshiab/journalism-dataviz/1.0.10/src/dataviz/helpers/validateDataTypes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validateDataTypes.d.ts","sourceRoot":"","sources":["../../../../../../../../../src/deps/jsr.io/@nshiab/journalism-dataviz/1.0.10/src/dataviz/helpers/validateDataTypes.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,OAAO,UAAU,iBAAiB,CACvC,IAAI,EAAE;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CAAE,EAAE,EAClC,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,MAAM,QAsCV"}

package/esm/deps/jsr.io/@nshiab/journalism-dataviz/1.0.10/src/dataviz/helpers/validateDataTypes.js

@@ -0,0 +1,27 @@
+export default function validateDataTypes(data, x, y) {
+    if (data.length === 0) {
+        throw new Error("Data array is empty.");
+    }
+    // Check all rows to validate data types
+    for (let i = 0; i < data.length; i++) {
+        const row = data[i];
+        // Validate x values
+        const xValue = row[x];
+        if (xValue === undefined || xValue === null) {
+            throw new Error(`Row ${i}: x-axis value "${x}" is undefined or null.`);
+        }
+        const isValidX = typeof xValue === "number" || xValue instanceof Date;
+        if (!isValidX) {
+            throw new Error(`Row ${i}: x-axis value "${x}" must be a number or Date. Got: ${typeof xValue} (${xValue})`);
+        }
+        // Validate y values
+        const yValue = row[y];
+        if (yValue === undefined || yValue === null) {
+            throw new Error(`Row ${i}: y-axis value "${y}" is undefined or null.`);
+        }
+        const isValidY = typeof yValue === "number";
+        if (!isValidY) {
+            throw new Error(`Row ${i}: y-axis value "${y}" must be a number. Got: ${typeof yValue} (${yValue})`);
+        }
+    }
+}

package/esm/deps/jsr.io/@nshiab/journalism-dataviz/1.0.10/src/dataviz/logBarChart.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Generates and logs a text-based bar chart to the console. This function is useful for quickly visualizing data distributions or comparisons directly within a terminal or log output, without needing a graphical interface. It's particularly effective for presenting categorical data or showing the relative magnitudes of different items.
+ *
+ * The chart is constructed using ASCII characters, making it universally compatible across various terminal environments. It can display data for various categories and their corresponding numerical values, with extensive options for custom formatting of labels and values, controlling the chart's width, and adding a descriptive title or a total label. For optimal visualization, it's recommended that the input `data` be sorted by the `values` key in descending order, though the function does not enforce this.
+ *
+ * @param data - An array of objects, where each object represents a bar in the chart. Each object should contain keys corresponding to the `labels` and `values` parameters.
+ * @param labels - The key in the data objects whose values will be used as textual labels for each bar (e.g., 'category', 'name', 'country').
+ * @param values - The key in the data objects whose numerical values will determine the length of each bar and be displayed alongside the labels (e.g., 'sales', 'count', 'percentage').
+ * @param options - Optional configuration for customizing the appearance and behavior of the chart.
+ * @param options.formatLabels - A function to format the labels displayed on the chart. It receives the raw label value as input and should return a string. Defaults to converting the label to a string.
+ * @param options.formatValues - A function to format the numerical values displayed next to the bars. It receives the raw numerical value as input and should return a string. Defaults to formatting the number using `formatNumber` (which adds commas for thousands, etc.).
+ * @param options.width - The maximum width of the bars in characters. The bars will scale proportionally to this width. A larger width allows for more detailed visualization. Defaults to `40`.
+ * @param options.title - An optional title to display above the chart. If not provided, a default title based on `labels` and `values` keys will be generated.
+ * @param options.totalLabel - An optional label to display for the total sum of all values at the bottom of the chart. If provided, the sum of all `values` will be calculated and displayed next to this label.
+ * @param options.compact - If `true`, the chart will be rendered in a more compact format, reducing vertical spacing between bars. Defaults to `false`.
+ *
+ * @example
+ * ```ts
+ * // Visualize sales data for different regions.
+ * const salesData = [
+ *   { region: 'North', sales: 1200 },
+ *   { region: 'South', sales: 800 },
+ *   { region: 'East', sales: 1500 },
+ *   { region: 'West', sales: 950 }
+ * ];
+ * logBarChart(salesData, 'region', 'sales', { title: 'Regional Sales Overview' });
+ * ```
+ * @example
+ * ```ts
+ * // Display product popularity with custom value formatting and a compact layout.
+ * const productPopularity = [
+ *   { product: 'Laptop', views: 5000 },
+ *   { product: 'Mouse', views: 1500 },
+ *   { product: 'Keyboard', views: 2500 }
+ * ];
+ * logBarChart(productPopularity, 'product', 'views', {
+ *   formatValues: (v) => `${v / 1000}K`,
+ *   width: 30,
+ *   compact: true,
+ *   totalLabel: 'Total Views'
+ * });
+ * ```
+ * @returns {void}
+ * @category Dataviz
+ */
+export default function logBarChart<T extends Record<string, unknown>>(data: T[], labels: keyof T, values: keyof T, options?: {
+    formatLabels?: (d: T[typeof labels]) => string;
+    formatValues?: (d: T[typeof values]) => string;
+    width?: number;
+    title?: string;
+    totalLabel?: string;
+    compact?: boolean;
+}): void;
+//# sourceMappingURL=logBarChart.d.ts.map

package/esm/deps/jsr.io/@nshiab/journalism-dataviz/1.0.10/src/dataviz/logBarChart.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logBarChart.d.ts","sourceRoot":"","sources":["../../../../../../../../src/deps/jsr.io/@nshiab/journalism-dataviz/1.0.10/src/dataviz/logBarChart.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,MAAM,CAAC,OAAO,UAAU,WAAW,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACnE,IAAI,EAAE,CAAC,EAAE,EACT,MAAM,EAAE,MAAM,CAAC,EACf,MAAM,EAAE,MAAM,CAAC,EACf,OAAO,GAAE;IACP,YAAY,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,OAAO,MAAM,CAAC,KAAK,MAAM,CAAC;IAC/C,YAAY,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,OAAO,MAAM,CAAC,KAAK,MAAM,CAAC;IAC/C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,OAAO,CAAC;CACd,GACL,IAAI,CA6BN"}

package/esm/deps/jsr.io/@nshiab/journalism-dataviz/1.0.10/src/dataviz/logBarChart.js

@@ -0,0 +1,67 @@
+import { formatNumber } from "../../../../journalism-format/1.1.5/src/index.js";
+import makeBars from "./helpers/makeBars.js";
+/**
+ * Generates and logs a text-based bar chart to the console. This function is useful for quickly visualizing data distributions or comparisons directly within a terminal or log output, without needing a graphical interface. It's particularly effective for presenting categorical data or showing the relative magnitudes of different items.
+ *
+ * The chart is constructed using ASCII characters, making it universally compatible across various terminal environments. It can display data for various categories and their corresponding numerical values, with extensive options for custom formatting of labels and values, controlling the chart's width, and adding a descriptive title or a total label. For optimal visualization, it's recommended that the input `data` be sorted by the `values` key in descending order, though the function does not enforce this.
+ *
+ * @param data - An array of objects, where each object represents a bar in the chart. Each object should contain keys corresponding to the `labels` and `values` parameters.
+ * @param labels - The key in the data objects whose values will be used as textual labels for each bar (e.g., 'category', 'name', 'country').
+ * @param values - The key in the data objects whose numerical values will determine the length of each bar and be displayed alongside the labels (e.g., 'sales', 'count', 'percentage').
+ * @param options - Optional configuration for customizing the appearance and behavior of the chart.
+ * @param options.formatLabels - A function to format the labels displayed on the chart. It receives the raw label value as input and should return a string. Defaults to converting the label to a string.
+ * @param options.formatValues - A function to format the numerical values displayed next to the bars. It receives the raw numerical value as input and should return a string. Defaults to formatting the number using `formatNumber` (which adds commas for thousands, etc.).
+ * @param options.width - The maximum width of the bars in characters. The bars will scale proportionally to this width. A larger width allows for more detailed visualization. Defaults to `40`.
+ * @param options.title - An optional title to display above the chart. If not provided, a default title based on `labels` and `values` keys will be generated.
+ * @param options.totalLabel - An optional label to display for the total sum of all values at the bottom of the chart. If provided, the sum of all `values` will be calculated and displayed next to this label.
+ * @param options.compact - If `true`, the chart will be rendered in a more compact format, reducing vertical spacing between bars. Defaults to `false`.
+ *
+ * @example
+ * ```ts
+ * // Visualize sales data for different regions.
+ * const salesData = [
+ *   { region: 'North', sales: 1200 },
+ *   { region: 'South', sales: 800 },
+ *   { region: 'East', sales: 1500 },
+ *   { region: 'West', sales: 950 }
+ * ];
+ * logBarChart(salesData, 'region', 'sales', { title: 'Regional Sales Overview' });
+ * ```
+ * @example
+ * ```ts
+ * // Display product popularity with custom value formatting and a compact layout.
+ * const productPopularity = [
+ *   { product: 'Laptop', views: 5000 },
+ *   { product: 'Mouse', views: 1500 },
+ *   { product: 'Keyboard', views: 2500 }
+ * ];
+ * logBarChart(productPopularity, 'product', 'views', {
+ *   formatValues: (v) => `${v / 1000}K`,
+ *   width: 30,
+ *   compact: true,
+ *   totalLabel: 'Total Views'
+ * });
+ * ```
+ * @returns {void}
+ * @category Dataviz
+ */
+export default function logBarChart(data, labels, values, options = {}) {
+    if (options.title) {
+        console.log(`\n${options.title}`);
+    }
+    else {
+        console.log(`\nBar chart of "${String(values)}" per "${String(labels)}":`);
+    }
+    const formatLabels = options.formatLabels ??
+        function (d) {
+            return String(d);
+        };
+    const formatValues = options.formatValues ??
+        function (d) {
+            return formatNumber(d);
+        };
+    const width = options.width ?? 40;
+    const chartData = makeBars(data, "\x1b[38;5;55m", // Darker purple color
+    String(labels), String(values), (d) => formatLabels(d), (d) => formatValues(d), width, options.compact ?? false, options.totalLabel);
+    console.log(chartData.join("\n"));
+}

package/esm/deps/jsr.io/@nshiab/journalism-dataviz/1.0.10/src/dataviz/logDotChart.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Generates and logs a text-based dot chart to the console. This function is ideal for visualizing the relationship between two numerical variables. It provides a quick, terminal-friendly way to inspect data trends and distributions.
+ *
+ * The chart is rendered using ASCII characters, ensuring compatibility across various terminal environments. It supports custom formatting for both x and y-axis values, and can generate small multiples to compare distributions across different categories. While the function expects data to be sorted by the x-axis values for proper rendering, it does not enforce this.
+ *
+ * **Data Type Requirements:**
+ * - **X-axis values**: Must be `number` or `Date` objects.
+ * - **Y-axis values**: Must be `number` values.
+ * - All values must be non-null and defined.
+ *
+ * @param data - An array of objects representing the data to be visualized. Each object should contain keys corresponding to the `x` and `y` parameters.
+ * @param x - The key in the data objects whose values will be plotted on the x-axis. Values must be numbers or Date objects.
+ * @param y - The key in the data objects whose values will be plotted on the y-axis. Values must be numbers.
+ * @param options - An optional object to customize the chart's appearance and behavior.
+ * @param options.formatX - A function to format the x-axis values for display. It receives the raw x-value as input and should return a string. If the first data point's x value is a Date, it defaults to formatting the date as "YYYY-MM-DD".
+ * @param options.formatY - A function to format the y-axis values for display. It receives the raw y-value as input and should return a string.
+ * @param options.smallMultiples - A key in the data objects to create small multiples (separate charts) for each unique value of this key. This is useful for comparing trends across different categories.
+ * @param options.fixedScales - If `true` and `smallMultiples` is used, all small multiple charts will share the same x and y scales, allowing for direct comparison of magnitudes. If `false`, each small multiple will have its own independent scales. Defaults to `false`.
+ * @param options.smallMultiplesPerRow - The number of small multiples to display per row when `smallMultiples` is used. Defaults to `3`.
+ * @param options.width - The width of the chart in characters. This affects the horizontal resolution of the chart. Defaults to `60`.
+ * @param options.height - The height of the chart in lines. This affects the vertical resolution of the chart. Defaults to `20`.
+ * @param options.title - The title of the chart. If not provided, a default title based on `x`, `y`, and `smallMultiples` (if applicable) will be generated.
+ *
+ * @example
+ * ```ts
+ * // Visualize a time series of values.
+ * const timeSeriesData = [
+ *     { date: new Date("2023-01-01"), value: 10 },
+ *     { date: new Date("2023-02-01"), value: 20 },
+ *     { date: new Date("2023-03-01"), value: 30 },
+ *     { date: new Date("2023-04-01"), value: 40 },
+ * ];
+ *
+ * logDotChart(timeSeriesData, "date", "value", {
+ *     formatX: (d) => (d as Date).toISOString().slice(0, 10),
+ *     formatY: (d) => "$" + (d as number).toString(),
+ *     title: "Monthly Sales Trend",
+ * });
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Compare trends across different categories using small multiples.
+ * const multiCategoryData = [
+ *     { date: new Date("2023-01-01"), value: 10, category: "A" },
+ *     { date: new Date("2023-02-01"), value: 20, category: "A" },
+ *     { date: new Date("2023-03-01"), value: 30, category: "A" },
+ *     { date: new Date("2023-04-01"), value: 40, category: "A" },
+ *     { date: new Date("2023-01-01"), value: 15, category: "B" },
+ *     { date: new Date("2023-02-01"), value: 25, category: "B" },
+ *     { date: new Date("2023-03-01"), value: 35, category: "B" },
+ *     { date: new Date("2023-04-01"), value: 45, category: "B" },
+ * ];
+ *
+ * logDotChart(multiCategoryData, "date", "value", {
+ *     formatX: (d) => (d as Date).toISOString().slice(0, 10),
+ *     formatY: (d) => "$" + (d as number).toString(),
+ *     smallMultiples: "category",
+ *     smallMultiplesPerRow: 2,
+ *     fixedScales: true,
+ *     title: "Sales Trend by Category",
+ * });
+ * ```
+ *
+ * @returns {void}
+ * @category Dataviz
+ */
+export default function logDotChart<T extends Record<string, unknown>>(data: T[], x: keyof T, y: keyof T, options?: {
+    formatX?: (d: T[typeof x]) => string;
+    formatY?: (d: T[typeof y]) => string;
+    smallMultiples?: keyof T;
+    fixedScales?: boolean;
+    smallMultiplesPerRow?: number;
+    width?: number;
+    height?: number;
+    title?: string;
+}): void;
+//# sourceMappingURL=logDotChart.d.ts.map

package/esm/deps/jsr.io/@nshiab/journalism-dataviz/1.0.10/src/dataviz/logDotChart.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logDotChart.d.ts","sourceRoot":"","sources":["../../../../../../../../src/deps/jsr.io/@nshiab/journalism-dataviz/1.0.10/src/dataviz/logDotChart.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkEG;AACH,MAAM,CAAC,OAAO,UAAU,WAAW,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACnE,IAAI,EAAE,CAAC,EAAE,EACT,CAAC,EAAE,MAAM,CAAC,EACV,CAAC,EAAE,MAAM,CAAC,EACV,OAAO,GAAE;IACP,OAAO,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,KAAK,MAAM,CAAC;IACrC,OAAO,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,KAAK,MAAM,CAAC;IACrC,cAAc,CAAC,EAAE,MAAM,CAAC,CAAC;IACzB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;CACX,GACL,IAAI,CAyBN"}

package/esm/deps/jsr.io/@nshiab/journalism-dataviz/1.0.10/src/dataviz/logDotChart.js

@@ -0,0 +1,91 @@
+import addDots from "./helpers/addDots.js";
+import prepChart from "./helpers/prepChart.js";
+/**
+ * Generates and logs a text-based dot chart to the console. This function is ideal for visualizing the relationship between two numerical variables. It provides a quick, terminal-friendly way to inspect data trends and distributions.
+ *
+ * The chart is rendered using ASCII characters, ensuring compatibility across various terminal environments. It supports custom formatting for both x and y-axis values, and can generate small multiples to compare distributions across different categories. While the function expects data to be sorted by the x-axis values for proper rendering, it does not enforce this.
+ *
+ * **Data Type Requirements:**
+ * - **X-axis values**: Must be `number` or `Date` objects.
+ * - **Y-axis values**: Must be `number` values.
+ * - All values must be non-null and defined.
+ *
+ * @param data - An array of objects representing the data to be visualized. Each object should contain keys corresponding to the `x` and `y` parameters.
+ * @param x - The key in the data objects whose values will be plotted on the x-axis. Values must be numbers or Date objects.
+ * @param y - The key in the data objects whose values will be plotted on the y-axis. Values must be numbers.
+ * @param options - An optional object to customize the chart's appearance and behavior.
+ * @param options.formatX - A function to format the x-axis values for display. It receives the raw x-value as input and should return a string. If the first data point's x value is a Date, it defaults to formatting the date as "YYYY-MM-DD".
+ * @param options.formatY - A function to format the y-axis values for display. It receives the raw y-value as input and should return a string.
+ * @param options.smallMultiples - A key in the data objects to create small multiples (separate charts) for each unique value of this key. This is useful for comparing trends across different categories.
+ * @param options.fixedScales - If `true` and `smallMultiples` is used, all small multiple charts will share the same x and y scales, allowing for direct comparison of magnitudes. If `false`, each small multiple will have its own independent scales. Defaults to `false`.
+ * @param options.smallMultiplesPerRow - The number of small multiples to display per row when `smallMultiples` is used. Defaults to `3`.
+ * @param options.width - The width of the chart in characters. This affects the horizontal resolution of the chart. Defaults to `60`.
+ * @param options.height - The height of the chart in lines. This affects the vertical resolution of the chart. Defaults to `20`.
+ * @param options.title - The title of the chart. If not provided, a default title based on `x`, `y`, and `smallMultiples` (if applicable) will be generated.
+ *
+ * @example
+ * ```ts
+ * // Visualize a time series of values.
+ * const timeSeriesData = [
+ *     { date: new Date("2023-01-01"), value: 10 },
+ *     { date: new Date("2023-02-01"), value: 20 },
+ *     { date: new Date("2023-03-01"), value: 30 },
+ *     { date: new Date("2023-04-01"), value: 40 },
+ * ];
+ *
+ * logDotChart(timeSeriesData, "date", "value", {
+ *     formatX: (d) => (d as Date).toISOString().slice(0, 10),
+ *     formatY: (d) => "$" + (d as number).toString(),
+ *     title: "Monthly Sales Trend",
+ * });
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Compare trends across different categories using small multiples.
+ * const multiCategoryData = [
+ *     { date: new Date("2023-01-01"), value: 10, category: "A" },
+ *     { date: new Date("2023-02-01"), value: 20, category: "A" },
+ *     { date: new Date("2023-03-01"), value: 30, category: "A" },
+ *     { date: new Date("2023-04-01"), value: 40, category: "A" },
+ *     { date: new Date("2023-01-01"), value: 15, category: "B" },
+ *     { date: new Date("2023-02-01"), value: 25, category: "B" },
+ *     { date: new Date("2023-03-01"), value: 35, category: "B" },
+ *     { date: new Date("2023-04-01"), value: 45, category: "B" },
+ * ];
+ *
+ * logDotChart(multiCategoryData, "date", "value", {
+ *     formatX: (d) => (d as Date).toISOString().slice(0, 10),
+ *     formatY: (d) => "$" + (d as number).toString(),
+ *     smallMultiples: "category",
+ *     smallMultiplesPerRow: 2,
+ *     fixedScales: true,
+ *     title: "Sales Trend by Category",
+ * });
+ * ```
+ *
+ * @returns {void}
+ * @category Dataviz
+ */
+export default function logDotChart(data, x, y, options = {}) {
+    if (options.title) {
+        console.log(`\n${options.title}`);
+    }
+    else {
+        console.log(`\nDot chart of "${String(y)}" over "${String(x)}"${options.smallMultiples
+            ? `, for each "${String(options.smallMultiples)}"`
+            : ""}:`);
+    }
+    prepChart("dot", data, String(x), String(y), addDots, {
+        ...options,
+        formatX: options.formatX
+            ? (d) => options.formatX(d)
+            : undefined,
+        formatY: options.formatY
+            ? (d) => options.formatY(d)
+            : undefined,
+        smallMultiples: options.smallMultiples
+            ? String(options.smallMultiples)
+            : undefined,
+    });
+}

package/esm/deps/jsr.io/@nshiab/journalism-dataviz/1.0.10/src/dataviz/logLineChart.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Generates and logs a text-based line chart to the console. This function is particularly useful for visualizing trends over time providing a quick and accessible way to understand data progression directly within a terminal or log output.
+ *
+ * The chart is rendered using ASCII characters, ensuring broad compatibility. It supports custom formatting for both x and y-axis values, and can generate small multiples to compare trends across different categories. When the chart's width is smaller than the number of data points, the line represents an averaged approximation of the data, providing a smoothed view of the trend. For optimal visualization, it's recommended that the input `data` be sorted by the x-axis values.
+ *
+ * **Data Type Requirements:**
+ * - **X-axis values**: Must be `number` or `Date` objects.
+ * - **Y-axis values**: Must be `number` values.
+ * - All values must be non-null and defined.
+ *
+ * @param data - An array of objects representing the data to be visualized. Each object should contain keys corresponding to the `x` and `y` parameters.
+ * @param x - The key in the data objects whose values will be plotted on the x-axis. Values must be numbers or Date objects.
+ * @param y - The key in the data objects whose values will be plotted on the y-axis. Values must be numbers.
+ * @param options - An optional object to customize the chart's appearance and behavior.
+ * @param options.formatX - A function to format the x-axis values for display. It receives the raw x-value as input and should return a string. If the first data point's x value is a Date, it defaults to formatting the date as "YYYY-MM-DD".
+ * @param options.formatY - A function to format the y-axis values for display. It receives the raw y-value as input and should return a string.
+ * @param options.smallMultiples - A key in the data objects to create small multiples (separate charts) for each unique value of this key. This is useful for comparing trends across different categories.
+ * @param options.fixedScales - If `true` and `smallMultiples` is used, all small multiple charts will share the same x and y scales, allowing for direct comparison of magnitudes. If `false`, each small multiple will have its own independent scales. Defaults to `false`.
+ * @param options.smallMultiplesPerRow - The number of small multiples to display per row when `smallMultiples` is used. Defaults to `3`.
+ * @param options.width - The width of the chart in characters. This affects the horizontal resolution of the chart. Defaults to `60`.
+ * @param options.height - The height of the chart in lines. This affects the vertical resolution of the chart. Defaults to `20`.
+ * @param options.title - The title of the chart. If not provided, a default title based on `x`, `y`, and `smallMultiples` (if applicable) will be generated.
+ *
+ * @example
+ * ```ts
+ * // Visualize a simple time series of values.
+ * const timeSeriesData = [
+ *     { date: new Date("2023-01-01"), value: 10 },
+ *     { date: new Date("2023-02-01"), value: 20 },
+ *     { date: new Date("2023-03-01"), value: 30 },
+ *     { date: new Date("2023-04-01"), value: 40 },
+ * ];
+ *
+ * logLineChart(timeSeriesData, "date", "value", {
+ *     formatX: (d) => (d as Date).toISOString().slice(0, 10),
+ *     title: "Monthly Data Trend",
+ * });
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Compare trends across different categories using small multiples.
+ * const multiCategoryData = [
+ *     { date: new Date("2023-01-01"), value: 10, category: "A" },
+ *     { date: new Date("2023-02-01"), value: 20, category: "A" },
+ *     { date: new Date("2023-03-01"), value: 30, category: "A" },
+ *     { date: new Date("2023-04-01"), value: 40, category: "A" },
+ *     { date: new Date("2023-01-01"), value: 15, category: "B" },
+ *     { date: new Date("2023-02-01"), value: 25, category: "B" },
+ *     { date: new Date("2023-03-01"), value: 35, category: "B" },
+ *     { date: new Date("2023-04-01"), value: 45, category: "B" },
+ * ];
+ *
+ * logLineChart(multiCategoryData, "date", "value", {
+ *     formatX: (d) => (d as Date).toLocaleDateString(),
+ *     formatY: (d) => "$" + (d as number).toString(),
+ *     smallMultiples: "category",
+ *     smallMultiplesPerRow: 2,
+ *     fixedScales: true,
+ *     title: "Sales Trend by Category",
+ * });
+ * ```
+ *
+ * @returns {void}
+ * @category Dataviz
+ */
+export default function logLineChart<T extends Record<string, unknown>>(data: T[], x: keyof T, y: keyof T, options?: {
+    formatX?: (d: T[typeof x]) => string;
+    formatY?: (d: T[typeof y]) => string;
+    smallMultiples?: keyof T;
+    fixedScales?: boolean;
+    smallMultiplesPerRow?: number;
+    width?: number;
+    height?: number;
+    title?: string;
+}): void;
+//# sourceMappingURL=logLineChart.d.ts.map

package/esm/deps/jsr.io/@nshiab/journalism-dataviz/1.0.10/src/dataviz/logLineChart.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logLineChart.d.ts","sourceRoot":"","sources":["../../../../../../../../src/deps/jsr.io/@nshiab/journalism-dataviz/1.0.10/src/dataviz/logLineChart.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiEG;AACH,MAAM,CAAC,OAAO,UAAU,YAAY,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACpE,IAAI,EAAE,CAAC,EAAE,EACT,CAAC,EAAE,MAAM,CAAC,EACV,CAAC,EAAE,MAAM,CAAC,EACV,OAAO,GAAE;IACP,OAAO,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,KAAK,MAAM,CAAC;IACrC,OAAO,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,KAAK,MAAM,CAAC;IACrC,cAAc,CAAC,EAAE,MAAM,CAAC,CAAC;IACzB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;CACX,GACL,IAAI,CAyBN"}