.. _auto_responses_mapper:

*MAPS RESPONSES*
================

Maps response channel names from physical tests or simulations to canonical destination names using a CSV or database mapping file. Applies optional per-channel x/y scale factors and offsets, and optionally persists the renamed responses back to the database.

When to use
-----------

Tagged: ``channel_rename``, ``csv``, ``mapping``, ``offset``, ``physicaltest``, ``response_mapper``, ``responses``, ``scale_factor``.

Inputs
------

.. list-table::
   :header-rows: 1
   :widths: 20 20 20 20 20 20

   * - Label
     - ID
     - Type
     - Default
     - Required
     - Description
   * - Parent Type
     - parent_type
     - select
     - physicalteste
     - 
     - Selects the source entity type to map — choose 'physicaltest' for physical test records or 'srs' for simulation records; defaults to 'physicaltest'.
   * - Physicaltests
     - physicaltest_id
     - remote_lookup
     - —
     - 
     - One or more physical test record IDs to retrieve response channels from; active when parent_type is 'physicaltest'; repeatable lookup.
   * - Simulation
     - simulation_id
     - remote_lookup
     - —
     - 
     - One or more simulation record IDs to retrieve response channels from; active when parent_type is 'srs' (simulation); repeatable lookup.
   * - Map Source Type
     - map_source_type
     - select
     - file
     - ✓
     - Specifies whether the channel mapping definition is loaded from a flat file ('file') or from a database entry ('database'); required.
   * - Map Database
     - map_database_id
     - file
     - —
     - 
     - Database record reference for the mapping definition; used when map_source_type is 'database'; leave null when using a file.
   * - MFICF
     - map_file
     - file
     - —
     - 
     - CSV mapping file (MFICF format) containing at minimum an expression column and a destination column; used when map_source_type is 'file'.
   * - Expression Header
     - expression_header
     - text
     - Expression
     - 
     - Column header name in the mapping CSV that holds the source channel name pattern or expression; defaults to 'Expression'.
   * - Destination Header
     - destination_header
     - text
     - Destination
     - 
     - Column header name in the mapping CSV that holds the target canonical channel name; defaults to 'Destination'.
   * - Map Channel Expression
     - include_expression
     - textarea
     - —
     - 
     - Optional Python/filter expression evaluated per channel row; the channel is mapped only when this expression returns true; leave blank to map all matched channels.
   * - X-Scale Factor Header
     - xsf_header
     - scalar
     - x_sf
     - 
     - Column header in the mapping CSV that contains the x-axis scale factor to apply to each mapped channel; defaults to 'x_sf'.
   * - Y-Scale Factor Header
     - ysf_header
     - scalar
     - y_sf
     - 
     - Column header in the mapping CSV that contains the y-axis scale factor to apply to each mapped channel; defaults to 'y_sf'.
   * - X-Offset
     - xoff_header
     - scalar
     - x_off
     - 
     - Column header in the mapping CSV that contains the x-axis offset to apply to each mapped channel; defaults to 'x_off'.
   * - Y-Offset
     - yoff_header
     - scalar
     - y_off
     - 
     - Column header in the mapping CSV that contains the y-axis offset to apply to each mapped channel; defaults to 'y_off'.
   * - Update Responses Name
     - save_db
     - select
     - no
     - ✓
     - Controls whether the mapped (renamed) response names are written back to the database ('yes') or kept in-memory only ('no'); defaults to 'no'.

Outputs
-------

.. list-table::
   :header-rows: 1
   :widths: 20 20 20 20

   * - Label
     - ID
     - Type
     - Description
   * - Num Mapped
     - num_mapped
     - integer
     - Integer count of response channels that were successfully matched and mapped to a destination name.
   * - Num Unmapped
     - num_unmapped
     - integer
     - Integer count of response channels that could not be matched to any mapping rule and were left unmapped.
   * - Policies
     - policies
     - dataset
     - Dataset containing the resolved mapping rules (expression → destination, scale factors, offsets) that were applied during this run.
   * - Mapped Data
     - mapped_data
     - dataset
     - Dataset of the raw response records that were matched by at least one mapping rule, before renaming is applied.
   * - Unmapped Data
     - unmapped_data
     - dataset
     - Dataset of response records that did not match any mapping rule, useful for auditing coverage gaps.
   * - Mapped Responses
     - mapped_responses
     - dataset
     - Dataset of response records after renaming and scale/offset transformations have been applied; primary output for downstream processing.
   * - Physicaltest Id
     - physicaltest_id
     - integer
     - Passthrough integer ID of the physical test record(s) processed; populated when parent_type is 'physicaltest'.
   * - Simulation Id
     - simulation_id
     - integer
     - Passthrough integer ID of the simulation record(s) processed; populated when parent_type is 'srs'.
   * - Logs
     - logs
     - dataset
     - Dataset of per-channel mapping log entries detailing match outcomes, rules applied, and any warnings or errors encountered.
   * - Elapsed
     - elapsed
     - integer
     - Wall-clock execution time of the mapping operation in milliseconds, useful for performance monitoring in large-scale workflows.

Disciplines
-----------

- cae.postprocessing.response
- data.curve.transform
- data.dataset.transform
- data.io.csv

.. raw:: html

   <hr style="margin-top:2em">
   <p style="font-size:11px;color:#888">
   Auto-generated from <code>platform</code> schema. Worker id: <code>responses_mapper</code>. Schema hash: <code>6387bf646bc7</code>. Hand-curated docs in <code>workerexamples/</code> override this page when present.
   </p>