GogSeries

## GogSeries GogSeries — A single data series. |

## Synopsis

                        GogSeries;
                        GogSeriesClass;
                        GogSeriesDesc;
                        GogSeriesDimDesc;
    enum                GogDimType;
    enum                GogMSDimType;
                        GogSeriesElement;
                        GogSeriesElementClass;
    enum                GogSeriesPriority;
    enum                GogSeriesFillType;
    void                gog_series_check_validity           (GogSeries *series);
    GogSeriesElement *  gog_series_get_element              (GogSeries const *series,
                                                             int index);
    GogSeriesFillType   gog_series_get_fill_type            (GogSeries const *series);
    GogSeriesFillType   gog_series_get_fill_type_from_combo (GogSeries const *series,
                                                             GtkComboBox *combo);
    GogDataset *        gog_series_get_interpolation_params (GogSeries const *series);
    GOData *            gog_series_get_name                 (GogSeries const *series);
    GList const  	 *    gog_series_get_overrides            (GogSeries const *series);
    GogPlot *           gog_series_get_plot                 (GogSeries const *series);
    unsigned            gog_series_get_xy_data              (GogSeries const *series,
                                                             double const **x,
                                                             double const **y);
    unsigned            gog_series_get_xyz_data             (GogSeries const *series,
                                                             double const **x,
                                                             double const **y,
                                                             double const **z);
    gboolean            gog_series_has_legend               (GogSeries const *series);
    gboolean            gog_series_is_valid                 (GogSeries const *series);
    int                 gog_series_map_XL_dim               (GogSeries const *series,
                                                             GogMSDimType ms_type);
    unsigned            gog_series_num_elements             (GogSeries const *series);
    void                gog_series_populate_fill_type_combo (GogSeries const *series,
                                                             GtkComboBox *combo);
    void                gog_series_set_XL_dim               (GogSeries *series,
                                                             GogMSDimType ms_type,
                                                             GOData *val,
                                                             GError **err);
    void                gog_series_set_dim                  (GogSeries *series,
                                                             int dim_i,
                                                             GOData *val,
                                                             GError **err);
    void                gog_series_set_fill_type            (GogSeries *series,
                                                             GogSeriesFillType fill_type);
    void                gog_series_set_index                (GogSeries *series,
                                                             int ind,
                                                             gboolean is_manual);
    void                gog_series_set_name                 (GogSeries *series,
                                                             GODataScalar *name_src,
                                                             GError **err);

## Object Hierarchy

      GObject
       +----GogObject
             +----GogStyledObject
                   +----GogSeries

      GObject
       +----GogObject
             +----GogStyledObject
                   +----GogSeriesElement

## Implemented Interfaces

GogSeries implements GOStyledObject and GogDataset.

GogSeriesElement implements GOStyledObject.

## Properties

      "fill-type"                gchar*                : Read / Write
      "has-legend"               gboolean              : Read / Write
      "interpolation"            gchar*                : Read / Write
      "interpolation-skip-invalid" gboolean              : Read / Write
      "index"                    gint                  : Read / Write

## Description

A GogSeries represents a data series that can be added to a GogPlot.

## Details

### GogSeries

    typedef struct _GogSeries GogSeries;

### GogSeriesClass

    typedef struct {
    	GogStyledObjectClass base;

    	gboolean		 has_interpolation;
    	gboolean		 has_fill_type;

    	GogSeriesFillType const *valid_fill_type_list;

    	GType			 series_element_type;

    	/* Virtuals */
    	void        (*dim_changed) (GogSeries *series, int dim_i);
    	unsigned    (*get_xy_data) (GogSeries const *series,
    	                            double const **x, double const **y);
    	GogDataset *(*get_interpolation_params) (GogSeries const *series);
    } GogSeriesClass;

GogStyledObjectClass `base`; |
gboolean `has_interpolation`; | supports interpolation.
gboolean `has_fill_type`; | `TRUE` if filling is supported.
GogSeriesFillType const *`valid_fill_type_list`; | list of supported GogSeriesFillType values.
GType `series_element_type`; | GType for the series element if supported.
`dim_changed` () | called when data changed for the series.
`get_xy_data` () | get X and Y data.
`get_interpolation_params` () | get interpolation parameters if any, only applies to constrained cubic spline interpolation.

### GogSeriesDesc

    typedef struct {
    	unsigned style_fields;
    	unsigned num_dim;
    	GogSeriesDimDesc const *dim;
    } GogSeriesDesc;

GogSeriesDimDesc const *`dim`; | dimensions descriptions.

### GogSeriesDimDesc

    typedef struct {
    	char const *name;
    	GogSeriesPriority priority;
    	gboolean		is_shared;
    	GogDimType		val_type;
    	GogMSDimType		ms_type;
    } GogSeriesDimDesc;

char const *`name`; | name.
GogSeriesPriority `priority`; | priority.
gboolean `is_shared`; | whether the dimension is shared among the series.
GogDimType `val_type`; | data type.
GogMSDimType `ms_type`; | data type for foreign formats.

### enum GogDimType

    typedef enum {
    	GOG_DIM_INVALID = -1,
    	GOG_DIM_LABEL = 0,
    	GOG_DIM_INDEX,
    	GOG_DIM_VALUE,
    	GOG_DIM_MATRIX,
    	GOG_DIM_TYPES
    } GogDimType;

Data types for plots.

`GOG_DIM_INVALID` | invalid should not occur.
`GOG_DIM_LABEL` | labels.
`GOG_DIM_INDEX` | indices.
`GOG_DIM_VALUE` | vector of values.
`GOG_DIM_MATRIX` | matrix of values.
`GOG_DIM_TYPES` | should not occur.

### enum GogMSDimType

    typedef enum {
    	GOG_MS_DIM_LABELS = 0,
    	GOG_MS_DIM_VALUES = 1,
    	GOG_MS_DIM_CATEGORIES = 2,
    	GOG_MS_DIM_BUBBLES = 3, /* undocumented */
    	GOG_MS_DIM_TYPES,
    	GOG_MS_DIM_ERR_plus1, /* we made it up */
    	GOG_MS_DIM_ERR_minus1, /* we made it up */
    	GOG_MS_DIM_ERR_plus2, /* we made it up */
    	GOG_MS_DIM_ERR_minus2, /* we made it up */
    	GOG_MS_DIM_START, /* we made it up for dropbars*/
    	GOG_MS_DIM_END, /* we made it up for dropbars */
    	GOG_MS_DIM_LOW, /* we made it up for hi-lo*/
    	GOG_MS_DIM_HIGH, /* we made it up for hi-lo */
    	GOG_MS_DIM_EXTRA1, /* we made it up for other uses */
    	GOG_MS_DIM_EXTRA2 /* we made it up for other uses */
    } GogMSDimType;

Data types classed according to what they become when exported to foreign formats.

`GOG_MS_DIM_LABELS` | labels.
`GOG_MS_DIM_VALUES` | values.
`GOG_MS_DIM_CATEGORIES` | categories.
`GOG_MS_DIM_BUBBLES` | bubble values.
`GOG_MS_DIM_TYPES` | maximum value known by MS, should not occur.
`GOG_MS_DIM_ERR_plus1` | positive erros on first dimension, we made it up.
`GOG_MS_DIM_ERR_minus1` | negative erros on first dimension, we made it up.
`GOG_MS_DIM_ERR_plus2` | positive erros on second dimension, we made it up.
`GOG_MS_DIM_ERR_minus2` | negative erros on second dimension, we made it up
`GOG_MS_DIM_START` | start value, we made it up for dropbars.
`GOG_MS_DIM_END` | end value, we made it up for dropbars.
`GOG_MS_DIM_LOW` | low value, we made it up for hi-lo.
`GOG_MS_DIM_HIGH` | high value, we made it up for hi-lo.
`GOG_MS_DIM_EXTRA1` | we made it up for other uses.
`GOG_MS_DIM_EXTRA2` | we made it up for other uses.

### GogSeriesElement

    typedef struct _GogSeriesElement GogSeriesElement;

### GogSeriesElementClass

    typedef struct {
    	GogStyledObjectClass base;

    	/* Virtuals */
    	gpointer (*gse_populate_editor) (GogObject *gobj,
    					 GOEditor *editor,
    					 GOCmdContext *cc);
    } GogSeriesElementClass;

GogStyledObjectClass `base`; |
`gse_populate_editor` () | populates editor.

### enum GogSeriesPriority

    typedef enum {
    	GOG_SERIES_REQUIRED,  /* it must be there */
    	GOG_SERIES_SUGGESTED, /* allocator will fill it in, but use need not */
    	GOG_SERIES_OPTIONAL,
    	GOG_SERIES_ERRORS
    } GogSeriesPriority;

Applies to data declarations in GogSeriesDimDesc.

`GOG_SERIES_REQUIRED` | it must be there.
`GOG_SERIES_SUGGESTED` | allocator will fill it in, but use need not.
`GOG_SERIES_OPTIONAL` | optional data.
`GOG_SERIES_ERRORS` | optional data for error bars.

### enum GogSeriesFillType

    typedef enum {
    	GOG_SERIES_FILL_TYPE_Y_ORIGIN,
    	GOG_SERIES_FILL_TYPE_X_ORIGIN,
    	GOG_SERIES_FILL_TYPE_BOTTOM,
    	GOG_SERIES_FILL_TYPE_LEFT,
    	GOG_SERIES_FILL_TYPE_TOP,
    	GOG_SERIES_FILL_TYPE_RIGHT,
    	GOG_SERIES_FILL_TYPE_ORIGIN,
    	GOG_SERIES_FILL_TYPE_CENTER,
    	GOG_SERIES_FILL_TYPE_EDGE,
    	GOG_SERIES_FILL_TYPE_SELF,
    	GOG_SERIES_FILL_TYPE_NEXT,
    	GOG_SERIES_FILL_TYPE_X_AXIS_MIN,
    	GOG_SERIES_FILL_TYPE_X_AXIS_MAX,
    	GOG_SERIES_FILL_TYPE_Y_AXIS_MIN,
    	GOG_SERIES_FILL_TYPE_Y_AXIS_MAX,
    	GOG_SERIES_FILL_TYPE_INVALID
    } GogSeriesFillType;

`GOG_SERIES_FILL_TYPE_Y_ORIGIN` | from origin ox the X-axis.
`GOG_SERIES_FILL_TYPE_X_ORIGIN` | from the origin of the Y-axis
`GOG_SERIES_FILL_TYPE_BOTTOM` | from the chart bottom.
`GOG_SERIES_FILL_TYPE_LEFT` | from the chart left side.
`GOG_SERIES_FILL_TYPE_TOP` | from the chart top.
`GOG_SERIES_FILL_TYPE_RIGHT` | , from the chart right side.
`GOG_SERIES_FILL_TYPE_ORIGIN` | from the origin (for radar and polar plots).
`GOG_SERIES_FILL_TYPE_CENTER` | from the center (for radar and polar plots).
`GOG_SERIES_FILL_TYPE_EDGE` | from the edge (for radar and polar plots).
`GOG_SERIES_FILL_TYPE_SELF` | close the series curve and fills it.
`GOG_SERIES_FILL_TYPE_NEXT` | from next series.
`GOG_SERIES_FILL_TYPE_X_AXIS_MIN` | from X-axis minimum.
`GOG_SERIES_FILL_TYPE_X_AXIS_MAX` | from X-axis maximum.
`GOG_SERIES_FILL_TYPE_Y_AXIS_MIN` | from Y-axis minimum.
`GOG_SERIES_FILL_TYPE_Y_AXIS_MAX` | from Y-axis maximum.
`GOG_SERIES_FILL_TYPE_INVALID` | invalid, should not happen.

### gog_series_check_validity ()

    void                gog_series_check_validity           (GogSeries *series);

Updates the is_valid flag for a series. This is an internal utility that should not really be necessary for general usage.

`series` : | GogSeries

### gog_series_get_element ()

    GogSeriesElement *  gog_series_get_element              (GogSeries const *series,
                                                             int index);

`series` : | GogSeries
`index` : | the element index
Returns : | the GogSeriesElement corresponding to `index` if any. [transfer none]

### gog_series_get_fill_type ()

    GogSeriesFillType   gog_series_get_fill_type            (GogSeries const *series);

### gog_series_get_fill_type_from_combo ()

    GogSeriesFillType   gog_series_get_fill_type_from_combo (GogSeries const *series,
                                                             GtkComboBox *combo);

### gog_series_get_interpolation_params ()

    GogDataset *        gog_series_get_interpolation_params (GogSeries const *series);

Only constrained cubic spline interpolation use parameters (for the slopes at each end).

`series` : | GogSeries
Returns : | the interpolation parameters. [transfer none]

### gog_series_get_name ()

    GOData *            gog_series_get_name                 (GogSeries const *series);

Gets the _source_ of the name associated with the series. NOTE : this is _NOT_ the actual name.

`series` : | a GogSeries
Returns : | a GODataScalar, without added reference. [transfer none]

### gog_series_get_overrides ()

    GList const  	 *    gog_series_get_overrides            (GogSeries const *series);

Overrides are data owning their own style, overriding the series style.

`series` : | GogSeries
Returns : | the series overrides. [element-type GogSeriesElement][transfer none]

### gog_series_get_plot ()

    GogPlot *           gog_series_get_plot                 (GogSeries const *series);

`series` : | GogSeries
Returns : | the possibly NULL plot that contains this series. [transfer none]

### gog_series_get_xy_data ()

    unsigned            gog_series_get_xy_data              (GogSeries const *series,
                                                             double const **x,
                                                             double const **y);

### gog_series_get_xyz_data ()

    unsigned            gog_series_get_xyz_data             (GogSeries const *series,
                                                             double const **x,
                                                             double const **y,
                                                             double const **z);

### gog_series_has_legend ()

    gboolean            gog_series_has_legend               (GogSeries const *series);

`series` : | GogSeries
Returns : | TRUE if the series has a visible legend entry

### gog_series_is_valid ()

    gboolean            gog_series_is_valid                 (GogSeries const *series);

`series` : | GogSeries
Returns : | the current cached validity. Does not recheck

### gog_series_map_XL_dim ()

    int                 gog_series_map_XL_dim               (GogSeries const *series,
                                                             GogMSDimType ms_type);

### gog_series_num_elements ()

    unsigned            gog_series_num_elements             (GogSeries const *series);

`series` : | GogSeries
Returns : | the number of elements in the series

### gog_series_populate_fill_type_combo ()

    void                gog_series_populate_fill_type_combo (GogSeries const *series,
                                                             GtkComboBox *combo);

### gog_series_set_XL_dim ()

    void                gog_series_set_XL_dim               (GogSeries *series,
                                                             GogMSDimType ms_type,
                                                             GOData *val,
                                                             GError **err);

### gog_series_set_dim ()

    void                gog_series_set_dim                  (GogSeries *series,
                                                             int dim_i,
                                                             GOData *val,
                                                             GError **err);

Absorbs a ref to `val`

`series` : | GogSeries
`dim_i` : | Which dimension
`val` : | GOData
`err` : | optional GError pointer

### gog_series_set_fill_type ()

    void                gog_series_set_fill_type            (GogSeries *series,
                                                             GogSeriesFillType fill_type);

### gog_series_set_index ()

    void                gog_series_set_index                (GogSeries *series,
                                                             int ind,
                                                             gboolean is_manual);

If `ind` >= 0 attempt to assign the new index. Auto indicies (`is_manual` == FALSE) will not override the current index if it is manual. An `index` < 0, will reset the index to automatic and potentially queue a revaluation of the parent chart's cardinality.

`series` : | GogSeries
`ind` : | >= 0 assigns a new index, < 0 resets to auto
`is_manual` : | gboolean

### gog_series_set_name ()

    void                gog_series_set_name                 (GogSeries *series,
                                                             GODataScalar *name_src,
                                                             GError **err);

Absorbs a ref to `name_src`.

`series` : | a GogSeries
`name_src` : | a GODataScalar
`err` : | a GError

## Property Details

### The `"fill-type"` property

      "fill-type"                gchar*                : Read / Write

How to fill the area.

Default value: "invalid"

### The `"has-legend"` property

      "has-legend"               gboolean              : Read / Write

Should the series show up in legends.

Default value: TRUE

### The `"interpolation"` property

      "interpolation"            gchar*                : Read / Write

Type of line interpolation.

Default value: "linear"

### The `"interpolation-skip-invalid"` property

      "interpolation-skip-invalid" gboolean              : Read / Write

Should the series interpolation ignore the invalid data.

Default value: FALSE

### The `"index"` property

      "index"                    gint                  : Read / Write

Index of the corresponding data element.

Allowed values: >= 0

Default value: 0