Contributing to UrbanMapper¶

Welcome to the contributing guide for UrbanMapper! We are excited to collaborate on developing a tool for urban data analysis that is both accessible and powerful. This guide will help you set up your environment, add new components, and submit contributions. Whether you are fixing bugs, adding features, or improving documentation, your work is important!

Project Setup Guide¶

Prerequisites¶

• UrbanMapper requires Python 3.10 or higher.

• Use uv (recommended), conda, or venv to manage your project setup. Follow the steps below to install one of them.

  uv (Recommended)condavenv

  • To install uv, follow the instructions on the uv documentation.
  • If you don’t have Python 3.10 or higher / you prefer to be sure, you can install and pin it using uv:

    uv python install 3.10
    uv python pin 3.10
    

  • To install conda, follow the instructions on the conda documentation.
  • If you don’t have Python 3.10 or higher, you can create a new conda environment with the required version:

    conda create -n urbanmapper python=3.10
    conda activate urbanmapper
    

  • Ensure you have Python 3.10 or higher installed. You can check your Python version with:

    python3 --version
    

  • To create a virtual environment, use Python's built-in venv module:

    python3 -m venv urbanmapper-env
    source urbanmapper-env/bin/activate  # On macOS/Linux
    urbanmapper-env\Scripts\activate     # On Windows
    

Clone the Repo¶

git clone git@github.com:VIDA-NYU/UrbanMapper.git
cd UrbanMapper

Environment Setup¶

Get started by setting up your development environment. We recommend uv for its speed, but pip or conda work too. Choose one of the following options:

Config Note:¶

Check out config.yaml in urban_mapper/ for pipeline schemas and mixin mappings. It’s optional for basic setup but key for advanced tweaks.

Linting and Formatting with Ruff¶

We use ruff to keep the codebase clean and consistent. Run it before submitting changes.

Commands¶

• Check Issues:

  uv run ruff check
  

• Fix Formatting:

  uv run ruff check --fix
  

Pre-Commit Hooks¶

Pre-commit hooks enforce standards by running checks (like ruff) before commits.

Setup¶

1. Install:

   uv run pre-commit install
   

2. Test Manually (optional):

   uv run pre-commit run --all-files
   

How to Create New Components¶

UrbanMapper’s modular design makes extending it a breeze. Select the component type you want to add:

from urban_mapper.modules.loader.abc_loader import LoaderBase
import geopandas as gpd
import pandas as pd
from beartype import beartype

@beartype
class CSVLoader(LoaderBase):
    def load_data_from_file(self) -> gpd.GeoDataFrame:
        df = pd.read_csv(self.file_path)  #(1)
        # Convert to GeoDataFrame...
        return gdf

from urban_mapper.modules.urban_layer.abc_urban_layer import UrbanLayerBase
import geopandas as gpd
import osmnx as ox
from beartype import beartype

@beartype
class OSMNXStreets(UrbanLayerBase):
    def from_place(self, place_name: str, **kwargs) -> None:
        self.network = ox.graph_from_place(place_name, network_type="all")  # (1)
        self.layer = ox.graph_to_gdfs(self.network)[1].to_crs(self.coordinate_reference_system)

from urban_mapper.modules.imputer.abc_imputer import GeoImputerBase
import geopandas as gpd
from beartype import beartype

@beartype
class SimpleGeoImputer(GeoImputerBase):
    def _transform(self, input_geodataframe: gpd.GeoDataFrame, urban_layer) -> gpd.GeoDataFrame:
        # Impute logic here
        return input_geodataframe        def preview(rmat: s        r = "-> str::
s        r     return f"Imputer: Simpl:s        r     eGeoImputer\n  Lat: {self.la:titude_column}"

from urban_mapper.modules.filter.abc_filter import GeoFilterBase
import geopandas as gpd
from beartype import beartype

@beartype
class BoundingBoxFilter(GeoFilterBase):
    def _transform(self, input_geodataframe: gpd.GeoDataFrame, urban_layer) -> gpd.GeoDataFrame:
        minx, miny, maxx, maxy = urban_layer.get_layer_bounding_box()
        return input_geodataframe.cx[minx:maxx, miny:maxy]

from urban_mapper.modules.enricher.aggregator.abc_aggregator import BaseAggregator
import pandas as pd
from beartype import beartype

@beartype
class SumAggregator(BaseAggregator):
    def __init__(self, group_by_column: str, value_column: str):
        self.group_by_column = group_by_column
        self.value_column = value_column
    def _aggregate(self, input_dataframe: pd.DataFrame) -> pd.Series:
        return input_dataframe.groupby(self.group_by_column)[self.value_column].sum()

from urban_mapper.modules.visualiser.abc_visualiser import VisualiserBase
import geopandas as gpd
from beartype import beartype

@beartype
class StaticVisualiser(VisualiserBase):
    def _render(self, urban_layer_geodataframe: gpd.GeoDataFrame, columns: list, **kwargs):
        return urban_layer_geodataframe.plot(column=columns[0], legend=True, **kwargs).get_figure()

from urban_mapper.modules.pipeline_generator.abc_pipeline_generator import PipelineGeneratorBase
from beartype import beartype

@beartype
class GPT4OPipelineGenerator(PipelineGeneratorBase):
    def generate_pipeline(self, data_description: str) -> list:
        # AI-driven step generation
        return []

Pipeline Architecture¶

UrbanMapper’s pipeline flows like this:

Notation: (1) = exactly one instance, (0..*) = zero or more instances, (1..*) = one or more instances, (0, 1) = zero or one instance

Each step processes the data sequentially, transforming it from raw input to enriched urban insights. New components should slot into this sequence (see urban_mapper/pipeline/).

Generate Documentation¶

First and foremost, thank you for your contribution! To generate documentation, follow these steps:

1. UV Sync with DEV:

   uv sync --dev
   

2. Build Docs:

   ./build_docs.sh
   

3. Serve Docs:

   uv run mkdocs serve
   

4. Open in Browser: Localhost

Note: During documentation generation, ensure your environment is correctly set up. If you encounter issues with dependencies like 'cairo', refer to the Troubleshooting section. If you’ve added new packages, update the requirements files as described in Managing Dependencies.

Pull Requests and Rebasing¶

• Branch:

  git checkout -b feat/your-feature
  

• Commit:
  • Use Git Karma style (e.g., feat: add new loader).
• Rebase:

  git fetch origin
  git rebase origin/main
  

• Submit PR:
  • Push and open a PR against main.
  • Note: We highly encourage using Git Karma for commits/branches (e.g., feat/add-loader).

Common Git Commands¶

Thank You!¶

Thanks for contributing to UrbanMapper! Your efforts shape urban data analysis. Questions? Open an issue—we’ve got your back.

Enjoy mapping! 🌍

Troubleshooting¶

Handling 'cairo' Dependency Issues¶

Managing Dependencies¶

When you add a new package to the project, update the requirements files as follows:

1. Update requirements.txt –– Mainly for the people who are using pip or conda to install the dependencies.

   uv pip compile pyproject.toml -o requirements.txt
   

   Note that this step will vanish after the first release of UrbanMapper on PyPi. Meanwhile, if you want to know more about why we should do that and, why not UV is automatically doing that: https://github.com/astral-sh/uv/issues/6007. Happy reading 💪!

2. Update requirements-dev.txt –– Mainly for the newly generated documentation via ReadTheDoc.

   uv export --dev --no-hashes --no-header --no-annotate | awk '{print $1}' FS=' ;' > requirements-dev.txt
   

   Then, manually adjust for platform-specific dependencies. Locate lines like:

   pywin32==310
   pywin32-ctypes==0.2.3
   pywinpty==2.0.15
   

   Replace them with:

   pywin32==310; platform_system=="Windows"
   pywin32-ctypes==0.2.3; platform_system=="Windows"
   pywinpty==2.0.15; platform_system=="Windows"
   

   Note that this manual adjustment is needed for Read The Docs, which does not yet support uv. See the ongoing discussion at https://github.com/astral-sh/uv/issues/10074.

3. Commit and Push: After updating, commit and push the changes to the repository.