Refactor RasterLayer to be based on PropertyLayer in Mesa

[wang-boyu]

What's the problem this feature will solve?

The current implementation of RasterLayer includes copies of some methods from mesa.space.Grid (see #120), making it difficult to maintain.

Describe the solution you'd like

A more related class in Mesa is its recent PropertyLayer (mesa/mesa#1898). RasterLayer could inherit from PropertyLayer with added geospatial capabilities.

Additional context

Might also be beneficial to have part of GeoSpace inherit from _PropertyGrid to manage multiple raster layers.

Some related past issues:

• Convenient methods in RasterLayer #91
• Cell aggregation API in raster layer #81

[EwoutH]

Agree on this! I don't have time to work on it, but I can provide guidance and review.

[wang-boyu]

Also need something similar to mesa/mesa#2336 for visualization.

[SongshGeo]

Hi, I'm happy to help with this issue.

I've browsed the PropertyLayer class in Mesa's latest codebase. I also found the Cell class under the experiment.cell_space module, which seems to be an experimental feature.

I don't know if they will be integrated with the Cell class in Mesa-Geo in the future. I believe Cell should be regarded as a stable basic unit of discrete space with more functionality. I mean, experimental Cell in the current Mesa codebase could be the direction. What do you think?

[wang-boyu]

Thanks for your interest on this!

I have to say that I'm not familiar with the experimental Cell and PropertyLayer features in Mesa. Perhaps it's better to have some help and advice from @EwoutH instead.

One thing to note though is that Mesa-Geo's current Cell in RasterLayer may not be exactly the same as the experimental Cell in Mesa, despite they share the same name (unfortunately). Here I used Cell to be an agent-like entity (i.e., with a step() function) in a RasterLayer, whereas the experimental Cell in Mesa looks like some kind of agent containers. One thing in common is that they both seem to be able to have properties.

Hope I'm not confusing you : )

[EwoutH]

@SongshGeo very cool!

We will stabilize the whole cell space, likely in Mesa 3.1. In the long term, we will remove the current spaces. For now, you can regard Cell as being stable, we likely won’t be changing it significantly.

In my (personal) vision, in the long term Mesa-geo will be integrated more tightly in Mesa. See mesa/mesa#2330. So I will support any changes to move in that direction.

You should probably also read this issue:

• Move propertylayer from DiscreteSpace to Grid mesa#2431

Let me know if you have any questions! If you want to chat directly, you can join our Matrix chat room.

[SongshGeo]

Thanks for your explanation, @EwoutH. Cool. I support the long-term integration of Mesa and Mesa-geo. But for now, I will mainly focus on changes to Mesa-geo.
I understand @wang-boyu 's point; currently, mesa-geo is just a simple instance with attributes. The experimental Cell in Mesa is similar to mine (see what I did in ABSESpy), as it serves as a container for Agents and can also store attributes.

I haven't had much time to examine the visualization part, but I'm happy to open a PR that modifies Mesa-geo using Cell and PropertyLayer from Mesa.

By the way, I joined the Matrix community a long time ago. Instant messaging sometimes causes me some stress, so I prefer to communicate here.

Re. the projects/mesa#2431 , I agree with what you said about using "GIS models" to imagine attributes as a "big cake". We can set multiple attributes for the same layer (i.e., a cell can have various attributes); however, agents do not need to move between different layers. We should use ideas similar to the Xarray package to manage selections between different layers based on coordinates.

What do you think?

[EwoutH]

If I understand you correctly we're thinking in the same direction. I imagine agents still having a single position according to a single CRS, but being able to fetch data from multiple layers (simultaneously), which might or might not have similar CRS.

Go ahead and start playing with potential solutions! Feel free to open a draft PR here early.

[SongshGeo]

Cool, that's exactly what I meant. It is good to know that we're in the same direction. I will do it this week.

[SongshGeo]

Hi, @wang-boyu and @EwoutH

I have made some preliminary refactoring of RasterLayer to showcase my ideas.

All previous methods can call the experimental APIs of Cell and PropertyLayer in this way. In other words, RasterLayer will combine both functionalities, encapsulated with geographic information. Given that the data attribute of PropertyLayer is implemented based on Numpy 2d arrays, array-style indexing in RasterLayer aligns better with GIS practices. For instance, we can have a property like this:

>>> layer.array_cells
array([[Cell((0, 3), []), Cell((1, 3), []), Cell((2, 3), [])],
       [Cell((0, 2), []), Cell((1, 2), []), Cell((2, 2), [])],
       [Cell((0, 1), []), Cell((1, 1), []), Cell((2, 1), [])],
       [Cell((0, 0), []), Cell((1, 0), []), Cell((2, 0), [])]],
      dtype=object)

For another example, add_property (i.e., previous apply_raster) could be:

    def add_property(
        self,
        data: np.ndarray | float | int | bool,
        attr_name: str,
        add_to_cells: bool = True,
    ) -> None:
        """Add a property layer to the grid."""
        if isinstance(data, np.ndarray):
            if data.shape != (self.height, self.width):
                raise ValueError(
                    f"Data shape does not match raster shape. "
                    f"Expected {(self.height, self.width)}, received {data.shape}."
                )
        else:
            data = np.full((self.height, self.width), data)
        property_layer = PropertyLayer(
            attr_name,
            self.width,
            self.height,
            default_value=np.nan,
        )
        # Would be better if `PropertyLayer` had a class method to create directly from array.
        property_layer.data = data
        self.grid.add_property_layer(property_layer, add_to_cells)

I haven't completed all function and test modifications yet; if you agree with this direction, I will continue to work on them.

[EwoutH]

Thanks!

One of the advantages of the current PropertyLayer is that it’s extremely fast, because almost all operations can be performed vectorized. If I’m correct, you now propose an array of cells. Will that retain the PropertyLayer’s performance?

From an API/implementation standpoint, I’m curious what Wang thinks.

@quaquel you might also be interested in this.