data

data

new data()

Module for dealing with data retrieval, transformation, upload, and download operations. Provides functions to interact with various hydrological data sources and perform data operations.

Source:

Methods

(async, static) download(options) → {Promise.<void>}

Download data in various formats to the user's local file system. Automatically transforms data using the transform function and creates a downloadable file.

Parameters:
Name Type Description
options Object

Configuration object for download

Properties
Name Type Attributes Description
params Object <optional>

Parameters for download configuration

Properties
Name Type Attributes Description
fileName string <optional>

Name for the downloaded file (without extension)
args Object

Arguments for download format and transformation

Properties
Name Type Attributes Description
type string

Download format ('CSV', 'JSON')
keep Array.<string> <optional>

Column headers to keep (for CSV)
data Object | Array | Promise

Data to download (can be a Promise)
Source:
Returns:

Promise that resolves when download is initiated

Type
Promise.<void>
Examples
// Download data as CSV file
await hydro.data.download({
  params: { fileName: 'streamflow_data' },
  args: { 
    type: 'CSV',
    keep: ['dateTime', 'value']
  },
  data: transformedData
});
// Downloads file as 'streamflow_data.csv'
// Download data as JSON file
await hydro.data.download({
  params: { fileName: 'station_info' },
  args: { type: 'JSON' },
  data: stationData
});
// Downloads file as 'station_info.json'
// Download with auto-generated filename
await hydro.data.download({
  args: { type: 'CSV' },
  data: myData
});
// Downloads with timestamp-based filename like '23.12.15.14:30.csv'

(static) generateDateString() → {string}

Generates a timestamp-based string for file naming. Creates a formatted date string in YY.MM.DD.HH:MM format.

Source:
Returns:

Formatted date string

Type
string
Examples
// Get current timestamp for filename
const timestamp = hydro.data.generateDateString();
// Returns something like: "23.12.15.14:30"
// Use in file download
const filename = `data_${hydro.data.generateDateString()}.csv`;
// Results in: "data_23.12.15.14:30.csv"

(static) lowercasing(obj) → {Object|Array|*}

Converts all object keys to lowercase recursively, including nested objects and arrays. Useful for normalizing API responses that may have inconsistent casing.

Parameters:
Name Type Description
obj Object | Array | *

Object, array, or value to process
Source:
Returns:

Copy of input with all object keys converted to lowercase

Type
Object | Array | *
Examples
// Normalize object keys
const normalized = hydro.data.lowercasing({
  StationName: "USGS Station",
  FlowData: {
    DateTime: "2023-01-01T12:00:00Z",
    Value: 100.5
  }
});
// Returns: { stationname: "USGS Station", flowdata: { datetime: "2023-01-01T12:00:00Z", value: 100.5 } }
// Process array of objects
const normalizedArray = hydro.data.lowercasing([
  { StationID: "01646500", FlowRate: 100 },
  { StationID: "01647000", FlowRate: 85 }
]);
// Returns: [{ stationid: "01646500", flowrate: 100 }, { stationid: "01647000", flowrate: 85 }]

(static) recursiveSearch(options) → {Array}

Recursively searches for arrays with specific key names in nested objects. Useful for extracting data from complex nested JSON structures returned by APIs.

Parameters:
Name Type Description
options Object

Search configuration object

Properties
Name Type Attributes Default Description
obj Object

Object to search within
searchkey string

Key name to search for
results Array <optional>
 []

Array to store found values (used internally for recursion)
Source:
Returns:

Array containing all found values for the specified key

Type
Array
Examples
// Search for 'timeSeries' arrays in USGS response
const complexData = {
  value: {
    queryInfo: { ... },
    timeSeries: [
      { name: 'Streamflow', values: [{ value: 100 }, { value: 95 }] }
    ]
  }
};

const timeSeries = hydro.data.recursiveSearch({
  obj: complexData,
  searchkey: 'timeSeries'
});
// Returns: [[{ name: 'Streamflow', values: [...] }]]
// Search for 'values' arrays in nested data
const found = hydro.data.recursiveSearch({
  obj: complexData,
  searchkey: 'values'
});
// Returns all arrays with key 'values'

(async, static) retrieve(options) → {Promise.<(Object|string)>}

Main function to retrieve data from various hydrological data sources. Supports multiple data sources including USGS, NLDI, NWS, and others.

Parameters:
Name Type Description
options Object

Configuration object for data retrieval

Properties
Name Type Attributes Description
params Object

Parameters for the request

Properties
Name Type Attributes Description
source string

Data source identifier (e.g., 'usgs', 'nldi', 'nws')
datatype string

Type of data to retrieve (varies by source)
type string <optional>

Response format ('json', 'xml', 'csv', 'soap') - defaults to source's default
transform boolean <optional>

Whether to apply data transformation
placeHolder boolean <optional>

Whether to use placeholder data
keyname string <optional>

API key parameter name for authenticated sources
args Object

Arguments specific to the data source endpoint
data Object <optional>

Additional data payload (for POST requests)
Source:
Returns:

Promise resolving to retrieved data in specified format

Type
Promise.<(Object|string)>
Examples
// Retrieve USGS instantaneous streamflow data
const streamflowData = await hydro.data.retrieve({
  params: {
    source: 'usgs',
    datatype: 'instant-values',
    transform: true
  },
  args: {
    format: 'json',
    sites: '05454500',
    startDT: '2020-01-01',
    endDT: '2020-01-07'
  }
});
// Retrieve NLDI basin boundary data
const basinData = await hydro.data.retrieve({
  params: {
    source: 'nldi',
    datatype: 'getBasin'
  },
  args: {
    featureSource: 'comid',
    featureId: '13297246'
  }
});
// Retrieve NASA POWER meteorological data
const powerData = await hydro.data.retrieve({
  params: {
    source: 'nasapower',
    datatype: 'point-data'
  },
  args: {
    parameters: 'T2M,PRECTOTCORR,RH2M',
    community: 're',
    longitude: -76.3,
    latitude: 38.5,
    start: '20200101',
    end: '20200131',
    format: 'JSON'
  }
});
// Retrieve NOAA climate data with API key
const climateData = await hydro.data.retrieve({
  params: {
    source: 'noaa',
    datatype: 'prec-15min',
    token: 'YOUR_NOAA_TOKEN'
  },
  args: {
    datasetid: 'PRECIP_15',
    stationid: 'GHCND:USW00014895',
    startdate: '2020-01-01',
    enddate: '2020-01-07',
    limit: 100
  }
});
// Retrieve Meteostat weather station data
const meteoData = await hydro.data.retrieve({
  params: {
    source: 'meteostat',
    datatype: 'dailydata-station',
    'x-rapidapi-key': 'YOUR_RAPIDAPI_KEY'
  },
  args: {
    station: '10382',
    start: '2020-01-01',
    end: '2020-01-31'
  }
});
// Retrieve EPA precipitation data (POST request)
const epaData = await hydro.data.retrieve({
  params: {
    source: 'epa',
    datatype: 'precipitation',
    type: 'json'
  },
  args: {
    source: 'nldas',
    dateTimeSpan: {
      startDate: '2020-01-01 00',
      endDate: '2020-01-07 00',
      dateTimeFormat: 'yyyy-MM-dd HH'
    },
    geometry: {
      point: {
        latitude: 33.925,
        longitude: -83.356
      }
    },
    dataValueFormat: 'E3',
    temporalResolution: 'hourly',
    units: 'metric'
  }
});
// Retrieve flood damage scenario data
const floodData = await hydro.data.retrieve({
  params: {
    source: 'flooddamage_dt',
    datatype: 'x500_year',
    transform: 'eval'
  },
  args: {
    sourceType: 'Cedar Rapids'
  }
});

(static) transform(options) → {Object|Array|string}

Convert data types into various formats based on JavaScript objects as primary input. Supports extraction of nested data, filtering, and format conversion.

Parameters:
Name Type Description
options Object

Configuration object for transformation

Properties
Name Type Attributes Description
params Object <optional>

Parameters for data extraction and saving

Properties
Name Type Attributes Description
save string <optional>

Key name to search for and extract from nested objects
output string <optional>

Output variable name (currently unused)
args Object <optional>

Arguments for transformation options

Properties
Name Type Attributes Default Description
type string <optional>

Output format: 'ARR', 'ARR-col', 'CSV', 'JSON', 'XML2JSON'
keep Array.<string> | string <optional>

Array of column headers to keep (JSON string or array)
parse boolean <optional>

Whether to parse strings to numbers/dates/booleans
mode string <optional>

Processing mode: 'flatten', 'flatten-objects'
pick number <optional>

Pick specific row index from 2D array
attachNames boolean <optional>
 true

Whether to attach column names to arrays
data Object | Array

Input data object to be transformed
Source:
Returns:

Transformed data in the specified format

Type
Object | Array | string
Examples
// Extract specific data from nested object and convert to array
const arrayData = hydro.data.transform({
  params: { save: 'timeSeries' },
  args: { 
    keep: ['dateTime', 'value'], 
    type: 'ARR',
    parse: true 
  },
  data: usgsResponseData
});
// Convert object array to CSV format
const csvData = hydro.data.transform({
  args: { type: 'CSV' },
  data: [
    { date: '2023-01-01', flow: 100.5 },
    { date: '2023-01-02', flow: 95.3 }
  ]
});
// Flatten nested object structure
const flattenedData = hydro.data.transform({
  args: { mode: 'flatten-objects' },
  data: {
    station: {
      info: { name: 'USGS Station', id: '01646500' },
      data: { flow: 100.5, stage: 2.1 }
    }
  }
});
// Result: { 'station.info.name': 'USGS Station', 'station.info.id': '01646500', ... }
// Extract specific columns as separate arrays
const columnArrays = hydro.data.transform({
  args: { 
    type: 'ARR-col',
    keep: ['dateTime', 'value'],
    attachNames: false
  },
  data: [
    { dateTime: '2023-01-01', value: 100.5, quality: 'A' },
    { dateTime: '2023-01-02', value: 95.3, quality: 'A' }
  ]
});
// Result: [['2023-01-01', '2023-01-02'], [100.5, 95.3]]
// Convert XML string to JSON
const jsonData = hydro.data.transform({
  args: { type: 'XML2JSON' },
  data: '<root><item>value1</item><item>value2</item></root>'
});
// Pick specific row from 2D array and flatten
const singleRow = hydro.data.transform({
  args: { 
    pick: 0, 
    mode: 'flatten' 
  },
  data: [
    ['dates', '2023-01-01', '2023-01-02'],
    ['values', 100.5, 95.3]
  ]
});
// Result: [100.5, 95.3] (numeric values from first row, excluding header)

(async, static) upload(options) → {Promise.<(Array|Object|string)>}

Upload data from the user's local file system for analysis. Creates a file input dialog and processes the selected file based on its type.

Parameters:
Name Type Description
options Object

Configuration object for file upload

Properties
Name Type Attributes Description
params Object

Parameters for upload configuration

Properties
Name Type Description
type string

File type to accept ('CSV', 'JSON', 'KML')
args Object <optional>

Additional arguments (currently unused)
data Object <optional>

Additional data (currently unused)
Source:
Returns:

Promise resolving to parsed file content

Type
Promise.<(Array|Object|string)>
Examples
// Upload and parse CSV file
const csvData = await hydro.data.upload({
  params: { type: 'CSV' }
});
// Returns array of arrays with numeric conversion for numeric columns
// Example result: [['Date', 'Flow', 'Stage'], ['2023-01-01', 100.5, 2.1], ...]
// Upload and parse JSON file
const jsonData = await hydro.data.upload({
  params: { type: 'JSON' }
});
// Returns parsed JSON object
// Upload KML file as raw text
const kmlData = await hydro.data.upload({
  params: { type: 'KML' }
});
// Returns raw KML content as string

(static) xml2json(xml) → {Object|string|null}

Recursively converts XML document format to JSON format. Handles XML attributes, text content, and nested elements.

Parameters:
Name Type Description
xml Document | Element

Parsed XML document or element from DOMParser
Source:
Returns:

Object representation of XML structure, or null if error occurs

Type
Object | string | null
Examples
// Convert XML to JSON
const parser = new DOMParser();
const xmlDoc = parser.parseFromString(xmlString, "text/xml");
const jsonResult = hydro.data.xml2json(xmlDoc);

// For XML like: <station id="01646500"><name>Potomac River</name><flow>100.5</flow></station>
// Returns: { station: { "@id": "01646500", name: "Potomac River", flow: "100.5" } }
// Handle XML with multiple elements
// XML: <stations><station>Station1</station><station>Station2</station></stations>
// Returns: { stations: { station: ["Station1", "Station2"] } }