Implement panel map class

[cynthiahqy]

lots of internal functions currently assume inputs are valid panel maps. It would probably be sensible to implement some safeguards -- i.e. using classes

This could be (quickly) checked for using a class condition. Requires implementing a constructor/validation/helper function design pattern as described in 13.3 Classes, Advanced R -- see skeleton here: 27e9ff1/R/panel_map.R

Maybe this lives in a separate panelmap package though?

[cynthiahqy]

This is being implemented in xmap:

• [x] low level constructor
• [ ] validator
• [ ] user helper

[cynthiahqy]

More example code: https://github.com/tidyverts/tsibble/blob/main/R/as-tsibble.R

[cynthiahqy]

What should the s3 object be named?

From Advanced R, 13.3 Classes

When using a class in a package, I recommend including the package name in the class name. That ensures you won’t accidentally clash with a class defined by another package.

But I don't like the look of xmap_xmap, it feels tedious. xmap_df probably makes more sense, because it indicates that it is a data.frame.

[cynthiahqy]

What column type checks are required?

weights should be numeric (<int> or more likely <dbl>)

This one is fairly straight forward, if all links have weight 1 <int> will suffice, otherwise <dbl> is necessary and brings some floating point issues with it (see #30 also)

*_node columns should maybe be factor columns?

From R for Data Science:

In R, factors are used to work with categorical variables, variables that have a fixed and known set of possible values. They are also useful when you want to display character vectors in a non-alphabetical order.

Both the source and target nomenclature form a fixed and known set of possible node labels.

Possible downstream benefits:

• ordering nodes when visualising an xmap
• checking an xmap completely covers a dataset (avoid need to compute unique(src_node))

But could it cause issues when implementing transformation of data using an xmap?

• Does dplyr::join() treat factor columns as character ones anyway?
• Are there any bugs that could arise from the underlying implementation of factors as integer vectors + levels attribute?
• xmap should accept integer and character vectors (since you can use numbers or letters or a mixture to encode classification categories)

[cynthiahqy]

Probably want to retain whatever vector class the user provides for the from and to columns. Factor and character vectors make the most sense, but you could have integer codes. This is probably not a great idea, but there isn't any obvious reason xmap should prohibit users from doing this.

• [ ] Test that factor / character class of src/target columns as given by user (in graph_df) are retained
• [x] Calculate and attach known node set as attribute to xmap (for conform::concord checks)

[cynthiahqy]

this has been migrated to #57

Where should different checks live?

There are a few types of checks that need to happen when forming a valid xmap:

1. R specific data.frame/S3 attribute checks
2. logical conditions on the graph encoded by the xmap
3. data.frame size/column types

Some of the data.frame attribute checks currently in validate_xmap() are somewhat redundant because they are checked for in new_xmap(). For example:

• exactly 3 columns
• named from, weight cols are actually present in the df
• weight column type is numeric

are all checked when forming the xmap_df.

This means that the error messages in validate_xmap() will never be triggered (since the function takes in an object of class xmap_df.) However, it would still be useful to keep the more verbose error messages currently in validate_xmap() to help users. Maybe I can move these into the as_xmap() helper function?

[cynthiahqy]

Methods & Generics?

More of a later thing, but parking ideas here.

print.xmap()

Existing methods:

• could leverage {pillar} by adding the tbl class. This would make xmap a subclass of tibbles.
• could also consider {igraph} style print: src_node -- weights --> target_node

The properties of a crossmap that might be useful to display:

• types & count of outgoing links: one-to-one, one-to-many? (split/no-split)
• types of incoming links: one-from-one, one-from-many (aggregation/no aggregation?)
• from & to set element count: how many source and target classification codes are there?

plot.xmap()

• default plot.data.frame() method does a scatterplot, which doesn't really make sense for a graph

[cynthiahqy]

Read and Write methods #62 :

• 57 for xmap_df format (.csv)

• 48 for xmap_graph format (.xml? or other?)

[cynthiahqy]

Discussions have all moved to other issues -- mostly #57, #60 and #62