topologic.projection package

topologic.projections provides a canned series of source-to-Graph projection functions.

The function return type Callable[[nx.Graph], Callable[[List[str]], None]] is the cornerstone to every projection function.

You can, and should, define any function you want as long as it complies with that return type. The first function should take in any Dataset source-specific configuration information; information necessary to tell a projection function how your source data is laid out and should be used to apply changes to the networkx.Graph.

The 1st inner function is used by the topologic.io.csv_loader.from_dataset function - it applies the networkx.Graph to update.

The 2nd inner function is also used by topologic.io.csv_loader.from_dataset to take each record from the Dataset source and use it to apply this modification to the networkx.Graph.

Graph metadata format:

If a graph is to have metadata on its vertices or edges, it shall always be in the form of:

{
    "weight": 1.0,
    "attributes": [
        { "key": "value1", "anotherKey": "anotherValue", "aDifferentKey": "aDifferentValue" },
        { "key": "value2", "aDifferentKey": "aDifferentValue2" }
    ]
}

Notes: - Keys are always of type str - Values are always stored as type str, but could be a more narrowly bounded type like int or float. - Just because a key exists in one row of the attributes List does not mean it will exist in any other. Do not presume a constant “shape” of the dictionaries of edge attributes.

topologic.projection.edge_ignore_metadata(source_index: int, target_index: int, weight_index: Optional[int] = None) → Callable[[networkx.classes.graph.Graph], Callable[[List[str]], None]][source]

Drops all metadata. Creates graph solely based on source, target, and optional weight.

See package docstrings for more details on these currying functions.

Parameters
  • source_index (int) – The index in the CSV data row to use as the source node in this edge

  • target_index (int) – The index in the CSV data row to use as the target node in this edge

  • weight_index (Optional[int]) – Optional. The index in the CSV data row to use as the weight of the edge. If no weight is provided, all records of an edge are presumed to have a weight of 1. Duplicates of an edge will have their weights (or inferred weight) aggregated into a single value.

Returns

A partially applied function that partially applies yet more arguments prior to the final operation function

Return type

Callable[[networkx.Graph], Callable[[List[str]], None]]

topologic.projection.edge_with_collection_metadata(headers: List[str], source_index: int, target_index: int, weight_index: Optional[int] = None, ignored_values: Optional[List[str]] = None) → Callable[[networkx.classes.graph.Graph], Callable[[List[str]], None]][source]

Some graph algorithms have undefined behavior over multigraphs. To skirt this limitation, we allow the data to represent a multigraph, though we collapse it into a non-multigraph. We do this by aggregating the weights, and in this case we take any extra metadata in the edge source and project it, along with headers, into an attribute dictionary. This dictionary is then added to a List of any previous attribute dictionaries for the same source and target, so as to not clobber any metadata.

See package docstrings for more details on these currying functions.

Parameters
  • headers (List[str]) – Headers from a CSV row to use as metadata attribute keys

  • source_index (int) – The index in the CSV data row to use as the source node in this edge

  • target_index (int) – The index in the CSV data row to use as the target node in this edge

  • weight_index (Optional[int]) – Optional. The index in the CSV data row to use as the weight of the edge. If no weight is provided, all records of an edge are presumed to have a weight of 1. Duplicates of an edge will have their weights (or inferred weight) aggregated into a single value.

  • ignored_values (Optional[List[str]]) – Optional. A list of values to ignore if present in the row, such as “NULL” or “”

Returns

A partially applied function that partially applies yet more arguments prior to the final operation function

Return type

Callable[[networkx.Graph], Callable[[List[str]], None]]

topologic.projection.edge_with_single_metadata(headers: List[str], source_index: int, target_index: int, weight_index: Optional[int] = None, ignored_values: Optional[List[str]] = None) → Callable[[networkx.classes.graph.Graph], Callable[[List[str]], None]][source]

Will load edges into graph even if they are a multigraph. However, aside from weight, the multigraph attributes are ignored and the last record to be processed for that source and target will have its metadata retained and all prior metadata dropped.

See package docstrings for more details on these currying functions.

Parameters
  • headers (List[str]) – Headers from a CSV row to use as metadata attribute keys

  • source_index (int) – The index in the CSV data row to use as the source node in this edge

  • target_index (int) – The index in the CSV data row to use as the target node in this edge

  • weight_index (Optional[int[) – Optional. The index in the CSV data row to use as the weight of the edge. If no weight is provided, all records of an edge are presumed to have a weight of 1. Duplicates of an edge will have their weights (or inferred weight) aggregated into a single value.

  • ignored_values (Optional[List[str]]) – Optional. A list of values to ignore if present in the row, such as “NULL” or “”

Returns

A partially applied function that partially applies yet more arguments prior to the final operation function

Return type

Callable[[networkx.Graph], Callable[[List[str]], None]]

topologic.projection.vertex_with_collection_metadata(headers: List[str], vertex_id_index: int, ignored_values: Optional[List[str]] = None) → Callable[[networkx.classes.graph.Graph], Callable[[List[str]], None]][source]

This function is an unlikely function to use; if you have vertex metadata you wish to load into the networkx.Graph where the vertex_id is repeated, it would be a better choice for you to compact those into a single record with a specific, string representable format of multiple metadata entries. However, this function can be used when you aren’t sure what you have. Like the edge_with_collection_metadata projection, this function will create a List of dictionaries for each instance of metadata it sees for a given vertex_id.

Note: If the vertex_id for a given row does not exist in the graph, NO METADATA WILL BE RETAINED.

See package docstrings for more details on these currying functions.

Parameters
  • headers (List[str]) – Headers from a CSV row to use as metadata attribute keys

  • vertex_id_index (int) – The index in the CSV data row to use as the vertex id in this graph

  • ignored_values (Optional[List[str]]) – Optional. A list of values to ignore if present in the row, such as “NULL” or “”

Returns

A partially applied function that partially applies yet more arguments prior to the final operation function

Return type

Callable[[networkx.Graph], Callable[[List[str]], None]]

topologic.projection.vertex_with_single_metadata(headers: List[str], vertex_id_index: int, ignored_values: List[str] = None) → Callable[[networkx.classes.graph.Graph], Callable[[List[str]], None]][source]

Function will project vertex metadata into the graph. If prior data exists for the vertex_id, the later instance of data for the vertex_id will clobber it.

Note: If the vertex_id for a given row does not exist in the graph, NO METADATA WILL BE RETAINED.

See package docstrings for more details on these currying functions and on the attributes datastructure.

Parameters
  • headers (List[str]) – Headers from a CSV row to use as metadata attribute keys

  • vertex_id_index (int) – The index in the CSV data row to use as the vertex id in this graph

  • ignored_values (Optional[List[str]]) – Optional. A list of values to ignore if present in the row, such as “NULL” or “”

Returns

A partially applied function that partially applies yet more arguments prior to the final operation function

Return type

Callable[[networkx.Graph], Callable[[List[str]], None]]