pandas_matrix_zone_translation#

translation.pandas_matrix_zone_translation(matrix, translation_from_col, translation_to_col, translation_factors_col, from_unique_index, to_unique_index, translation, col_translation=None, translation_dtype=None, matrix_infill=0.0, translate_infill=0.0, check_totals=True, slow_fallback=True, chunk_size=100, _force_slow=False)#

Efficiently translates a pandas matrix between index systems.

Parameters:

  • matrix (DataFrame) – The matrix to translate. The index and columns need to be the values being translated. This CANNOT be a “long” matrix.

  • translation (DataFrame) – A pandas DataFrame defining the weights to translate use when translating. Needs to contain columns: translation_from_col, translation_to_col, translation_factors_col. When col_translation is None, this defines the translation to use for both the rows and columns. When col_translation is set, this defines the translation to use for the rows.

  • col_translation (DataFrame) – A matrix defining the weights to use to translate the columns. Takes an input of the same format as translation. When None, translation is used as the column translation.

  • translation_from_col (str) – The name of the column in translation and col_translation containing the current index and column values of matrix.

  • translation_to_col (str) – The name of the column in translation and col_translation containing the desired output index and column values. This will define the output index and column format.

  • translation_factors_col (str) – The name of the column in translation and col_translation containing the translation weights between translation_from_col and translation_to_col. Where zone pairs do not exist, they will be infilled with translate_infill.

  • from_unique_index (list[Any]) – A list of all the unique IDs in the input indexing system.

  • to_unique_index (list[Any]) – A list of all the unique IDs in the output indexing system.

  • translation_dtype (dtype | None) – The numpy datatype to use to do the translation. If None, then the dtype of vector is used. Where such high precision isn’t needed, a more memory and time efficient data type can be used.

  • matrix_infill (float) – The value to use to infill any missing matrix values.

  • translate_infill (float) – The value to use to infill any missing translation factors.

  • check_totals (bool) – Whether to check that the input and output matrices sum to the same total.

  • slow_fallback (bool) – Whether to fall back to a slower, more memory efficient method if a MemoryError is raised during faster translation.

  • chunk_size (int) – The size of the chunks to use if falling back on a slower, more memory efficient method. Most of the time this can be ignored unless translating between two massive zoning systems.

  • _force_slow (bool) –

Returns:

matrix, translated into to_unique_index system.

Return type:

translated_matrix

Raises:

ValueError: – If matrix is not a square array, or if translation any inputs are not the correct format.