Shakelog Dashboard Help
¶ Chapter 1: Dynamic SHM
¶ 1. Project Settings
¶ 1.1 Project Information
Use this section to configure the baseline parameters when initializing a new monitoring project.
¶ General Project Information
Project Name: Enter a unique, descriptive identifier for the specific site or asset. This name will represent the asset across all dashboards and exported engineering reports.
Project Type: Select or specify the structural monitoring system architecture being deployed(e.g., ShakeLog System).
Gateway ID: Input the unique numerical hardware identifier assigned to the on-site data acquisition gateway.
Structure Type: Classify the main asset category (e.g., Building, Bridge, Industrial). This classification helps apply the appropriate structural health baseline models.
¶ Engineering Units Configuration
Velocimeter: Select the preferred engineering unit for velocity data streams from the dropdown menu (e.g., m/s).
Accelerometer: Select the preferred engineering unit for acceleration data streams from the dropdown menu (e.g., g).
Project Tags: Add relevant structural, material, or regional keywords (e.g., Building, concrete, Steel). These tags allow the team to quickly filter, group, and query multiple structures across our global asset database.
Project Notes: Use this text area to log critical engineering and environmental context.
The example building is shown below.
¶ 1.2 Location and Time
Location
Address: Enter the physical street address of the structure.
Country: Select the nation where the asset resides from the dropdown menu. If the country is not explicitly listed, select Other.
City: Specify the city and region (e.g., Montreal, Canada).
ZIP / Postal Code: Enter the local postal routing code (e.g., 107-8503).
Latitude & Direction: Input the decimal latitude coordinate (e.g., 35.67361) and select the appropriate hemisphere directional dropdown (North or South).
Longitude & Direction: Input the decimal longitude coordinate (e.g., 139.72835) and select the appropriate hemisphere directional dropdown (East or West).
Time Zone Configuration
Aligning the software time zone with the physical data logger onsite is paramount for accurate event triggering and data correlation.
Time Zone Dropdown: Manually select or verify the localized time zone offset (e.g., Asia/Tokyo (GMT+09:00)). All incoming accelerometer, velocimeter, and structural health alerts will be timestamped according to this selection.
The example building is shown below.
¶ 1.3 Geometry
This section defines the primary geometric entities used to visualize the modes. Understanding how these elements function is critical for accurate sensor data mapping and structural component visualization.
All geometry information is organized in a table with descriptive column headings. The right side of each row features three action buttons to Edit, Delete, or Copy the entry, in that specific order. To add a new geometry, click the green "+" button in the top-right corner. Additionally, table data can be bulk imported or exported via a .txt file using a tab-separated format, where records are divided by newlines and individual data fields are separated by tabs.
¶ Nodes
In the geometric space of the visualization interface, a Node represents a single point with a unique Node ID in three-dimensional space, defined precisely by its spatial coordinates (X, Y, Z). Nodes serve as the foundational units from which all complex geometries and structural networks are built.
Sensor Mapping Matrix: Within the dashboard architecture, sensor data is mapped directly to specific nodes. This binds the physical accelerometer or velocimeter data stream to a precise spatial coordinate on the structural asset.
The Setup ID field is not utilized for ShakeLog projects (as they do not require multi-setup testing) and should be left at its default value of 0.
¶ Lines
A Line is a linear geometric element defined by its connectivity between two distinct endpoints (the parent nodes).
Surface Boundaries: Line segments can be utilized to outline perimeter boundaries, establishing the edges of larger structural surfaces, floor diaphragms, or shear wall faces.
Structural Element Modeling: Within the monitoring workspace, lines are used to represent primary one-dimensional structural members.
Each line connects two points, meaning its inputs must strictly correspond to valid Node IDs from the preceding Nodes table.
¶ Surfaces
Geometrically, surfaces are constructed using a triangular mesh architecture where each individual surface facet is defined by three interconnected nodes. The dashboard only accepts triangular meshes; quadrilateral surfaces are currently unsupported. Any quadrilateral surface data must be converted into triangular elements prior to entry.
Structural Application: Surfaces are primarily designed to model and visualize horizontal or sub-horizontal flat elements. Typical use cases include:
Floor slabs and diaphragms
Ceilings and non-structural architectural horizontal boundaries
Bridge decks and approach slabs
Modeling Restrictions: Surfaces within this module are optimized for horizontal plane mapping. They are not intended to define vertical structural components, such as shear walls or retaining structures.
Critical Modeling Protocol: Rigid vs. Deformable Components
If a structural component (such as a floor slab or bridge deck) is expected to experience and display deformation under dynamic or environmental loading, do not model it as a single, large rigid shape. To capture realistic behaviors like bending, local deflection, localized tilt, or curvature changes, the component must be discretized into a multi-element mesh (multiple smaller surface pieces).
¶ Final Preview
Click Preview Geometry to visually verify your model layout. Control buttons at the top allow you to toggle the visibility of node numbers and sensor locations. Navigate the 3D viewport using standard mouse controls: Left-click to pan, Right-click to rotate, and use the Scroll Wheel (or drag while holding Middle-click) to zoom.
¶ Non-sensor Joint Movement
Defining non-sensor joint movement based on sensor IDs allows the software to mathematically map the behavior of unmonitored locations, which ultimately allows you to visualize the complete 3D mode shape animation of the structure. The rigid body Python code can be used to generate the non-sensor joint movement, as shown below for the building example.
¶ Non-sensor Joint Movement per Mode
This configuration grid allows you to manually map out exactly how your defined non-sensor structural locations are expected to displace during each distinct dynamic mode.
Mode ID Synchronization: These identifiers are not created here; they are synchronized and selected directly from the Health Monitoring tab.
Frequency Parameters: The listed frequencies are automatically populated alongside their respective Mode IDs.
Note: These values in this view are read-only and cannot be modified. They serve as a reference point only and do not impact the manual displacement mapping calculations for this specific step.
This modal window opens when you click the Edit button under the Non-Sensor Joint Movements column for a specific mode. It allows you to define exactly how a non-sensor joint moves by linking its behavior to the weighted movements of up to two reference nodes per axis.
¶ The Theory & Mathematical Logic
To calculate the estimated displacement of a non-sensor joint (Node ID), the software applies a linear combination (interpolation or extrapolation) based on the behavior of known physical nodes.
By establishing these ratios, the software can accurately map complex global mode shapes to areas of the structure without physical sensors.
Saving & Exiting: After verifying that the coefficients are balanced and correct, click the Close button at the bottom right corner to return to the main Non-Sensor Joint Movements Per Mode dashboard. Be sure to click the green checkmark on the main table to commit these changes to memory.
Note on Remaining Inputs: Any additional geometry inputs not covered in this section are strictly required for seismic analysis. These parameters and their configurations are detailed thoroughly in Chapter 2.
¶ 1.4 HAZUS Damage Estimation
This section configures the parameters required to estimate structural and non-structural losses following a seismic event. This configuration is strictly utilized for Seismic Evaluation projects.
Structural Health Monitoring (SHM): If your project is focused solely on dynamic structural health monitoring, this configuration is not required and can be safely left empty.
Detailed Methodology: For comprehensive instructions on configuring HAZUS damage states and curve thresholds, please refer to Chapter 2.
¶ 1.5 FEMA P-58 Damage Estimation
This section configures the parameters required to estimate structural and non-structural losses following a seismic event. This configuration is strictly utilized for Seismic Evaluation projects.
Structural Health Monitoring (SHM): If your project is focused solely on dynamic structural health monitoring, this configuration is not required and can be safely left empty.
Detailed Methodology: For comprehensive instructions on configuring FEMA P-58 damage states and curve thresholds, please refer to Chapter 2.
¶ 1.6 Compliance
This section defines the threshold curves (typically measuring Peak Particle Velocity (PPV) against frequency) used to monitor structural health and environmental impact.
Add Custom Compliance Standard: Click this button to manually input a proprietary or project-specific compliance matrix. Use this if your project is bound by a specialized non-standard engineering specification or a unique contractual threshold.
Compliance Standard Dropdown: Select the active regulatory standard from the dropdown menu to apply its pre-configured limitation curves. The available built-in standards include:
Toronto: Applies the local environmental and structural vibration criteria typically aligned with the City of Toronto structural monitoring bylaws (e.g., By-law 514-2008 for construction vibration).
USBM RI8507: Applies the United States Bureau of Mines (USBM) Research Investigation 8507 alternative blasting level criteria. This utilizes a frequency-dependent PPV limit curve designed to minimize cosmetic and structural damage in low-rise residential and commercial structures.
OSM: Applies the Office of Surface Mining (OSM) regulatory limits, utilizing standard structural protection criteria based on structural material categories and distance-based scaling.
Note: Choosing a standard automatically applies its respective frequency-dependent envelope. Ensure the selected criteria match the specific governing jurisdiction and structural classification detailed in your project's environmental or structural impact assessment report.
For more details, please refer to the vibration event section. The compliance options are shown below.
¶ 1.7 Report Settings
Sensor labels need to be defined. Room numbers and floor numbers are typically mentioned.
The Health Monitoring Report Settings workspace configures the automation engine responsible for generating periodic structural health evaluations.
The software uses standard Cron-like expressions to trigger automated reports. Critical Coordinate Note: All schedules are calculated and executed strictly in Coordinated Universal Time (UTC). Remember to convert your local project time zone to UTC when defining trigger windows to avoid off-hour processing or data synchronization gaps. Configure the execution cadence using the following temporal parameters:
Minutes (0–59): Specify the exact minute of the hour for the report engine to execute (e.g., 0 for the top of the hour).
Hours (0–23): Input the execution hour in 24-hour UTC format (e.g., 13 corresponds to 13:00 UTC / 1:00 PM UTC).
Month (1–12 or JAN–DEC): Define which months the report runner is active. Use an asterisk (*) to evaluate every month consecutively.
Day Context Toggle: Select whether the schedule dictates execution by the date or the day of the week:
Day of the Month: Specify a numerical date (e.g., 1 to run on the first day of every month). You can also use advanced operators such as L (the final day of the current calendar month) or xW (the weekday closest to day x).
Day of the Week: Specify specific days for execution (e.g., MON-FRI) if weekly cadence is preferred.
Preview (UTC Time): A real-time, human-readable translation of your input. Always verify this readout to ensure the engine triggers exactly when intended.
Syntax Reference Cheat Sheet
Asterisk (*): Triggers at any/every increment of that unit.
Hyphen Range (e.g., 2-7): Executes across an inclusive range.
Comma List (e.g., 13-16,4,7-8): Restricts execution to specific individual entries or sub-ranges.
Forward Slash Step (e.g., */2): Defines cyclical intervals (e.g., */2 under minutes translates to "every 2 minutes").
Minimum Days to Report: Enter the minimum historical data window length (in days) required to compile the automated document (e.g., 365).
Once configuration fields are populated, manage the state of your automated report generation using the action buttons:
Submit: Validates and applies the configured reporting data thresholds.
Delete: Wipes the current parameter configurations from the active workspace.
Save Schedule: Commits the current time configurations to the live cron engine. A green confirmation status line will appear directly above, confirming: "A report is currently scheduled: [Your Configuration Info Here]".
Cancel Schedule: Suspends the automated trigger matrix without deleting your underlying threshold inputs.
Mode Shape Visibility: Both Tracked Mode Shapes and AVT Mode Shapes can be toggled on or off (shown or hidden) in the interface, depending on your specific project display requirements.
Shindo Seismic Scale: The system supports the integration of the Shindo Seismic Scale (JMA seismic intensity). This can be optionally selected or deselected based on your local regional reporting requirements.
Note on Analysis Methods: The underlying technical principles and workflows for all available Seismic Analysis Methods are covered extensively in Chapter 2.
The example Building is shown below.
¶ 1.8 Contact
Asset owners are added to this section. The manager of the project will decide whether to add the client’s contact list.
¶ 2. Gateway Commands (Control Panel)
Complete the following configuration sequence immediately after physical hardware installation is finalized. These steps transition the monitoring deployment from an idle installation state to an active, calibrated structural health telemetry stream.
¶ 2.1 Status of the Gateway
Confirm that the deployed hardware gateway displays an Online status within the system control panel dashboard.
¶ 2.2 Expected Sensor List
Execute the Expected Sensor List command. Verify that all deployed sensor nodes register a Green status indicator, confirming a successful data-link layer connection and stable power distribution.
¶ 2.3 Start Measurement
Execute the Start Measurement command to define the baseline acquisition rules and event-triggering thresholds: Trigger Mechanisms: Enable a dual-triggering matrix by selecting both STA/LTA (Short-Term Average / Long-Term Average) and a Fixed Threshold. This dual setup protects against missing high-frequency micro-events while filtering out persistent background harmonic noise.
Threshold Boundaries: The recommended thresholds are as follows:
Acceleration: 5 mg
Velocity: 5 mm/s
Explicitly select the desired sensor channels and sampling frequency (120 Hz or 62 Hz sampling frequency based on the needs of the project.)
Keep the parameters by default, unless decided otherwise by the responsible engineer. Choose 0 for sensor ID to apply to all sensors.
¶ 2.4 Save Data
Capture an initial test dataset, click Save Data, and inspect the incoming waveforms. Verify that the trace is clean by checking specifically for unacceptable signal-to-noise ratios, clipping, or unexpected baseline drift. Automate Routine: Once data quality is verified as good, commit the configuration parameters to the active monitoring Schedule.
The Save Data command automates periodic structural logging during continuous measurements using standard Cron syntax, executing in UTC by default. To activate automation, check Schedule Task and configure your temporal cadence using wildcards (* for any time), ranges, lists, or step intervals.
Range (Using a Hyphen -): A range tells the scheduler to run consecutively from a starting point to an ending point, including every increment in between.
Example (Hours field): 9-12
When it executes: 9:00, 10:00, 11:00, and 12:00. It captures the entire block.
List (Using a Comma ,): A list tells the scheduler to run only at specific, discrete times that you explicitly name, skipping everything else.
Example (Hours field): 9,12
When it executes: 9:00 and 12:00. It completely ignores 10:00 and 11:00.
SSICOV Integration Tip: To enable automatic, continuous Stochastic Subspace Identification (SSICOV), you must set the Sensor ID to 0 to trigger a global broadcast save. To safely feed these automated captures directly into your analytical sandbox for baseline verification, check the Add result to tuning set option.
¶ 2.5 Structural Analysis
Save a tuning set to check your Stochastic Subspace Identification (SSI). Fine-tune your operational modal analysis settings and Submit the SSI parameters to baseline the structure's natural frequencies and mode shapes. Note: For a comprehensive guide on optimizing the system identification matrix, state-space dimensions, and interpreting stabilization diagrams, refer to the next chapter (SSI Analysis ).
¶ 2.6 Voting Parameters
Execute the Set Voting Parameters command to validate genuine structural events and suppress false alarms caused by localized ambient anomalies. For a comprehensive guide, refer to the vibration event chapter.
¶ Sensor-Local Configuration Guide
The Read or Write Sensor-local Configuration command allows you to read from or write parameters directly to the firmware of an individual sensor node. This control interface is essential for managing hardware-level safeguards and adjusting coordinate systems when physical field constraints prevent a sensor from being mounted in its standard orientation.
Target and Command Execution
Command Dropdown: Select Read or Write Sensor-local Configuration. This tells the gateway to execute direct read/write operations on the designated node's internal register rather than changing global database settings.
Sensor ID: Enter the unique alphanumeric hardware identifier for the specific physical sensor node you intend to configure or query.
Schedule Task: Check this box if you want to queue this operation to execute during the next scheduled hardware wake/sync cycle rather than sending an instantaneous command.
Read / Write Checkboxes: For each parameter below, select Read to poll the sensor's current active onboard setting, or Write to push and overwrite a new value to the sensor's internal memory.
Submit: Click this button to transmit or queue the command packet.
Vibration Data Rotations: This parameter maps the physical sensor's local coordinate axes to the global structural model axes. If field conditions require a sensor to be physically installed sideways or upside down, you must apply an orthogonal rotation adjustment here to correct the data stream.
If a sensor is rotated on-site, configure the rotation parameter to match the physical orientation adjustment. This interface allows you to apply a standard three-dimensional coordinate transformation matrix to map the sensor's physical local axes (x, y, z) directly to the global structural model coordinate system (X, Y, Z). This is critical when field installation constraints require a sensor to be mounted off-axis, on a sloped structural member, or rotated orthogonally.
The software utilizes a standard right-hand rule convention for intrinsic orthogonal rotations. Ensure all angles are evaluated relative to the unrotated, nominal position of the sensor body.
Yaw (Rotation in the xy plane, around the z+ axis):
Description: Represents the horizontal angular rotation around the vertical axis.
Pitch (Rotation in the xz plane, around the y+ axis):
Description: Represents the vertical tilt or inclination along the sensor's longitudinal axis.
Roll (Rotation in the yz plane, around the x+ axis):
Description: Represents the rotational twist around the sensor’s lateral axis.
Step-by-Step Rotation Sync Workflow
Measure Onsite Matrix: Check the physical installation using a digital protractor or laser survey tool to record deviations along all three axes relative to the structural blueprints.
Input Angles: Select the required angle from the dropdown menus (e.g., 0°, 90°, 180°, 270°, or specific custom angular offsets).
Check the 'Write' Box: Ensure the Write checkbox next to Vibration data rotations is explicitly checked.
Submit to Firmware: Click Submit. The gateway will push the transformation angles to the sensor's onboard register, ensuring data streams are transformed at the hardware level prior to database ingestion.
Failure to apply correct rotations will cause cross-contamination of directional data, invalidating subsequent inter-story drift calculations, modal analysis vector directions, and automated structural health response mapping.
Thermistor Present: Toggle this parameter based on the physical configuration of your node. Select Write with this active if the sensor body is equipped with an internal or external thermistor for recording ambient structural temperatures. This enables simultaneous thermal-vibration correlation studies (e.g., tracking thermal frequency shifts). Turn it off if a thermistor is absent to minimize power consumption and prevent null data logging errors.
TX Activity Watchdog Delay (s): Sets the hardware transmission watchdog timeout interval in seconds. If the sensor's radio or communication stack freezes for longer than this duration during transmission activities, the onboard watchdog will automatically trigger a hard reset of the node's communication interface to restore telemetry.
Command Execution & Tracking
Control Panel: This interface is utilized exclusively for sending commands to the system. Outbound actions are initiated here, but command history is not displayed within this view.
Query Tab: To monitor, track, or view the status of previously submitted commands, click on the Query tab located directly adjacent to the Control Panel.
¶ 3. SSI Analysis (Control Panel)
The objective of this step is to define the set of SSI parameters to be used for real-time SSI analysis. An optimal parameter configuration should be selected to maximize the identification and tracking of the largest possible number of modes. In this context, particular emphasis must be placed on ensuring the reliable identification and continuous tracking of the fundamental modes, as they are critical to the structural characterization.
There are three steps for implementing SSI: Preprocessing, SVD Computation, and Modal Analysis.
¶ Preprocessing
The preprocessing step allows users to select the data source, apply basic signal processing, and configure preliminary parameters for Cov-SSI. The subsequent steps use this preprocessed data for the SSI calculations. There are two parameters in the Main Settings section. The first parameter, Time Lag, defines the data length used for SSI estimation. The number of data points used to build the Hankel matrix in SSI is calculated as shown in Eq. (1):
Number of data points = Time lag (s) × Sampling frequency. Eq. (1)
The time lag is commonly chosen as 3 to 10 times the period of the target mode. If the time lag is too short, the correlation function may not capture enough information, leading to reduced SSI analysis quality.
Users should note that the Decimation option in the Preprocessing → Signal Processing section affects the sampling frequency. The adjusted sampling frequency is equal to the original sampling frequency divided by the decimation factor.
Number of Singular Values determines how many singular values from the Frequency Domain Decomposition (FDD) are plotted in the final results. Usually 4 singular values are recommended. This plot helps users identify the physical poles in the SSI analysis during later steps.
The Data Channels section allows users to select specific channels for SSI analysis. Three parameters can be adjusted in this section: Channels, Removed Sensor IDs, and Reference Sensors. The Channels parameter offers six options: Vx, Vy, Vz, Ax, Ay, and Az. “V” represents velocity data, while “A” represents acceleration data.
The Removed Sensor IDs option allows users to mute data from specific sensors, which is useful when a sensor malfunctions.
The Reference Sensor option lets users select one or more sensors to serve as references during SSI. Using reference sensors reduces computational effort and thereby accelerates SSI computation.
¶ SVD Computation
After receiving the green message from the previous step, SVD computation can be implemented. This step is straightforward: select the same group as before, and then click the Submit button.
¶ Modal Analysis
The Modal Analysis section computes the system's modes by postprocessing the SVD results. This postprocessing involves two main components: the stability diagram and automated clustering. Parameters for both components can be configured in this section. The Lowest Modal Order and Highest Modal Order define the range of model orders used to generate the stability diagram. The model order indicates the number of largest singular values used for modal estimation. A larger Clustering Threshold Factor results in fewer, larger clusters of modes, while a smaller factor produces more clusters of smaller size.
Before pushing newly adjusted Stochastic Subspace Identification (SSI) parameters live to the physical field gateway, you must first initialize, configure, and verify your workspace using a localized Tuning Set.
¶ Step 1: Initialize and Save the Tuning Set
Baseline Capture: Create and save an initial Tuning Set using a slice of clean, representative raw structural data.
Purpose: Saving this tuning set acts as your analysis baseline. Without a saved tuning set, the platform cannot calculate or preview experimental SSI results (such as stabilization diagrams, natural frequencies, or modal damping ratios).
¶ Step 2: Iterative Step Verification
Step-by-Step Confirmation: As you adjust structural dynamic parameters, you must validate each change against your saved tuning set.
Validation Check: Ensure that the stabilization diagrams display clear, well-aligned pole clusters and that the extracted structural mode shapes conform to expected engineering physics. Do not proceed to the next parameter stage until the current setting is confirmed against the tuning dataset.
¶ Step 3: Final Submission to the Gateway
Parameter Commit: Once every configuration step is completely validated and all modal indicators align with your target tolerances, click Submit Parameters.
Note: Once submission to the gateway is successful, the newly optimized processing algorithms will apply to all incoming telemetry moving forward. Updated analytical graphs, modal frequency trends, and structural stability indices will become visible within the Health Monitoring tab starting with the very next scheduled data ingestion interval.
¶ 4. Tracking Parameters (Health Monitoring)
The health monitoring system tracks structural modes (baseline characteristics of a structure) over time to detect changes or damage. Below is a simplified guide to the settings used to configure this tracking.
¶ Step 1. Basic Mode Identification
Mode ID: A unique label for each structural mode.
Frequency: The vibration frequency of the mode when the structure is undamaged.
Shape: The complex physical movement pattern of the mode. This can be imported from a specialized text file or directly from SSI plots.
¶ Step 2. Tracking Timing & Sensitivity
Start Time: The date and time when tracking begins. Data collected before this point is ignored, which helps exclude noise from initial sensor installation.
Window Capacity: The number of recent data points the algorithm remembers.
Adaptive Tracking: Instead of comparing new data to the original "undamaged" baseline, the system compares it to the average of this "window" to account for natural, gradual changes like temperature.
Size Matters: A small window (e.g., 50 points) follows changes quickly but can be disrupted by noise. A larger window (e.g., 100 points or ~2 days) is more stable against noise but slower to react to changes.
Static Tracking: Set Window Capacity to 0 to compare all new data strictly against the original baseline. This is best for short-term projects.
¶ Step 3. Tolerance (Closeness Criteria)
Tolerance: Defines how "close" a new data point must be to the current average to be included in the track. Points that fall outside this range are rejected.
Default Tolerance: A fixed value used at the very beginning of tracking when there isn't enough data yet to calculate a window average. It is usually set higher to handle initial environmental noise.
Tolerance Factor: A multiplier (default is 1) that fine-tunes the sensitivity of the automated tracking algorithm.
Higher Factor: Better for noisy environments, but risks picking up "bad" data.
Lower Factor: More precise, but might miss good data points if set too low.
To understand the impact of the Tolerance Factor, it helps to think of it as a "filter" that decides which data points are allowed into your structural health records. Since a factor of 1 represents the standard mathematical threshold for noise, moving to extreme highs or lows creates the following scenarios:
The "Open Door" Policy (Extremely High Factor)
If you set a very high tolerance factor (e.g., 5.0 or higher), you are being highly "pessimistic" about the environmental noise, assuming that even wild fluctuations are normal.
The Benefit: The algorithm will almost never lose track of a mode, even during massive storms or heavy traffic events.
The Risk: It creates "dirty" data. The system may begin to pick up spurious SSI points (mathematical ghosts or artifacts that aren't actually part of the structure's behavior) and treat them as real health data. This can mask actual structural damage because the average becomes "diluted" by garbage points.
The "Elite Club" Policy (Extremely Low Factor)
If you set an extremely low factor (e.g., 0.1 or 0.2), you are telling the algorithm that the structure is perfectly stable, and any deviation is unacceptable.
The Benefit: The data you do collect will be incredibly "clean" and precise, representing only the most stable modal properties.
The Risk: You will likely suffer from massive gaps in your monitoring. Even minor, harmless environmental changes (like a sunny day warming the concrete) might cause the frequency to shift just enough to be rejected by the algorithm. The system will essentially "stop" tracking the mode because no new points are "perfect" enough to meet the criteria.
Table 1- Tolerance factors explanation
| Feature | Low Factor (Extreme) | High Factor (Extreme) |
| Data Quality | Extremely clean, but very sparse. | High volume, but noisy/unreliable. |
| Sensitivity | Over-sensitive; rejects good data. | Under-sensitive; accepts "bad" data. |
| Best Use Case | Laboratory settings with zero outside interference. | Extremely noisy environments (e.g., a bridge with constant heavy rail traffic). |
¶ Example Building:
Note that in this project, the modes are easy to find, and the frequency variations are low, so both MAC and frequency thresholds are chosen strictly (1.25 and 0.25, respectively). These 3 cases are useful examples:
¶ Case 1: Standard Stable Structures (Baseline Configuration)
Structural Conditions: Target modal frequencies are well-separated, easy to isolate, and exhibit low ambient or thermal variation.
Parameter Settings: MAC Tolerance = 1.25 | Frequency Tolerance = 0.25
Engineering Logic: Strict thresholds ensure highly precise tracking and minimize false pole assignments. This is the optimal baseline configuration for most standard monitoring environments.
¶ Case 2: High-Variable Environments
Structural Conditions: The structure undergoes significant frequency shifts due to intense environmental fluctuations (e.g., extreme seasonal temperature changes or variable traffic loads).
Parameter Settings: MAC Tolerance = 1.25 | Frequency Tolerance = [Increased value, e.g., > 0.25]
Engineering Logic: Increasing the frequency tolerance factor prevents the tracking engine from dropping valid structural modes when ambient conditions cause natural frequencies to temporarily drift.
¶ Case 3: Sparse Sensor Deployments (Frequency-Focused Tracking)
Structural Conditions: The project focuses strictly on frequency tracking rather than full mode shape visualization, often due to a limited sensor array (e.g., only 1 or 2 nodes deployed).
Parameter Settings: MAC Tolerance = [High / Maximum value] | Frequency Tolerance = 0.25
Engineering Logic: Setting an intentionally loose or high MAC tolerance effectively neutralizes its impact on the tracking filter. This allows the backend engine to bypass complex mode-shape matching and rely entirely on the strict frequency tolerance to isolate the correct pole.
¶ 5. Gradual Deterioration Detection (Health Monitoring)
This simplified guide covers the Automatic Gradual Deterioration (Damage) Detection features in the Sensequake dashboard, which analyze tracked structural modes to identify potential damage.
¶ 5.1 How Damage is Detected
The system monitors individual modes using specific metrics (like Frequency, Slope, or Curvature). Detection follows these steps:
Windowing: Only recent data points within a specified Window Duration (e.g., the last 30 days) are considered.
Threshold Comparison: Every data point in that window is compared against a threshold.
Triggering: Damage is reported only if a high enough percentage of points in the window exceeds the threshold. This percentage is controlled by the Minimum Triggered Proportion for Detection (a value from 0 to 1).
Data Consistency: To avoid false alarms from sparse data, the Minimum Number of Points in Window setting ensures damage detection only runs if enough successful data points are collected.
¶ 5.2 Key Metrics
¶ Frequency Metric
Behavior: Tracks the resonance frequency of a mode.
Thresholds: Set as a fraction (0 to 1) of the baseline frequency. A trigger occurs if the frequency drops below this value. The thresholds are chosen by the responsible engineer by calculating 98% of the minimum frequency per month.
Seasonality: You can use a Threshold Timeline to set different limits for different times of the year (e.g., summer vs. winter). The threshold can be modified at any time.
¶ Absolute Slope & Curvature
Behavior: Measures physical changes in the mode shape using pairs (Slope) or triplets (Curvature) of nodes.
Setup: You must specify Node IDs (not sensor IDs) in the project settings for these to work.
Dynamic Thresholds: Since these values are complex, the system calculates thresholds based on a "base period" of initial data. It uses the mean and standard deviation to create high and low boundaries.
¶ 5.3. Monitoring Status
You can check the health of your metrics using the icons in the dashboard:
⚪ Gray: Metric is not in use.
Thumbs up: No damage detected.
Triangle: Damage detected.
❌ Red: Setup error (e.g., missing node pairs for slope calculation).
Always click the Commit button after changing parameters. It is also recommended to open the Details Panel (by clicking an icon) to view plots of your data against the active thresholds to ensure your settings are realistic.
To set up the Absolute Slope and Absolute Curvature metrics, you need to define specific geometric relationships between your structural nodes.
¶ Node Setup Requirements
Node IDs: You must use Node IDs from your structure's geometry, not the Sensor IDs.
Project Settings: These pairs or triplets must be defined in the Project Settings page and committed before they appear in the health monitoring tab.
Independent Detection: The system performs damage detection on each pair or triplet separately; if any one of them triggers a "damage" status, the entire metric for that mode is flagged.
¶ Absolute Slope (Pairs)
This metric looks at how the physical angle between two points on the structure changes over time.
Calculation: The system takes the real mode shape vectors (arrows) from two nodes and projects them onto a 3D plane.
Perpendicular Component: It then extracts the part of that movement perpendicular to the line connecting the two nodes to calculate a "slope".
Absolute Value: The absolute value is used so that 180-degree phase shifts in the data don't create false alarms.
¶ Absolute Curvature (Triplets)
This is used to detect more complex deformations that require three points to define.
Collinearity: To make the math work, the system "rotates" the third node in its calculations so all three points are treated as if they are in a straight line.
Formula: It uses a discrete curvature formula that accounts for different distances between the nodes (e.g., if Node A to B is a different length than B to C).
¶ Setting Your Base Period
Because slope and curvature values are harder to predict than frequency, the system calculates their thresholds dynamically:
Max Base Duration: This is the maximum timeframe at the start of a project used to "learn" what a normal slope/curvature looks like.
Min Base Duration: To ensure the system doesn't guess based on too little data, it will wait until this minimum time has passed before it starts detecting damage.
Standard Deviation Factor: You set a "factor" (multiplier). The threshold becomes the Mean ± (Factor × Standard Deviation) of that base period.
If you see a Red X icon, it usually means you enabled these metrics but forgot to define the node pairs/triplets in the settings.
The damage criteria for the Example Building is shown below.
¶ 6. Seismic and Vibration Events Triggering and Reporting (Control Panel)
This section provides an overview of the workflow required to configure automated event-based reporting. It details the customizable parameters available for tailoring report outputs and explains the engineering logic used to classify and generate these documents.
The platform distinguishes between transient structural shocks and continuous environmental disturbances by utilizing two distinct automated report types:
¶ Seismic Report (Acceleration-Based)
Primary Telemetry: Accelerometer data.
Engineering Objective: Triggered by high-amplitude, transient dynamic events (e.g., earthquakes, severe structural impacts).
Analytical Outputs: This report prioritizes engineering demand parameters such as Peak Ground Acceleration (PGA), Peak Floor Acceleration (PFA), pseudo-spectral acceleration (PSA) response spectra, and automated HAZUS/FEMA P-58 damage estimations.
¶ Vibration Event Report (Velocity-Based)
Primary Telemetry: Velocimeter data.
Engineering Objective: Triggered by continuous, intermittent, or cyclic structural disturbances (e.g., adjacent construction blasting, heavy machinery operation, deep excavation transit).
Analytical Outputs: This report evaluates Peak Particle Velocity (PPV) and dominant frequency pairs, mapping them directly against localized regulatory envelopes (such as the Toronto By-law, USBM RI8507, or OSM curves) to audit structural compliance and cosmetic damage risks.
Design Methodology: Segmenting these reports by their baseline physics (acceleration vs. velocity) ensures that processing power, filtering algorithms, and compliance evaluations are perfectly matched to the specific structural hazard being recorded. This eliminates data bloat and delivers concise, actionable compliance documents immediately following a threshold breach.
¶ 6.1 Vibration Event (Acceleration-based)
¶ 6.1.1 Acceleration Alarm Setup
To automate event-driven alerts, you must configure two primary operational parameters. The first of these is the Acceleration Threshold, which is defined when executing the Start Measurement command via the Control Panel on the project dashboard.
The visibility of the Fixed Threshold Acceleration configuration box is context-dependent. It will only appear within the user interface if the Mode dropdown is set to an option that utilizes a static physical limit.
Review the framework below to select the appropriate triggering logic for your monitoring program:
Threshold Triggering: Triggers an alert immediately when the raw acceleration amplitude exceeds a static numerical value. Selecting this mode reveals the fixed threshold input box.
Trigger on STA/LTA or Threshold: A dual-logical OR configuration. The system triggers an event if either the dynamic Short-Term Average/Long-Term Average ratio is exceeded or the static acceleration threshold is breached. Selecting this mode reveals the fixed threshold input box.
Trigger on STA/LTA and Threshold: A restrictive logical AND configuration. An event is only validated if the dynamic STA/LTA envelope and the static physical threshold are breached simultaneously. Selecting this mode reveals the fixed threshold input box.
Note: If the Mode is set to pure STA/LTA Triggering, the Fixed Threshold Acceleration option box will be hidden, as the algorithm will compute alerts based strictly on relative energy ratio shifts rather than a static physical limit.
The second operational parameter required to finalize the event alarm framework is the Acceleration-Based Voting Parameters. Like the threshold triggers, these values are configured directly through the Control Panel. For a comprehensive technical breakdown of how the backend algorithm evaluates these voting arrays to trigger system-wide alert notifications, see the Voting Logic & Spatial Coincidence section below.
¶ 6.1.2 How is an acceleration alarm decided?
As soon as a sensor detects an acceleration over the fixed threshold set during the start command, it sends a signal to the gateway. After receiving this signal, the gateway waits for a short time to give a chance to other sensors that might report a similar acceleration spike. Once this timeout has expired, the gateway then uses the voting parameters to decide whether an alarm has occurred or not. Note that only sensors in the expected list are considered.
For example, say we have 3 sensors in the expected list with IDs [1, 2, 3]. If we use the parameters we set above, consider the following cases -
Sensor [1] registers an acceleration above the threshold:
An alarm is not generated in this instance since sensor 1 did not have enough voting power to pass the minimum proportion of 0.5.
Sensors [1,2] register an acceleration above the threshold:
An alarm is generated in this instance.
Sensor [3] registers an acceleration above the threshold:
An alarm is generated in this instance.
¶
6.1.3 Conditions for a seismic report to be generated
A seismic event report is generated for every acceleration alarm detected by the gateway.
¶
6.1.4 Report Setup
After the alarm generation parameters have been configured, there are a few other things to set up before these alarms can be used to generate reports. These options need to be checked:
- SSICOV parameters set.
- Geometry.
- Set this option in the project settings to “Yes”.
- Complete the contact list.
¶ 6.2 Vibration Event (Velocity-based)
¶ 6.2.1 Velocity Alarm Setup
There are 3 user parameters that the user has to configure to generate these alarms. The first is the velocity threshold, which can be set when selecting the “start measurement” command using the control panel on the dashboard.
Pre-trigger duration should be left blank. It will automatically use the largest possible duration.
The second parameter to set is the velocity-based voting parameters, which can also be set using the control panel, similar to what was explained.
The final parameter to set is the compliance graph. This can be set from the “Compliance” tab in “Project Settings”.
Example: If there are 20 sensors, and the plan is to trigger an event if any of the sensors passes the threshold, “Minimum proportion for alarm” is 0.05 (which is 1/20), and the weights are assigned as 0:1 (same weight to all sensors).
¶ 6.2.2 How is a velocity alarm decided?
Unlike acceleration-based alarms, which are confirmed on the gateway using voting parameters, velocity-based alarms are confirmed immediately without looking at voting parameters. As soon as a sensor detects a velocity over the fixed threshold set during the start command, it sends a signal to the gateway. After receiving this signal, the gateway waits for a short time to give a chance to other sensors that might report a similar velocity spike. Once this timeout has expired, the gateway then simply sends these signals as alarms to the cloud.
¶ 6.2.3 Conditions for a vibration event report to be generated?
Once the cloud receives these alarms from the sensor(s), it uses the velocity data from each sensor around the velocity spike (this length of time is determined by the “Pre Trigger” and “Post Trigger” parameters in the start command) to perform an FFT. It then checks if any of the FFT peaks cross the compliance graph at a point in frequency. If it does, this sensor’s weight will contribute to the voting. The voting is then done to decide whether a report is generated.
For example, say we have 3 sensors in the expected list with IDs [1, 2, 3]. If we use the parameters we set above, consider the following cases:
Sensor [1] registers a velocity above the threshold and an FFT peak above the compliance:
A report is not generated in this instance since sensor 1 did not have enough voting power to pass the minimum proportion of 0.5.
Sensors [1,2] register a velocity above the threshold and an FFT peak above the compliance:
A report is generated in this instance.
Sensor [3] registers a velocity above the threshold and an FFT peak above the compliance:
A report is generated in this instance.
¶ 6.2.4 Report setup
After the alarm generation parameters have been configured, there are a few other things to set up before these alarms can be used to generate reports. These options need to be checked:
- Geometry.
- Set this option from the project settings to “Yes”
- Complete the contact list.
¶ Automated Structural Health Scenarios & Reporting Logic
To streamline asset management and ease the decision-making process for asset owners, the platform automatically evaluates incoming data against established baseline thresholds. Depending on the structural state detected within the selected evaluation window, the system categorizes the asset into one of three operational scenarios and issues corresponding report strings.
¶ Scenario 1: Nominal State (Healthy / No Breaches)
Condition Matrix: No damage thresholds are breached within the selected evaluation window.
Action: A Condition Assessment Report is not generated.
Monthly Health Report Readout: > "The structure is exhibiting its expected behavior."
¶ Scenario 2: Transient Breach (Resolved Within Cycle)
Condition: One or more damage criteria thresholds were breached during the evaluation window (prompting an automated condition assessment report), but all criteria returned to nominal baseline prior to the end of the monthly reporting cycle.
Action: A Condition Assessment Report is generated alongside the monthly summary to document the temporary anomaly.
Monthly Health Report Readout: > "The structure has breached one or more thresholds last month but went back to normal afterwards. The structure is exhibiting its expected behavior now."
Condition Assessment Report Readout (Context-Dependent):
For Global Frequency Drops: > "The structure has breached one or more thresholds over the past [x] days. Further investigation is recommended."
For Localized Slope / Curvature Deviations: > "The location highlighted in red has breached one or more thresholds within the last [x] days. Further investigation of this area is recommended."
¶ Scenario 3: Active Breach (Ongoing Structural Deviation)
Condition: One or more damage criteria thresholds were breached during the evaluation window, and the criterion remains actively outside the thresholds at the close of the reporting cycle.
Action: A Condition Assessment Report is generated. The structure is still damaged; further investigation is needed.
Monthly Health Report Readout: > "The structure has breached one or more thresholds last month. The structure is not exhibiting its expected behavior. Further investigation is needed."
Condition Assessment Report Readout (Context-Dependent):
For Global Frequency Drops: > "The structure has breached one or more thresholds over the past [x] days. Further investigation is recommended."
For Localized Slope / Curvature Deviations: > "The location highlighted in red has breached one or more thresholds within the last [x] days. Further investigation of this area is recommended."
Engineering Protocol: Structural interventions change the dynamic properties of an asset. Following any structural repair, local remediation, seismic retrofit, or physical sensor repositioning, the responsible structural engineer must manually execute a baseline reset command within the Control Panel. This recalibrates the system's predictive models to the structure's new post-intervention nominal state, preventing false Scenario 3 flags.
¶ 7. Final Step
Based on the needs of a project, the measurements can be reduced to once per day after one month of tracking. The tracking parameters can be adjusted based on the structure's behaviour. The damage thresholds must be fixed after 2 years of tracking.