Performance benchmarks:

Thanks for this PR. Can you ensure you get to 100% test code coverage, or at least as close as is reasonable? You can check the coverage report to see which parts are not yet covered by tests.

@EwoutH, you started the original issue. What do you think? Do you prefer overloading create_agent, or do you prefer a separate method from_dataframe as done here and as argued for by several people, including me, in the original issue.

Performance benchmarks:

@quaquel Got the 100% test code coverage. Also, interesting performance benchmark results.
Any thoughts here?

The benchmark results make no sense. Nothing here touches code that is used in the benchmarks. But we have been seeing funky benchmark results a lot lately. I'll try to take a closer look at the PR itself soonish.

I doo agree with dropping **args but keeping **kwargs

If we allow series as per #3186, allowing kwargs here is redundant.

I see the point about redundancy with a Series-capable create_agents, but I think keeping **kwargs in from_dataframe is worth it for Data Integrity and Ergonomics:

• The DataFrame often represents the 'Raw Population' (observed data like age, income), while the extra **kwargs represent 'Simulation State' (initial model parameters like is_infected=False, energy=100). Forcing users to inject simulation constants into their raw dataframes just to instantiate agents feels like 'polluting' the data layer.
• Adding a column of constant scalars to a large DataFrame (e.g., 1M rows) is an $O(N)$ operation that consumes extra memory. Passing a single scalar via **kwargs is $O(1)$ and avoids making pandas allocate memory for a column that would be immediately discarded after iteration.
• Users coming from data-heavy workflows (HuggingFace, Ray, etc.) will look for .from_dataframe() specifically because they have a table and want to map it. If that method lacks the ability to add a simple constant override, it feels 'broken' compared to other Pythonic factory methods.

Essentially, create_agents is for when you are building a population by columns, and from_dataframe is for when you are building a population from a table. Both should be first-class citizens with simple override support.

Also, as stated by @EwoutH in #3186 (comment) should I split this into 2 seperate PRs?

I agree.

While I would prefer 2 PRs, keeping it in one is also fine since the create agent changes are small.

Ok, I am fine with adding kwargs back to from_dataframe, but let's then restrict it to non-sequence data only.

Agreed.

Do we have any idea how this will handle non-Pandas tables? Like NumPy arrays or Polars dataframes?

Do we have any idea how this will handle non-Pandas tables? Like NumPy arrays or Polars dataframes?

Numpy does not have to_dict, so it will fail. Polars has a to_dict, but with different keyword arguments. Again it will fail.

I can add Duck-Typing for Polars support.

Something like:

# In from_dataframe
if hasattr(df, "to_dict"): # Pandas
    records = df.to_dict(orient="records")
elif hasattr(df, "to_dicts"): # Polars
    records = df.to_dicts()
else:
    raise TypeError("Object must be a Pandas or Polars DataFrame.")

But this might require slightly more complex error handling if to_dict exists but doesn't support the orient kwarg in some other library.

I suggest we just handle pandas for now and move the polars conversation more broadly to the mesa 4 discussion