Skip to content

Create MicroJSON models

In this tutorial, we explain how a Python script is used to convert a pandas DataFrame into a MicroJSON FeatureCollection object.

Example dataframe to MicroJSON conversion

Transforms a pandas DataFrame into a FeatureCollection model.

This function is designed to convert geometries stored in a pandas DataFrame into a FeatureCollection model, based on the MicroJSON schema.

Parameters: - df: The pandas DataFrame to transform. Each row should represent a feature.

Returns: - A FeatureCollection object that aggregates the individual features.

Source code in src/microjson/examples/df_to_microjson.py 
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
def df_to_microjson(df: pd.DataFrame) -> mj.FeatureCollection:
    """
    Transforms a pandas DataFrame into a FeatureCollection model.

    This function is designed to convert geometries stored in a pandas
    DataFrame into a FeatureCollection model, based on the MicroJSON schema.

    Parameters:
    - df: The pandas DataFrame to transform. Each row should represent a
    feature.

    Returns:
    - A FeatureCollection object that aggregates the individual features.

    """
    # Initialize a list to hold the Feature objects
    features: List[mj.Feature] = []

    # Iterate over each row in the DataFrame
    for _, row in df.iterrows():
        # Dynamically generate a Geometry object based on the row's
        # geometry type
        GeometryClass = getattr(mj, row["geometryType"])
        geometry = GeometryClass(
            type=row["geometryType"], coordinates=row["coordinates"]
        )

        # create a dictionary of properties using the columns name, value and values
        properties = {}
        for key in ["name", "value", "values"]:
            properties[key] = row[key]

        # Generate a Feature object that combines geometry and properties
        feature = mj.MicroFeature(
            type=row["type"], geometry=geometry, properties=properties
        )

        # Append this feature to the list of features
        features.append(feature)

    # Generate a FeatureCollection object to aggregate all features
    feature_collection = mj.MicroFeatureCollection(
        type="FeatureCollection",
        features=features,
        properties={"plate": "Example Plate"},
        multiscale={
            "axes": [
                {
                    "name": "x",
                    "type": "space",
                    "unit": "meter",
                    "description": "The x-coordinate",
                },
                {
                    "name": "y",
                    "type": "space",
                    "unit": "meter",
                    "description": "The y-coordinate",
                },
            ],
            "transformationMatrix": [[1, 0, 0], [0, 1, 0], [0, 0, 1]],
        },
    )

    return feature_collection

Here's a breakdown of the steps involved:

  1. Initialize an empty list of Features: A list features is initialized to hold Feature objects.

  2. Iterate over DataFrame rows: The function iterates through each row of the DataFrame, performing the following operations for each row:

    • Create a Geometry Object: It dynamically generates a Geometry object based on the geometry type specified in the row.

    • Create a Properties Object: It then creates a Properties object to hold metadata about the feature like the name, value, and an array of values.

    • Combine into a Feature: It combines both the geometry and properties into a MicroJSON Feature object.

  3. Calculate Value Ranges: For each numeric attribute, a range of values (min, max) is calculated.

  4. Create a FeatureCollection Object: Finally, it aggregates all the features into a MicroJSON FeatureCollection object, including the calculated value ranges and other optional metadata.

Example dataframe creation, conversion and MicroJSON output

Below, we convert a pandas DataFrame into a MicroJSON FeatureCollection object. It includes an example of creating a DataFrame with two features, one Point and one Polygon, and converting it into a FeatureCollection model using the df_to_microjson function as described above, and then serializing the model to a JSON string.

if __name__ == "__main__":
    # Example DataFrame with two features: one Point and one Polygon
    data = [
        {
            "type": "Feature",
            "geometryType": "Point",
            "coordinates": [0, 0],
            "name": "Point 1",
            "value": 1,
            "values": [1, 2, 3],
        },
        {
            "type": "Feature",
            "geometryType": "Polygon",
            "coordinates": [[[0, 0], [1, 0], [1, 1], [0, 1], [0, 0]]],
            "name": "Polygon 1",
            "value": 2,
            "values": [4, 5, 6],
        },
    ]

    # Convert this list of dictionaries into a DataFrame
    df = pd.DataFrame(data)

    # Convert the DataFrame into a FeatureCollection model
    feature_collection_model = df_to_microjson(df)

    # Serialize the FeatureCollection model to a JSON string
    print(
        feature_collection_model.model_dump_json(indent=2, exclude_unset=True)
    )