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.

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.

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]

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.

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).

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.

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.

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.

gwy_scatter_get_n_values()

gint
gwy_scatter_get_n_values (GwyScatter *scatter);

Reports the number of values per point in scattered data.

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.

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.

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.

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.

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 .

gwy_scatter_get_n_points()

gsize
gwy_scatter_get_n_points (GwyScatter *scatter);

Gets the number of points in a scattered data.

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().

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.

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.

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.

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.

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.

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.

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.

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.

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).

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

gwy_scatter_multiply()

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

Multiplies values in a scattered data by given constant.

gwy_scatter_add()

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

Adds a constant to values in a scattered 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.

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.

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.

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.

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.

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.

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).

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

struct GwyScatterClass

struct GwyScatterClass {
    GObjectClass parent_class;

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

Class of scattered data.

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.

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.

Flags: Run First