GwyScatter: Gwyddion Library Reference Manual

## GwyScatter GwyScatter — Irregular two-dimensional data |

## Functions

gboolean | (*GwyScatterFilterFunc) ()
gint | (*GwyScatterCompareFunc) ()
GwyScatter * | gwy_scatter_new ()
GwyScatter * | gwy_scatter_new_sized ()
GwyScatter * | gwy_scatter_new_from_data ()
GwyScatter * | gwy_scatter_new_from_xyz ()
GwyScatter * | gwy_scatter_new_alike ()
GwyScatter * | gwy_scatter_new_part ()
gint | gwy_scatter_get_n_values ()
GwyXY * | gwy_scatter_get_xy ()
const GwyXY * | gwy_scatter_get_xy_const ()
gdouble * | gwy_scatter_get_data ()
const gdouble * | gwy_scatter_get_data_const ()
gdouble * | gwy_scatter_pack ()
gsize | gwy_scatter_get_n_points ()
void | gwy_scatter_copy_data ()
void | gwy_scatter_invalidate ()
void | gwy_scatter_xy_changed ()
void | gwy_scatter_data_changed ()
GwyScatter * | gwy_scatter_copy ()
void | gwy_scatter_assign ()
void | gwy_scatter_set_from_field ()
void | gwy_scatter_set_from_field_area ()
void | gwy_scatter_set_from_packed ()
void | gwy_scatter_set_data_label ()
const gchar * | gwy_scatter_get_data_label ()
gint | gwy_scatter_find_data_by_label ()
void | gwy_scatter_clear_data_labels ()
GwyUnit * | gwy_scatter_get_unit_xy ()
GwyUnit * | gwy_scatter_get_unit_data ()
GwyValueFormat * | gwy_scatter_get_value_format_xy ()
GwyValueFormat * | gwy_scatter_get_value_format_data ()
void | gwy_scatter_copy_units ()
void | gwy_field_copy_units_to_scatter ()
void | gwy_scatter_copy_units_to_field ()
void | gwy_scatter_xrange ()
void | gwy_scatter_yrange ()
void | gwy_scatter_min_max ()
void | gwy_scatter_multiply ()
void | gwy_scatter_add ()
void | gwy_scatter_scale_xy ()
const gdouble * | gwy_scatter_get_xy_full ()
void | gwy_scatter_set_xy_full ()
const gdouble * | gwy_scatter_get_data_full ()
void | gwy_scatter_set_data_full ()
GwyScatter * | gwy_scatter_new_reduced_points ()
void | gwy_scatter_reduce_points ()
void | gwy_scatter_resize ()
gsize | gwy_scatter_filter ()
GwyScatter * | gwy_scatter_new_filtered ()
gsize | gwy_scatter_reduce_to_subset ()
GwyScatter * | gwy_scatter_new_subset ()
void | gwy_scatter_sort ()
void | gwy_scatter_sort_by_value ()
void | gwy_scatter_stack ()
void | gwy_scatter_insert_values ()
void | gwy_scatter_remove_values ()

## Signals

void | data-changed | Run First
void | xy-changed | Run First

## Types and Values

struct | GwyScatter
struct | GwyScatterClass

## Object Hierarchy

        GObject
        ╰── GwyScatter

## Implemented Interfaces

GwyScatter implements GwySerializable.

## Includes

    #include <libgwyddion/gwyddion.h>

## Description

GwyScatter represents general, i.e. possibly unevenly spaced, two-dimensional data, also called XYZ data. Each point has X and Y coordinates, and then any number of data values, including none (representing just a set of coordinates in the plane). Nevertheless, the number of data values is uniform over all the points. Unlike images (GwyField or GwyNield), scattered data can also be empty, i.e. contain zero points.

Many functions take a value index, usually denoted `i` , and operate on the `i` -th value in each point.

## Functions

### GwyScatterFilterFunc()

    gboolean
    (*GwyScatterFilterFunc) (const GwyXY *xy,
                             const gdouble *values,
                             gpointer user_data);

Type of scattered data filtering function.

Retrurns: `TRUE` to keep the point; `FALSE` to discard it.

#### Parameters

xy | Pointer to the XY coordinates of the point. |
values | Pointer to the array of all values for the point. |
user_data | User data passed to the driver function. | [closure]

### GwyScatterCompareFunc()

    gint
    (*GwyScatterCompareFunc) (const gdouble *xydataa,
                              const gdouble *xydatab,
                              gpointer user_data);

Type of scattered data sorting function.

Both `xydataa` and `ydatab` are packed blocks of nvalues+2 doubles, with XY first, followed by all data values for the point. The format is the same as in `gwy_scatter_pack()` and `gwy_scatter_set_from_packed()`.

Retrurns: Negative value if a < b; zero if a = b; positive value if a > b.

#### Parameters

xydataa | Coordinates and values of point a. |
xydatab | Coordinates and values of point b. |
user_data | User data passed to the driver function. | [closure]

### gwy_scatter_new()

    GwyScatter *
    gwy_scatter_new (gint nvalues);

Creates a new empty scattered data.

The scattered data will not contain any points. Usually, `gwy_scatter_new_from_data()` is more useful.

[constructor]

#### Parameters

nvalues | The number of data values per point (excluding XY coordinates). |

#### Returns

A newly created scattered data.

[transfer full]

### gwy_scatter_new_sized()

    GwyScatter *
    gwy_scatter_new_sized (gint nvalues,
                           gsize n);

Creates a new scattered data with a preallocated size.

The scattered data will contain the speficied number of points with uninitialised (undefined) content.

#### Parameters

nvalues | The number of data values per point (excluding XY coordinates). |
n | Number of points. |

#### Returns

A newly created scattered data.

[transfer full]

### gwy_scatter_new_from_data()

    GwyScatter *
    gwy_scatter_new_from_data (const GwyXY *points,
                               const gdouble *data,
                               gint nvalues,
                               gsize n);

Creates a new single-value scattered data, filling it with provided coordinates and data.

The data are passed as a single flat array, indexed first by value (outer index), then by point (inner index).

#### Parameters

points | Array of `n` XY coordinates for the scattered data. |
data | Array of `n` ×`nvalues` data values with the data values. |
nvalues | The number of data values per point (excluding XY coordinates). |
n | Number of points. |

#### Returns

A newly created scattered data.

[transfer full]

### gwy_scatter_new_from_xyz()

    GwyScatter *
    gwy_scatter_new_from_xyz (const GwyXYZ *xyz,
                              gsize n);

Creates a new single-value scattered data, filling it with provided XYZ data.

The X and Y parts of `xyz` will become the coordinatres and Z will become the value.

#### Parameters

xyz | Array of `n` points with the scattered data. | [array length=n]
n | Number of points. |

#### Returns

A newly created scattered data.

[transfer full]

### gwy_scatter_new_alike()

    GwyScatter *
    gwy_scatter_new_alike (GwyScatter *model);

Creates a new empty scattered data similar to another scattered data.

The number of values per point and their units of the new scattered data will be identical to those of `model` but the new scattered data will not contain any points. Use `gwy_scatter_copy()` to completely duplicate scattered data including points and values.

#### Parameters

model | A scattered data to use as the template. |

#### Returns

A newly created scattered data.

[transfer full]

### gwy_scatter_new_part()

    GwyScatter *
    gwy_scatter_new_part (GwyScatter *scatter,
                          gdouble xfrom,
                          gdouble xto,
                          gdouble yfrom,
                          gdouble yto);

Creates a new scattered data as a part of another scattered data.

The new scattered data consits of data with lateral coordinates within the specified ranges (inclusively). It may be empty.

Data are physically copied, i.e. changing the new scattered data does not change `scatter` 's data and vice versa.

#### Parameters

scatter | A scattered data. |
xfrom | Minimum x-coordinate value. |
xto | Maximum x-coordinate value. |
yfrom | Minimum y-coordinate value. |
yto | Maximum y-coordinate value. |

#### Returns

A newly created scattered data.

[transfer full]

### gwy_scatter_get_n_values()

    gint
    gwy_scatter_get_n_values (GwyScatter *scatter);

Reports the number of values per point in scattered data.

#### Parameters

scatter | A scattered data. |

#### Returns

The number of values per point.

### gwy_scatter_get_xy()

    GwyXY *
    gwy_scatter_get_xy (GwyScatter *scatter);

Gets one raw value array of a scattered data.

The returned array contains `gwy_scatter_get_n_points()` data values which can directly modified. It is owned by `scatter` and is not guaranteed to be valid through it data life time, only until it changes.

This function invalidates any cached information, use `gwy_scatter_get_xy_const()` if you are not going to change the data. See `gwy_scatter_invalidate()` for some discussion.

#### Parameters

scatter | A scattered data. |

#### Returns

The array with XY point coordinates.

### gwy_scatter_get_xy_const()

    const GwyXY *
    gwy_scatter_get_xy_const (GwyScatter *scatter);

Gets one raw value array of a scattered data, read-only.

The returned array contains `gwy_scatter_get_n_points()` coordinates. It is owned by `scatter` and is not guaranteed to be valid through it data life time, only until it changes.

Use `gwy_scatter_get_xy()` if you want to to change the data. See `gwy_scatter_invalidate()` for some discussion.

#### Parameters

scatter | A scattered data. |

#### Returns

The array with XY point coordinates.

### gwy_scatter_get_data()

    gdouble *
    gwy_scatter_get_data (GwyScatter *scatter,
                          gint i);

Gets one raw value array of a scattered data.

The returned array contains `gwy_scatter_get_n_points()` data values which can directly modified. It is owned by `scatter` and is not guaranteed to be valid through it data life time, only until it changes.

This function invalidates any cached information, use `gwy_scatter_get_data_const()` if you are not going to change the data. See `gwy_scatter_invalidate()` for some discussion.

#### Parameters

scatter | A scattered data. |
i | Index of a value in `scatter` . |

#### Returns

The array with `i` -th scattered data values.

### gwy_scatter_get_data_const()

    const gdouble *
    gwy_scatter_get_data_const (GwyScatter *scatter,
                                gint i);

Gets one raw value array of a scattered data, read-only.

The returned array contains `gwy_scatter_get_n_points()` data values. It is owned by `scatter` and is not guaranteed to be valid through it data life time, only until it changes.

Use `gwy_scatter_get_data()` if you want to to change the data. See `gwy_scatter_invalidate()` for some discussion.

#### Parameters

scatter | A scattered data. |
i | Index of a value in `scatter` . |

#### Returns

The array with `i` -th scattered data values.

### gwy_scatter_pack()

    gdouble *
    gwy_scatter_pack (GwyScatter *scatter,
                      gint i);

Packs scattered data by point into a new array.

The scattered data are normally organised by value planes. If you need to transform them to a form organised by point, this function does such transformation.

When `i` is non-negative, the returned flat array consists of value triplets x, y, v_i. When `i` is negative, the array always contains x, y and then all the values for the correspoinding point.

See also `gwy_scatter_set_from_packed()` which takes data in the packed format a uses them to fill `scatter` .

#### Parameters

scatter | A scattered data. |
i | Index of a value in `scatter` , or -1 for all values. |

#### Returns

The array with packed data values, to be freed with `g_free()`.

[transfer full]

### gwy_scatter_get_n_points()

    gsize
    gwy_scatter_get_n_points (GwyScatter *scatter);

Gets the number of points in a scattered data.

#### Parameters

scatter | A scattered data. |

#### Returns

The number of points.

### gwy_scatter_copy_data()

    void
    gwy_scatter_copy_data (GwyScatter *scatter,
                           GwyScatter *target);

Copies the data of a scattered data to another scattered data of the same dimensions.

Only the data points are copied. Both the number of points and number of values per point must match. To make a scattered data completely identical to another, including resizing and chanding units or labels, you can use `gwy_scatter_assign()`.

#### Parameters

scatter | Source scattered data. |
target | Destination scattered data. |

### gwy_scatter_invalidate()

    void
    gwy_scatter_invalidate (GwyScatter *scatter);

Invalidates cached scattered data statistics.

Cached statistics include ranges returned by `gwy_scatter_xrange()`, `gwy_scatter_yrange()` and `gwy_scatter_min_max()`, the fingerprint for `gwy_scatter_xy_is_compatible()` and and possibly other characteristics in the future.

See `gwy_field_invalidate()` for discussion of invalidation and examples.

#### Parameters

scatter | A scattered data. |

### gwy_scatter_xy_changed()

    void
    gwy_scatter_xy_changed (GwyScatter *scatter);

Emits signal GwyScatter::xy-changed on a scattered data.

If you change both coordinates and data, you should also emit GwyScatter::data-changed.

#### Parameters

scatter | A scattered data. |

### gwy_scatter_data_changed()

    void
    gwy_scatter_data_changed (GwyScatter *scatter);

Emits signal GwyScatter::data-changed on a scattered data.

If you change both coordinates and data, you should also emit GwyScatter::xy-changed.

#### Parameters

scatter | A scattered data. |

### gwy_scatter_copy()

    GwyScatter *
    gwy_scatter_copy (GwyScatter *scatter);

Create a new XYZ scattered data as a copy of an existing one.

This function is a convenience `gwy_serializable_copy()` wrapper.

#### Parameters

scatter | A XYZ scattered data to duplicate. |

#### Returns

A copy of the XYZ scattered data.

[transfer full]

### gwy_scatter_assign()

    void
    gwy_scatter_assign (GwyScatter *destination,
                        GwyScatter *source);

Makes one XYZ scattered data equal to another.

This function is a convenience `gwy_serializable_assign()` wrapper.

#### Parameters

destination | Target XYZ scattered data. |
source | Source XYZ scattered data. |

### gwy_scatter_set_from_field()

    void
    gwy_scatter_set_from_field (GwyScatter *scatter,
                                GwyField *field);

Fills the data of a scattered data from a data field.

The number of points in the new scattered data will be equal to the number of points in the field. Lateral coordinates will be equal to the corresponding `field` coordinates; values will be created in regular grid according to `field` 's physical size and offset.

Lateral and value units will correspond to `field` 's units. This means the field needs to have identical `x` and `y` units.

#### Parameters

scatter | A scattered data. |
field | A two-dimensional data field. |

### gwy_scatter_set_from_field_area()

    void
    gwy_scatter_set_from_field_area (GwyScatter *scatter,
                                     GwyField *field,
                                     GwyNield *mask,
                                     GwyMaskingType masking,
                                     gint col,
                                     gint row,
                                     gint width,
                                     gint height);

Fills the data of a scattered data from a data field, possibly using masking.

#### Parameters

scatter | A scattered data. |
field | A two-dimensional data field. |
mask | Mask of pixels to include from/exclude, or `NULL`. | [nullable]
masking | Masking mode to use. |
col | Column index. |
row | Row index. |
width | Area width (number of columns). |
height | Area height (number of rows) |

### gwy_scatter_set_from_packed()

    void
    gwy_scatter_set_from_packed (GwyScatter *scatter,
                                 const gdouble *data,
                                 gint nvalues,
                                 gsize n);

Fills a scattered data from packed values.

The data format is the same as what `gwy_scatter_pack()` creates, i.e. it is grouped by point, not by value planes. For single-valued data, you can also type-cast GwyXYZ to gdouble* and pass it as `data` .

The scattered data object is resized to match `nvalues` and `n` . Units and labels are kept (for the minimum of old and new `nvalues` ). However, if you change the number of values, usually all the units and labels need to be updated.

#### Parameters

scatter | A scattered data. |
data | Array of `n` ×(`nvalues` + 2) data values with XY coordinates and data values. |
nvalues | The number of data values per point (excluding XY coordinates). |
n | Number of points. |

### gwy_scatter_set_data_label()

    void
    gwy_scatter_set_data_label (GwyScatter *scatter,
                                gint i,
                                const gchar *label);

Sets the label of a value in scattered data.

All values can be either unlabelled or labelled. When they are unlabelled and you set the first label, all others automatically get a label (‘Unknown’, ‘Value 1’ or similar).

#### Parameters

scatter | A scattered data. |
i | Index of a value in `scatter` . |
label | New value label. |

### gwy_scatter_get_data_label()

    const gchar *
    gwy_scatter_get_data_label (GwyScatter *scatter,
                                gint i);

Gets the label of a value in a scattered data.

#### Parameters

scatter | A scattered data. |
i | Index of a value in `scatter` . |

#### Returns

Value label, as a string owned by `scatter` . It may be `NULL`.

[nullable]

### gwy_scatter_find_data_by_label()

    gint
    gwy_scatter_find_data_by_label (GwyScatter *scatter,
                                    const gchar *label);

Finds the first value in scattered data matching a label.

It is possible to pass `NULL` as `label` . It can find anything only if all values are unlabelled, and in such case it will return the first value index (provided there are any values). Hence, it is not particularly useful.

#### Parameters

scatter | A scattered data. |
label | Value label to find. | [nullable]

#### Returns

The value index if found, a negative value (-1) if not found.

### gwy_scatter_clear_data_labels()

    void
    gwy_scatter_clear_data_labels (GwyScatter *scatter);

Completely removes all data labels in a scattered data.

The scattered data revert to a clean state when `gwy_scatter_get_data_label()` returns `NULL` for all values. See `gwy_scatter_set_data_label()` for a discussion.

#### Parameters

scatter | A scattered data. |

### gwy_scatter_get_unit_xy()

    GwyUnit *
    gwy_scatter_get_unit_xy (GwyScatter *scatter);

Returns lateral SI unit of a scattered data.

The returned object can be modified to change the scattered data coordinate units.

#### Parameters

scatter | A scattered data. |

#### Returns

SI unit corresponding to the lateral (XY) dimensions of the scattered data. Its reference count is not incremented.

[transfer none]

### gwy_scatter_get_unit_data()

    GwyUnit *
    gwy_scatter_get_unit_data (GwyScatter *scatter,
                               gint i);

Returns a value SI unit of a scattered data.

The returned object can be modified to change the scattered data value units.

#### Parameters

scatter | A scattered data. |
i | Index of a value in `scatter` . |

#### Returns

SI unit corresponding to the `i` -th value of the scattered data. Its reference count is not incremented.

[transfer none]

### gwy_scatter_get_value_format_xy()

    GwyValueFormat *
    gwy_scatter_get_value_format_xy (GwyScatter *scatter,
                                     GwyUnitFormatStyle style,
                                     GwyValueFormat *format);

Finds value format good for displaying coordinates of a scattered data.

#### Parameters

scatter | A scattered data. |
style | Unit format style. |
format | A SI value format to modify, or `NULL` to allocate a new one. | [nullable]

#### Returns

The value format. If `format` is `NULL`, a newly allocated format is returned, otherwise (modified) `format` itself is returned.

### gwy_scatter_get_value_format_data()

    GwyValueFormat *
    gwy_scatter_get_value_format_data (GwyScatter *scatter,
                                       gint i,
                                       GwyUnitFormatStyle style,
                                       GwyValueFormat *format);

Finds value format good for displaying values of a scattered data.

#### Parameters

scatter | A scattered data. |
i | Index of a value in `scatter` . |
style | Unit format style. |
format | A SI value format to modify, or `NULL` to allocate a new one. | [nullable]

#### Returns

The value format. If `format` is `NULL`, a newly allocated format is returned, otherwise (modified) `format` itself is returned.

### gwy_scatter_copy_units()

    void
    gwy_scatter_copy_units (GwyScatter *scatter,
                            GwyScatter *target);

Sets lateral and value units of a scattered data to match another scattered data.

#### Parameters

scatter | A scattered data. |
target | Target scattered data with the same number of data values. |

### gwy_field_copy_units_to_scatter()

    void
    gwy_field_copy_units_to_scatter (GwyField *field,
                                     GwyScatter *scatter,
                                     gint i);

Sets lateral and value units of a scattered data to match a data field.

Latera units are set always. Value index `i` determines which value units to copy from the field.

#### Parameters

field | A two-dimensional data field. |
scatter | A scattered data. |
i | Index of a value in `scatter` . It can be negative to copy only lateral units. |

### gwy_scatter_copy_units_to_field()

    void
    gwy_scatter_copy_units_to_field (GwyScatter *scatter,
                                     gint i,
                                     GwyField *field);

Sets lateral and value units of a data field to match a scattered data.

Value index `i` determines which value units to copy to the field.

#### Parameters

scatter | A scattered data. |
i | Index of a value in `scatter` . It can be negative to only copy lateral units. |
field | A two-dimensional data field. |

### gwy_scatter_xrange()

    void
    gwy_scatter_xrange (GwyScatter *scatter,
                        gdouble *min,
                        gdouble *max);

Gets the range of X coordinates of an XYZ scattered data.

This information is cached.

#### Parameters

scatter | A scattered data. |
min | Location where to store the minimum value. | [out]
max | Location where to store the maximum value. | [out]

### gwy_scatter_yrange()

    void
    gwy_scatter_yrange (GwyScatter *scatter,
                        gdouble *min,
                        gdouble *max);

Gets the range of Y coordinates of an XYZ scattered data.

This information is cached.

#### Parameters

scatter | A scattered data. |
min | Location where to store the minimum value. | [out]
max | Location where to store the maximum value. | [out]

### gwy_scatter_min_max()

    void
    gwy_scatter_min_max (GwyScatter *scatter,
                         gint i,
                         gdouble *min,
                         gdouble *max);

Gets the range of one value in a scattered data.

This information is cached.

#### Parameters

scatter | A scattered data. |
i | Index of a value in `scatter` . |
min | Location where to store the minimum value. | [out]
max | Location where to store the maximum value. | [out]

### gwy_scatter_multiply()

    void
    gwy_scatter_multiply (GwyScatter *scatter,
                          gint i,
                          gdouble value);

Multiplies values in a scattered data by given constant.

#### Parameters

scatter | A scattered data. |
i | Index of a value in `scatter` . |
value | The value to multiply all data with. |

### gwy_scatter_add()

    void
    gwy_scatter_add (GwyScatter *scatter,
                     gint i,
                     gdouble value);

Adds a constant to values in a scattered data.

#### Parameters

scatter | A scattered data. |
i | Index of a value in `scatter` . |
value | The value to add to all data. |

### gwy_scatter_scale_xy()

    void
    gwy_scatter_scale_xy (GwyScatter *scatter,
                          gdouble xfactor,
                          gdouble yfactor,
                          gdouble xoffset,
                          gdouble yoffset);

Rescales and/or shifts all X and Y coordinates of an XYZ scattered data.

The multiplicative factors are applied before the offsets.

#### Parameters

scatter | A scattered data. |
xfactor | Factor to multiply all X coordinates with. |
yfactor | Factor to multiply all Y coordinates with. |
xoffset | Offset to add to all X coordinates. |
yoffset | Offset to add to all Y coordinates. |

### gwy_scatter_get_xy_full()

    const gdouble *
    gwy_scatter_get_xy_full (GwyScatter *scatter,
                             gsize *n);

Provides the values of an entire coordinates of scattered data as a flat array.

This function, paired with `gwy_scatter_set_xy_full()` can be namely useful in language bindings. In C, `gwy_scatter_get_xy_const()` or `gwy_scatter_get_xy()` is usually fine.

Note that this function returns a pointer directly to `scatter` 's XY data, as a flat array with alternating X and Y values.

#### Parameters

scatter | A scattered data. |
n | Location to store the number of extracted values (twice the number of data points). | [out]

#### Returns

The array containing the scattered data point coordinates.

[array length=n]

### gwy_scatter_set_xy_full()

    void
    gwy_scatter_set_xy_full (GwyScatter *scatter,
                             const gdouble *points,
                             gsize n);

Puts back coordinates from a flat array to scattered data.

If the number of points changes, all data become undefined.

This function, paired with `gwy_scatter_get_xy_full()` can be namely useful in language bindings. In C, you can just use `gwy_scatter_set_xy()` and `gwy_assign()`.

See `gwy_scatter_get_xy_full()` for a discussion.

#### Parameters

scatter | A scattered data. |
points | Coordinates to copy to the scattered data. They will replace whatever points are in `scatter` now. | [array length=n]
n | The number of values in `data` . The number must be even since every point has two coordinates, X and Y. |

### gwy_scatter_get_data_full()

    const gdouble *
    gwy_scatter_get_data_full (GwyScatter *scatter,
                               gint i,
                               gsize *n);

Provides all the data for a single value in scattered data as a flat array.

This function, paired with `gwy_scatter_set_data_full()` can be namely useful in language bindings. In C, `gwy_scatter_get_data_const()` or `gwy_scatter_get_data()` is usually fine.

Note that this function returns a pointer directly to `scatter` 's data.

#### Parameters

scatter | A scattered data. |
i | Index of a value in `scatter` . |
n | Location to store the total count of extracted data values (which is the product of the number of points and the number of values per point). | [out]

#### Returns

The array containing the scattered data points.

[array length=n]

### gwy_scatter_set_data_full()

    void
    gwy_scatter_set_data_full (GwyScatter *scatter,
                               gint i,
                               const gdouble *data,
                               gsize n);

Puts back all the data for a single value in scattered data from a flat array.

See `gwy_scatter_get_data_full()` for a discussion.

#### Parameters

scatter | A scattered data. |
i | Index of a value in `scatter` . |
data | Data values to copy into the scattered data. They will replace whatever values are in `scatter` now. | [array length=n]
n | The number of values in `data` . It must be equal to the product of the number of points. Unlike `gwy_scatter_set_xy_full()`, this function never resizes the scattered data. |

### gwy_scatter_new_reduced_points()

    GwyScatter *
    gwy_scatter_new_reduced_points (GwyScatter *scatter,
                                    gsize n);

Creates a similar scattered data with smaller number of points.

The functions attempts to choose points from the original scattered data to cover its full area, even though points from dense regions are still more likely to be found in the result than points from sparse regions. As the main purpose to enable quick rough operations that may take a long time with the full scattered data, the focus is on speed not fidelity.

The function may employ random selection and thus be be non-deterministic.

#### Parameters

scatter | A scattered data. |
n | Requested number of points in the reduced scattered data. If it is not smaller than the number of points in `scatter` then the function behaves like `gwy_scatter_copy()`. |

#### Returns

A newly created GwyScatter with reduced number of points.

[transfer full]

### gwy_scatter_reduce_points()

    void
    gwy_scatter_reduce_points (GwyScatter *scatter,
                               gsize n);

Reduces the number of points in scattered data.

The functions attempts to choose points from the original scattered data to cover its full area, even though points from dense regions are still more likely to be found in the result than points from sparse regions. As the main purpose to enable quick rough operations that may take a long time with the full scattered data, the focus is on speed not fidelity.

The function may employ random selection and thus be be non-deterministic.

If you take advantage of the possibility of passing `n` larger than the current number of points, you cannot assume that after the reduction the scattered data will have `n` points (if the number is actually reduced, then you can).

#### Parameters

scatter | A scattered data. |
n | Requested number of points in the reduced scattered data. If it is not smaller than the number of points in `scatter` the number of points is unchanged. |

### gwy_scatter_resize()

    void
    gwy_scatter_resize (GwyScatter *scatter,
                        gsize n);

Changes the number of points in a scattered data.

If the number of points decreases then the first `npoints` points will be kept. If the number of points increases the new points will be uninitialised. Although typically one overwrites all the points after using this function.

Use `gwy_scatter_set_xy_full()` if you already have an array of points to fill the scattered data with.

#### Parameters

scatter | A scattered data. |
n | New number of points in the scattered data. |

### gwy_scatter_filter()

    gsize
    gwy_scatter_filter (GwyScatter *scatter,
                        GwyScatterFilterFunc filter,
                        gpointer user_data);

Filters scattered data using a user-specified filter function.

See also `gwy_scatter_reduce_to_subset()` which filters scattered data using a bit mask.

#### Parameters

scatter | A scattered data. |
filter | Function returning `TRUE` for points to keep and `FALSE` for points to discard. | [scope call][closure user_data]
user_data | User data passed to `filter` . |

#### Returns

The new number of points in `scatter` .

### gwy_scatter_new_filtered()

    GwyScatter *
    gwy_scatter_new_filtered (GwyScatter *scatter,
                              GwyScatterFilterFunc filter,
                              gpointer user_data);

Creates new scattered data by filtering another data using a user-specified filter function.

See also `gwy_scatter_new_subset()` which filters scattered data using a bit mask.

#### Parameters

scatter | A scattered data. |
filter | Function returning `TRUE` for points to keep and `FALSE` for points to discard. | [scope call][closure user_data]
user_data | User data passed to `filter` . |

#### Returns

Newly created filtered scattered data.

[transfer full]

### gwy_scatter_reduce_to_subset()

    gsize
    gwy_scatter_reduce_to_subset (GwyScatter *scatter,
                                  const guint32 *keepbits);

Keeps a subset of scattered data points, defined using a bitmask.

The `scatter` array must have at least ceil(`gwy_scatter_get_n_points()`/32) elements. Bits in the array correspond to the scattered data – in order. Within each 32bit integer, the bits go from the lowest to the highest.

See also `gwy_scatter_filter()` which filters scattered data using a filter function.

#### Parameters

scatter | A scattered data. |
keepbits | Bit mask defining which data to keep. |

#### Returns

The number of values in the reduced data (given by the number of set bits in `keepbits` ).

### gwy_scatter_new_subset()

    GwyScatter *
    gwy_scatter_new_subset (GwyScatter *scatter,
                            const guint32 *keepbits);

Creates new scattered data as a subset of another, defined using a bitmask.

The `scatter` array must have at least ceil(`gwy_scatter_get_n_points()`/32) elements. Bits in the array correspond to the scattered data – in order. Within each 32bit integer, the bits go from the lowest to the highest.

See also `gwy_scatter_new_filtered()` which filters scattered data using a filter function.

#### Parameters

scatter | A scattered data. |
keepbits | Bit mask defining which data to keep. |

#### Returns

Newly created filtered scattered data.

[transfer full]

### gwy_scatter_sort()

    void
    gwy_scatter_sort (GwyScatter *scatter,
                      GwyScatterCompareFunc compare,
                      gpointer user_data);

Sorts scattered data using a user-provided function.

See also `gwy_scatter_sort_by_value()` if you want to simple sort by one data value, for example time.

#### Parameters

scatter | A scattered data. |
compare | Point comparison function. | [scope call][closure user_data]
user_data | User data passed to `compare` . |

### gwy_scatter_sort_by_value()

    void
    gwy_scatter_sort_by_value (GwyScatter *scatter,
                               gint i,
                               gboolean ascending);

Sorts scattered data using one data value.

See also `gwy_scatter_sort()` for a general sorting function.

#### Parameters

scatter | A scattered data. |
i | Index of data value to use for comparison. |
ascending | `TRUE` to sort in ascending order, `FALSE` in descending order. |

### gwy_scatter_stack()

    void
    gwy_scatter_stack (GwyScatter *scatter,
                       GwyScatter **operands,
                       guint n);

Adds data from scattered data as new values to another scattered data, ‘stacking’ the data.

All the operands must share the set of XY points with `scatter` . Meaning, they must pass `GWY_DATA_MISMATCH_POINTS` and `GWY_DATA_MISMATCH_LATERAL` checks with `gwy_scatter_is_incompatible()`. Nevertheless, it is an error to try to stack a scattered data to itself.

All data from the operands are then added to `scatter` , in given order, including units and labels. First all data from the first operand are added, then all data from the second operand, etc.

#### Parameters

scatter | A scattered data. |
operands | Array with more compatible scattered data. | [array size=n][transfer none]
n | Number of items in `operands` . |

### gwy_scatter_insert_values()

    void
    gwy_scatter_insert_values (GwyScatter *scatter,
                               gint i,
                               gint nvalues);

Increases the number of values per point in scattered data.

The new data start as uninitialised. Use `gwy_scatter_get_data()` afterwards to get the data arrays and fill them.

The XY coordinates remain unchanged.

#### Parameters

scatter | A scattered data. |
i | Index in scattered data values where to insert the new values. It can be between zero and the current number of values (inclusive). The latter case means appending to the end. |
nvalues | The number of values to add. |

### gwy_scatter_remove_values()

    void
    gwy_scatter_remove_values (GwyScatter *scatter,
                               gint i,
                               gint nvalues);

Decreases the number of values per point in scattered data.

The XY coordinates remain unchanged.

#### Parameters

scatter | A scattered data. |
i | Index of the first scattered data value to remove. It can be between zero and the current number of values (inclusive). However, the latter case means `nvalues` must be zero and is not particularly useful. |
nvalues | The number of values to remove. It must not exceed the number of values that exist in `scatter` (starting from `i` ). |

## Types and Values

### struct GwyScatter

    struct GwyScatter {
        gsize n;
    };

Object representing scattered data.

The GwyScatter struct contains some public fields that can be directly accessed for reading. To change them, you must use the GwyScatter methods.

#### Members

gsize `n`; | Number of points. |

### struct GwyScatterClass

    struct GwyScatterClass {
        GObjectClass parent_class;

        void (*xy_changed)(GwyScatter *scatter);
        void (*data_changed)(GwyScatter *scatter);
    };

Class of scattered data.

## Signal Details

### The `“data-changed”` signal

    void
    user_function (GwyScatter *gwyscatter,
                   gpointer    user_data)

The ::data-changed signal is never emitted by the object itself. It is intended as a means to notify object users they should update themselves, usually when a computation modifying the data is finished.

#### Parameters

gwyscatter | The GwyScatter which received the signal. |
user_data | user data set when the signal handler was connected. |

Flags: Run First

### The `“xy-changed”` signal

    void
    user_function (GwyScatter *gwyscatter,
                   gpointer    user_data)

The ::xy-changed signal is never emitted by the object itself. It is intended as a means to notify object users they should update themselves, usually when a computation modifying the XY positions is finished.

#### Parameters

gwyscatter | The GwyScatter which received the signal. |
user_data | user data set when the signal handler was connected. |

Flags: Run First