API Reference

Tools for computing diversity, integration, and segregation metrics.

class divintseg.SimilarityReference(reference: <Mock name='mock.DataFrame' id='139916738656384'> | ~typing.Mapping[str, int | float])[source]

Bases: object

An object that computes dissimilarty from a reference.

Parameters:

reference – The reference community. It should be a mapping from name to count or a dataframe with a single row with a column with the reference population of each group.

dissimilarity(df_communities: <Mock name='mock.DataFrame' id='139916738656384'>) → <Mock name='mock.Series' id='139916738656432'>[source]

Compute the dissimilarity index of one or more communities relative to a reference community.

Parameters:

df_communities – The communities. This is a DataFrame with each row representing a community and each column representing a group.

Returns:

  • The dissimilarity index of the each community relative to the reference

  • community.

similarity(df_communities: <Mock name='mock.DataFrame' id='139916738656384'>) → <Mock name='mock.Series' id='139916738656432'>[source]

Compute the representation index of one or more communities.

If sim_ref is a SimilarityReference, then sim_ref.similarity(communities)- is equal to `1.0 - sim_ref.similarity(communities).

Parameters:

df_communities – The communities. This is a DataFrame with each row representing a community and each column representing a group.

Returns:

  • The dissimilarity index of the each community relative to the reference

  • community.

divintseg.di(df_communities: <Mock name='mock.DataFrame' id='139916738656384'>, by=None, over=None, *, add_segregation: bool = False, drop_non_numeric: bool = False) → <Mock name='mock.DataFrame' id='139916738656384'>[source]

Compute the diversity, integration, and optionally the segregation of each of a collection of communities.

Parameters:

  • df_communities – A pd.DataFrame of communities.

  • by – The column or index to group by in order to partition the rows into communities.

  • over – The column to group by in order to partition the rows of each community into smaller aggregation units where the base diversity will be computed. If None then each row is assumed to represent a different community.

  • add_segregation – if True add a column to the results for segregation.

  • drop_non_numeric – If True, then any non-numeric column other than those specified by by and over will be implicitly dropped. This is useful if there are columns naming other levels of geographic aggregation that should be ignored.

Returns:

  • A Series containing the diversity,

  • integration, and optionally the segregation of

  • each community.

divintseg.dissimilarity(df_communities: <Mock name='mock.DataFrame' id='139916738656384'>, reference: <Mock name='mock.DataFrame' id='139916738656384'> | ~typing.Mapping[str, int | float]) → <Mock name='mock.Series' id='139916738656432'>[source]

Compute the dissimilarity index of one or more communities relative to a reference community.

If you want compute dissimilarity or similarity many times against a common reference, then creating at SimularityReference is a more efficient option.

Parameters:

  • df_communities – The communities. This is a DataFrame with each row representing a community and each column representing a group.

  • reference – The reference community. It should be a single row with a column with the reference population of each group.

Returns:

  • The dissimilarity index of the each community relative to the reference

  • community.

divintseg.diversity(communities: <Mock name='mock.DataFrame' id='139916738656384'> | ~typing.Iterable[float]) → <Mock name='mock.Series' id='139916738656432'> | float[source]

Compute the diversity of one or more communities.

Parameters:

communities – The communities. This is either an iterable over the population of each group in the community or, more commonly, a DataFrame with each row representing a community and each column representing a group.

Returns:

  • The diversity of the community or, if passed a

  • DataFrame then a Series

  • with one entry for the diversity of each community.

divintseg.integration(df_communities: <Mock name='mock.DataFrame' id='139916738656384'>, by=None, over=None, *, drop_non_numeric: bool = False) → <Mock name='mock.DataFrame' id='139916738656384'>[source]

Compute the integration of one of more communities over a nested level of population aggregation. For example, with US census data we might compute integration of block groups over blocks.

Parameters:

  • df_communities – A pd.DataFrame of communities.

  • by – The column or index to group by in order to partition the rows into communities.

  • over – The column to group by in order to partition the rows of each community into smaller aggregation units where the base diversity will be computed. If None then each row is assumed to represent a different community.

  • drop_non_numeric – If True, then any non-numeric column other than those specified by by and over will be implicitly dropped. This is useful if there are columns naming other levels of geographic aggregation that should be ignored.

Returns:

  • A Series containing the integration of

  • each community.

divintseg.segregation(df_communities: <Mock name='mock.DataFrame' id='139916738656384'>, by=None, over=None, *, drop_non_numeric: bool = False) → <Mock name='mock.DataFrame' id='139916738656384'>[source]

Compute the segregation of one of more communities over a nested level of population aggregation. For example, with US census data we might compute integration of block groups over blocks.

Parameters:

  • df_communities – A pd.DataFrame of communities.

  • by – The column or index to group by in order to partition the rows into communities.

  • over – The column to group by in order to partition the rows of each community into smaller aggregation units where the base diversity will be computed. If None then each row is assumed to represent a different community.

  • drop_non_numeric – If True, then any non-numeric column other than those specified by by and over will be implicitly dropped. This is useful if there are columns naming other levels of geographic aggregation that should be ignored.

Returns:

  • A Series containing the segregation of

  • each community.

divintseg.similarity(df_communities: <Mock name='mock.DataFrame' id='139916738656384'>, reference: <Mock name='mock.DataFrame' id='139916738656384'> | ~typing.Mapping[str, int | float]) → <Mock name='mock.Series' id='139916738656432'>[source]

Compute the similarity index of one or more communities relative to a reference community.

Note that similarity is just one minus dissimilarity.

If you want compute dissimilarity or similarity many times against a common reference, then creating at SimularityReference is a more efficient option.

Parameters:

  • df_communities – The communities. This is a DataFrame with each row representing a community and each column representing a group.

  • reference – The reference community. It should be a single row with a column with the reference population of each group.

Returns:

  • The similarity of the each community relative to the reference

  • community.