%YAML 1.1
---
$schema: "http://stsci.edu/schemas/yaml-schema/draft-01"
id: "http://stsci.edu/schemas/asdf/transform/remap_axes-1.4.0"
title: >
  Reorder, add and drop axes.

description: |
  This transform allows the order of the input axes to be shuffled and
  returned as the output axes.

  It is a list made up of integers.  Each item
  in the list corresponds to an output axis. Each item is the index of
  the input axis to send to the output axis.

  If an object with `mapping` and `n_inputs` properties is provided, the
  number of input axes is explicitly set by the `n_inputs` value.
  If only a list is provided, the number of input axes is
  automatically determined from the maximum index in the list.

  Invertibility: This transform does not have a general analytical inverse.
  In some well defined cases it is possible to invert automatically

examples:
  -
    - For 2 input axes, swap the axes
    - asdf-standard-1.6.0
    - |
        !transform/remap_axes-1.4.0
          mapping: [1, 0]
  -
    - For 2 input axes, return the second axis and drop the first
    - asdf-standard-1.6.0
    - |
        !transform/remap_axes-1.4.0
          mapping: [1]

  -
    - For 2 input axes, return the first axis twice, followed by the second
    - asdf-standard-1.6.0
    - |
        !transform/remap_axes-1.4.0
          mapping: [0, 0, 1]

  -
    - |
        The above example is equivalent to the following, and ASDF
        implementations are free to normalize it thusly:
    - asdf-standard-1.6.0
    - |
        !transform/concatenate-1.3.0
          forward:
            - !transform/remap_axes-1.4.0
              mapping: [0]
            - !transform/remap_axes-1.4.0
              mapping: [1]

  -
    - Here we have 3 input axes, but we are explicitly dropping the last one
    - asdf-standard-1.6.0
    - |
        !transform/remap_axes-1.4.0
          mapping: [0, 1]
          n_inputs: 3

definitions:
  mapping:
    type: array
    items:
      type: integer

allOf:
  - $ref: "transform-1.3.0"
  - properties:
      n_inputs:
        description: |
          Explicitly set the number of input axes.  If not provided,
          it is determined from the maximum index value in the
          mapping list.
        type: integer
      mapping:
        $ref: "#/definitions/mapping"
    required: [mapping]
...
