Documentationالدليل
Using Sudan Atlas in your codeاستخدام أطلس السودان في برامجك
One package for Python and one for JavaScript, with the same data and identical results. They match Sudanese place names written any way, in Arabic or English, to official P-codes, and give you the names and boundaries of Sudan's 18 states, the Abyei PCA area and 189 localities.
حزمة لبايثون وأخرى لجافاسكربت، تستخدمان البيانات نفسها وتعطيان النتائج نفسها. تتعرّف الحزمتان على أسماء الأماكن السودانية بالعربية أو الإنجليزية مهما اختلفت طريقة كتابتها، وتربطها بالرموز المكانية (P‑codes) الرسمية، وتوفّران أسماء وحدود ولايات السودان الـ18 ومنطقة أبيي، ومحلياته الـ189.
Installالتثبيت
pip install sudan-atlas # matcher, names and boundaries
pip install "sudan-atlas[geo]" # adds GeoDataFrames (needs geopandas)npm install sudan-atlasPython 3.11 or later; Node 18 or later, or any modern browser. The place names, spellings and boundary files ship inside the package, so Python and Node work offline; in a browser the boundary files are fetched when first needed.
تعمل الحزمة مع بايثون 3.11 أو أحدث، ومع Node 18 أو أحدث، وفي أي متصفح حديث. وتأتي الأسماء وصيغها وملفات الحدود مضمّنة فيها، فلا تحتاج في بايثون وNode إلى اتصال بالإنترنت؛ أما في المتصفح فتُجلب ملفات الحدود عند أول حاجة إليها.
Your first matchمطابقتك الأولى
Give match a name as it appears in your data. It returns the official place, its P-code, a score from 0 to 1 and how it was matched.
مرّر إلى الدالة match اسم المكان كما ورد في بياناتك، فتُرجع المكان الرسمي ورمزه المكاني، ودرجة تطابق بين 0 و1، وطريقة المطابقة.
from sudan_atlas import match
match("Elfasher", level=2)
# {'pcode': 'SD02114', 'name_en': 'Al Fasher', 'name_ar': 'الفاشر', 'level': 2,
# 'score': 1.0, 'method': 'exact', 'alternatives': [...]}
match("الفاشر")["pcode"] # 'SD02114'import { match } from "sudan-atlas";
match("Elfasher", { level: 2 });
// { pcode: "SD02114", name_en: "Al Fasher", name_ar: "الفاشر", level: 2,
// score: 1, method: "exact", alternatives: [...] }
match("الفاشر").pcode; // "SD02114"level is 1 for states and 2 for localities. Set it whenever you know it: "Kassala" is both a state and a locality, so match("Kassala") can't choose, while match("Kassala", level=1) returns SD11.
يحدّد level نوع المكان: 1 للولاية و2 للمحلية. ويُستحسن تحديده كلما عرفته، فاسم "Kassala" يُطلق على ولاية وعلى محلية في آن واحد، ولذلك لا تستطيع match("Kassala") الحسم بينهما، بينما تُرجع match("Kassala", level=1) الرمز SD11 مباشرة.
Your first mapخريطتك الأولى
Boundaries come as GeoJSON features in three detail levels: detailed, medium (the default) and light.
تأتي الحدود بصيغة GeoJSON وبثلاث درجات من التفصيل: detailed وmedium (الافتراضية) وlight.
from sudan_atlas import geo # needs the [geo] extra
localities = geo.localities("SD02") # North Darfur's 17 localities
ax = localities.plot(edgecolor="white", color="#2c7fb8")
localities.apply(lambda r: ax.annotate(r.name_en, r.geometry.representative_point().coords[0],
ha="center", fontsize=7), axis=1)import { getLocalities, getFeature } from "sudan-atlas";
import { geoConicEqualArea, geoPath } from "d3-geo";
const features = await Promise.all(getLocalities("SD02").map((p) => getFeature(p.pcode, "light")));
const collection = { type: "FeatureCollection", features };
const path = geoPath(geoConicEqualArea().parallels([9, 21]).rotate([-30, 0]).fitSize([600, 600], collection));
const svg = features.map((f) => `<path d="${path(f)}" fill="#2c7fb8" stroke="white"/>`).join("");Add P-codes to a spreadsheetإضافة الرموز المكانية إلى جدول
Match each distinct name once, then join the result back. Keep the method and score columns so you can review the uncertain rows.
طابِق كل اسم مختلف مرة واحدة فقط، ثم أعِد النتائج إلى جدولك. واحتفظ بعمودي طريقة المطابقة ودرجتها لتعود إلى الصفوف غير المؤكدة وتراجعها.
import pandas as pd
from sudan_atlas import match
df = pd.read_csv("sites.csv") # columns: state, locality, people
results = {
(loc, st): match(loc, state_hint=st, level=2)
for loc, st in df[["locality", "state"]].drop_duplicates().itertuples(index=False)
}
df["pcode"] = [results[k]["pcode"] for k in zip(df.locality, df.state)]
df["match_method"] = [results[k]["method"] for k in zip(df.locality, df.state)]
df["match_score"] = [results[k]["score"] for k in zip(df.locality, df.state)]
df[df.pcode.isna()] # rows to look at: no match, or a name that could be two placesimport { match } from "sudan-atlas";
const cache = new Map();
for (const row of rows) { // rows: [{ state, locality, people }, ...]
const key = `${row.locality}|${row.state}`;
if (!cache.has(key)) cache.set(key, match(row.locality, { stateHint: row.state, level: 2 }));
const r = cache.get(key);
Object.assign(row, { pcode: r.pcode, match_method: r.method, match_score: r.score });
}
const toReview = rows.filter((row) => row.pcode === null);Use a state hintتضييق البحث بالولاية
If your data has a state column, pass it. The matcher then looks only inside that state, which settles most look-alike names. The hint can be a P-code (SD15) or a state name in any spelling (Al Gezira, الجزيرة).
إذا كان في بياناتك عمود للولاية فمرّره إلى الدالة، فتبحث أداة المطابقة داخل تلك الولاية وحدها، وهذا يكفي لحسم معظم الأسماء المتشابهة. ويمكنك كتابة الولاية برمزها (SD15) أو باسمها بأي صيغة (Al Gezira، الجزيرة).
match("El Hasaheesa", state_hint="Al Gezira", level=2)["pcode"] # 'SD15034' (Al Hasahisa)
match("Nyala Shimal", state_hint="SD03", level=2)["pcode"] # 'SD03164'match("El Hasaheesa", { stateHint: "Al Gezira", level: 2 }).pcode; // "SD15034" (Al Hasahisa)
match("Nyala Shimal", { stateHint: "SD03", level: 2 }).pcode; // "SD03164"Handle uncertain namesحين لا تكون المطابقة مؤكدة
The matcher never guesses silently. When the best place scores below the threshold, or a second place scores almost as high, pcode is empty and alternatives lists the best three candidates for a person to choose from.
لا تخمّن أداة المطابقة أبدًا دون أن تخبرك. فإذا كانت درجة أفضل مكان أقل من الحد المطلوب، أو اقترب منه مكان آخر كثيرًا، تركت pcode فارغًا، ووضعت في alternatives أفضل ثلاثة مرشحين لتختار أنت من بينهم.
r = match("Gallabat")
r["pcode"], r["method"] # (None, 'ambiguous')
[(a["pcode"], a["name_en"]) for a in r["alternatives"]]
# [('SD12077', 'Basundah'), ('SD12083', 'Galabat Ash-Shargiah'), ('SD12078', 'Al Galabat Al Gharbyah - Kassab')]const r = match("Gallabat");
[r.pcode, r.method]; // [null, "ambiguous"]
r.alternatives.map((a) => [a.pcode, a.name_en]);
// [["SD12077", "Basundah"], ["SD12083", "Galabat Ash-Shargiah"], ["SD12078", "Al Galabat Al Gharbyah - Kassab"]]Gallabat town lies on the boundary between two localities, so both are offered. Decide with your own knowledge of the data, and store your decision so the next run doesn't ask again.
تقع بلدة القلابات على الحد بين محليتين، ولذلك تظهر المحليتان معًا. اختر بينهما بحسب معرفتك ببياناتك، واحفظ اختيارك حتى لا يتكرر السؤال في المرة القادمة.
Maps with GeoPandasرسم الخرائط بمكتبة GeoPandas
With the [geo] extra, geo.states() and geo.localities() return GeoDataFrames in EPSG:4326 with the columns pcode, name_en, name_ar, level, parent_pcode and geometry. Join your data on pcode, never on names.
عند تثبيت الإضافة [geo] تُرجع geo.states() وgeo.localities() جداول GeoDataFrame بنظام الإحداثيات EPSG:4326، فيها الأعمدة pcode وname_en وname_ar وlevel وparent_pcode وgeometry. اربط بياناتك بها عبر pcode، لا عبر الأسماء.
from sudan_atlas import geo
states = geo.states(resolution="light")
states.merge(my_totals, on="pcode", how="left").plot(column="people", legend=True, missing_kwds={"color": "#d4d4d8"})// GeoPandas is Python only. In JavaScript, use getFeature() with any mapping library
// (D3, Leaflet, MapLibre): every feature is plain GeoJSON with the same properties.Use it in a web pageالاستخدام في صفحة ويب
No build step needed: import the package from jsDelivr. Boundary files are fetched from the same place when you first ask for them.
لا تحتاج إلى أي أدوات بناء: استورد الحزمة مباشرة من jsDelivr، وستُجلب ملفات الحدود من هناك أيضًا عند أول طلب.
<script type="module">
import { match, getFeature } from "https://cdn.jsdelivr.net/npm/sudan-atlas@0.1/dist/index.js";
console.log(match("Omdurmaan", { level: 2 }).pcode); // "SD01006"
</script># In the browser, use the JavaScript package (switch the examples above to JavaScript).Serve the boundary files yourselfاستضافة ملفات الحدود على خادمك
In Node and Python the files are read from the package itself. In a browser they come from jsDelivr unless you copy the package's data/ folder to your own server and point the package at it.
في Node وبايثون تُقرأ ملفات الحدود من داخل الحزمة. أما في المتصفح فتُجلب من jsDelivr، إلا إذا نسخت مجلد data/ من الحزمة إلى خادمك ووجّهت الحزمة إليه.
import { setDataUrl, getFeature } from "sudan-atlas";
setDataUrl("/static/sudan-atlas/"); // your copy of node_modules/sudan-atlas/data/
const khartoum = await getFeature("SD01", "medium");# Not needed in Python: get_feature() reads the files bundled with the package.Without code: the map-makerدون برمجة: صانع الخرائط
The map-maker does all of this in your browser: open a CSV or Excel file, check the uncertain matches, then download a map and your file with P-codes added. Your file never leaves your device. It reads HXL hashtags (such as #adm2+name, #adm2+code and #affected) to pick the columns, uses P-code columns as they are, and keeps the hashtags in the file you download. A file with latitude and longitude columns can be placed by coordinates instead: each point is counted in the locality that contains it, using the detailed boundaries, and drawn on the map; points outside Sudan or without coordinates are listed, not dropped.
يؤدي صانع الخرائط كل ما سبق داخل متصفحك: افتح ملف CSV أو Excel، وراجع المطابقات غير المؤكدة، ثم نزّل الخريطة وملفك وقد أُضيفت إليه الرموز المكانية. ولا يغادر ملفك جهازك. ويقرأ صانع الخرائط وسوم HXL (مثل #adm2+name و#adm2+code و#affected) لاختيار الأعمدة، ويستخدم أعمدة الرموز المكانية كما هي، ويُبقي الوسوم في الملف الذي تنزّله. ويمكن تحديد مكان صفوف الملف الذي يحتوي على عمودين لخطَّي العرض والطول حسب الإحداثيات بدل الأسماء: فتُحسب كل نقطة في المحلية التي تقع فيها، اعتمادًا على الحدود المفصّلة، وتُرسم على الخريطة؛ أما النقاط الواقعة خارج السودان أو التي لا إحداثيات لها فتُذكر ولا تُسقط.
Connect an AI assistant (MCP)ربط مساعد ذكاء اصطناعي (MCP)
Sudan Atlas runs as a Model Context Protocol server, so assistants such as Claude can match place names and look up places for you. The address is https://atlas-sudan.vercel.app/api/mcp (Streamable HTTP). It is free, needs no key, only reads, and stores nothing you send.
يعمل أطلس السودان خادمًا لبروتوكول Model Context Protocol، فيستطيع مساعد مثل Claude أن يطابق أسماء الأماكن ويبحث عنها نيابة عنك. العنوان هو https://atlas-sudan.vercel.app/api/mcp (Streamable HTTP). الخدمة مجانية، ولا تحتاج إلى مفتاح، وتقرأ فقط، ولا تحفظ شيئًا مما ترسله.
# Claude Code
claude mcp add --transport http sudan-atlas https://atlas-sudan.vercel.app/api/mcp
# Other clients (mcp.json / claude_desktop_config.json, clients that support remote servers)
{ "mcpServers": { "sudan-atlas": { "type": "http", "url": "https://atlas-sudan.vercel.app/api/mcp" } } }// Claude Code
claude mcp add --transport http sudan-atlas https://atlas-sudan.vercel.app/api/mcp
// Other clients (mcp.json / claude_desktop_config.json, clients that support remote servers)
{ "mcpServers": { "sudan-atlas": { "type": "http", "url": "https://atlas-sudan.vercel.app/api/mcp" } } }| Toolالأداة | What it doesما تفعله |
|---|---|
match_place_name | One name to its P-code, with score, method and alternatives (optional state hint and level).اسم واحد إلى رمزه المكاني، مع الدرجة والطريقة والبدائل (مع تلميح اختياري بالولاية والمستوى). |
match_place_names | Up to 1,000 names at once, in order.حتى 1,000 اسم دفعة واحدة، بالترتيب. |
search_places | Find states and localities by part of a name.البحث عن الولايات والمحليات بجزء من الاسم. |
get_place | Names, parent state, localities, area and estimated population for a P-code.الأسماء والولاية والمحليات والمساحة وعدد السكان المقدَّر لرمز مكاني. |
list_places | All states, or the localities of the country or of one state.كل الولايات، أو محليات السودان كله أو محليات ولاية واحدة. |
get_boundary | A boundary as GeoJSON (light or medium detail).حدود مكان بصيغة GeoJSON (تفصيل خفيف أو متوسط). |
Like the packages, the server never guesses silently: when a name could be two places it returns the candidates, and the assistant is told to ask you.
ومثل الحزم، لا يخمّن الخادم أبدًا دون أن يخبرك: إذا احتمل الاسم مكانين أعاد المرشحين، ويُطلب من المساعد أن يسألك.
Privacy. Unlike the map-maker, which works entirely in your browser, the MCP server runs on our server: the names your assistant sends are processed there to answer the request, and are not stored or logged. Your assistant's own provider sees them too, under its own terms. Each address may make 60 requests a minute.
الخصوصية. صانع الخرائط يعمل كله داخل متصفحك، أما خادم MCP فيعمل على خادمنا: تُعالَج الأسماء التي يرسلها مساعدك هناك للإجابة عن الطلب، ولا تُحفظ ولا تُسجَّل. ويطّلع عليها كذلك مزوّد المساعد نفسه، وفق شروطه. ويُسمح لكل عنوان بـ60 طلبًا في الدقيقة.
Reference:المرجع: match()
match(name: str, state_hint: str | None = None, level: int | None = None) -> dictmatch(name: string, options?: { stateHint?: string | null; level?: 1 | 2 | null }): MatchResult| Fieldالحقل | Meaningالمعنى |
|---|---|
pcode | The P-code of the match, or empty (None / null) when there is no confident answer.الرمز المكاني للمكان المطابق، أو قيمة فارغة (None / null) إذا لم تكن هناك إجابة مؤكدة. |
name_en, name_ar, level | The official English and Arabic names and the level (1 state, 2 locality) of the match.الاسم الرسمي بالإنجليزية والعربية، ومستوى المكان (1 للولاية، 2 للمحلية). |
score | Similarity of the best candidate, from 0 to 1, rounded to four decimals.مدى تشابه أفضل مرشح، بين 0 و1، مقرّبًا إلى أربع خانات عشرية. |
method | exact (an official name), variant (a known spelling), fuzzy (a close spelling), ambiguous (two places too close to call) or none (nothing close enough).exact (الاسم الرسمي)، أو variant (صيغة معروفة للاسم)، أو fuzzy (كتابة قريبة)، أو ambiguous (مكانان متقاربان يتعذّر الحسم بينهما)، أو none (لا يوجد تشابه كافٍ). |
alternatives | The next best candidates (up to three), each with pcode, name_en, name_ar, level and score.المرشحون التالون في الترتيب (ثلاثة على الأكثر)، ولكل منهم pcode وname_en وname_ar وlevel وscore. |
Reference:المرجع: Matcher
match() uses a shared matcher with the default settings. Create your own to change them.
تستخدم match() أداة مطابقة مشتركة بالإعدادات الافتراضية، ويمكنك إنشاء أداتك الخاصة إذا أردت تغييرها.
from sudan_atlas import Matcher
strict = Matcher(threshold=0.9, margin=0.08)
strict.match("Kornoi", state_hint="North Darfur", level=2)import { Matcher } from "sudan-atlas";
const strict = new Matcher(undefined, { threshold: 0.9, margin: 0.08 });
strict.match("Kornoi", { stateHint: "North Darfur", level: 2 });threshold (default 0.82) is the lowest score accepted as a match. margin (default 0.05) is how far ahead of the second place the best candidate must be; closer than that, the result is ambiguous.
threshold (القيمة الافتراضية 0.82) هي أدنى درجة تُقبل بها المطابقة. وmargin (القيمة الافتراضية 0.05) هي أقل فارق مقبول بين أفضل مرشح والذي يليه؛ فإن كان الفارق أصغر كانت النتيجة ambiguous.
Reference: states and localitiesالمرجع: الولايات والمحليات
| Python | JavaScript | Returnsما تُرجعه |
|---|---|---|
get_states() | getStates() | The 19 admin-1 units (18 states and the Abyei PCA area), sorted by P-code.وحدات المستوى الإداري الأول الـ19 (18 ولاية ومنطقة أبيي)، مرتبة حسب الرمز. |
get_localities(state_pcode=None) | getLocalities(statePcode?) | All 189 localities, or those of one state.المحليات الـ189 كلها، أو محليات ولاية واحدة. |
| – | getPlace(pcode) | One place by P-code, or undefined.مكان واحد حسب رمزه، أو undefined إن لم يوجد. |
Each place has pcode, name_en, name_ar, level, parent_pcode (SD for states) and point, a [longitude, latitude] inside the place that is good for a label.
يحمل كل مكان الحقول pcode وname_en وname_ar وlevel وparent_pcode (وقيمته SD للولايات)، إضافة إلى point: إحداثيات [longitude, latitude] لنقطة داخل المكان تصلح لكتابة اسمه على الخريطة.
get_states()[0]
# {'pcode': 'SD01', 'name_en': 'Khartoum', 'name_ar': 'الخرطوم', 'level': 1,
# 'parent_pcode': 'SD', 'point': [33.1352, 15.915]}getStates()[0];
// { pcode: "SD01", name_en: "Khartoum", name_ar: "الخرطوم", level: 1,
// parent_pcode: "SD", point: [33.1352, 15.915] }Reference: boundariesالمرجع: الحدود
| Python | JavaScript | Returnsما تُرجعه |
|---|---|---|
get_feature(pcode, resolution="medium") | await getFeature(pcode, resolution = "medium") | A GeoJSON Feature with the place's properties.معلم GeoJSON (Feature) يحمل خصائص المكان. |
geo.states(resolution="medium") | – | GeoDataFrame of the 18 states and the Abyei PCA area (needs [geo]).جدول GeoDataFrame بالولايات الـ18 ومنطقة أبيي (يتطلب [geo]). |
geo.localities(state_pcode=None, resolution="medium") | – | GeoDataFrame of localities (needs [geo]).جدول GeoDataFrame بالمحليات (يتطلب [geo]). |
| – | setDataUrl(url) | Load boundary files from your own address (browser).تحميل ملفات الحدود من عنوان تحدده أنت (في المتصفح). |
resolution is detailed (the COD-AB geometry), medium or light (simplified for web maps, with shared borders kept intact).
يأخذ resolution إحدى ثلاث قيم: detailed (حدود COD-AB الأصلية)، أو medium أو light (نسختان مبسّطتان لخرائط الويب تحافظان على تطابق الحدود المشتركة).
Reference: P-codesالمرجع: الرموز المكانية
P-codes are the official codes from OCHA's Common Operational Datasets. SD is Sudan; a state adds two digits (SD15, Aj Jazirah); a locality adds three more (SD15034, Al Hasahisa). Join datasets on P-codes, never on names: names have many spellings, P-codes have one.
الرموز المكانية (P‑codes) هي الرموز الرسمية في مجموعات البيانات التشغيلية المشتركة التي يصدرها أوتشا. يرمز SD إلى السودان، ويضيف رمز الولاية رقمين (SD15 لولاية الجزيرة)، ويضيف رمز المحلية ثلاثة أرقام أخرى (SD15034 لمحلية الحصاحيصا). اربط بياناتك بالرموز لا بالأسماء: فللاسم صيغ كثيرة، أما الرمز فواحد.
Reference: data filesالمرجع: ملفات البيانات
The same files are in both packages and in the repository's data/ folder, and on jsDelivr under https://cdn.jsdelivr.net/npm/sudan-atlas@0.1/data/.
تجد الملفات نفسها في الحزمتين، وفي مجلد data/ في المستودع، وعلى jsDelivr في العنوان https://cdn.jsdelivr.net/npm/sudan-atlas@0.1/data/.
| Pathالمسار | Contentsالمحتوى |
|---|---|
boundaries/{detailed|medium|light}/adm{1|2}.geojson | States (adm1) and localities (adm2) as GeoJSON, EPSG:4326.الولايات (adm1) والمحليات (adm2) بصيغة GeoJSON وبنظام الإحداثيات EPSG:4326. |
boundaries/{detailed|medium|light}/adm{1|2}.topojson | The same as TopoJSON, smaller for the web.المحتوى نفسه بصيغة TopoJSON، وهي أخف حجمًا على الويب. |
places.json | The 208 places with names, levels, parents and label points.الأماكن الـ208 بأسمائها ومستوياتها والوحدات التي تتبعها، ونقاط كتابة أسمائها على الخريطة. |
variants.json, variants_osm.json | Known spellings of each place, with their sources (the OpenStreetMap ones under the ODbL).الصيغ المعروفة لاسم كل مكان ومصادرها (صيغ OpenStreetMap برخصة ODbL). |
normalisation.json | The rules that turn a name into a matching key, shared by both packages.القواعد التي يتحوّل بها الاسم إلى مفتاح للمطابقة، وتشترك فيها الحزمتان. |
Reference: versions and constantsالمرجع: الإصدارات والثوابت
| Python | JavaScript | Valueالقيمة |
|---|---|---|
sudan_atlas.__version__ | VERSION | The package version (0.1.3).إصدار الحزمة (0.1.3). |
DATA_VERSION | DATA_VERSION | The data release (2026.1).إصدار البيانات (2026.1). |
RESOLUTIONS | RESOLUTIONS | detailed, medium, light. |
| – | DEFAULT_THRESHOLD, DEFAULT_MARGIN | 0.82 and 0.05.0.82 و0.05. |
How matching worksكيف تعمل المطابقة
- Normalise. Both the input and every known name become a matching key: Arabic letter forms are unified (أ إ آ → ا, ة → ه, ى → ي), diacritics and articles (Al-, El-, ال) are set aside, common transliteration differences are merged (ou/u, ei/ai), and words such as "locality" or "محلية" are dropped.
- Exact. The key is compared with the official English and Arabic names of every place.
- Known spellings. Then with more than a thousand reviewed spellings gathered from GeoNames, Wikidata, OpenStreetMap and humanitarian datasets.
- Fuzzy. Then with every name by similarity, which catches typos and new spellings.
- Decide. The best candidate is accepted only if it scores at least 0.82 and is at least 0.05 ahead of the next place. Otherwise you get the candidates and the decision is yours.
- التوحيد. يُحوَّل الاسم المُدخل، وكل اسم معروف، إلى مفتاح موحّد للمطابقة: تُوحَّد أشكال الحروف العربية (أ إ آ ← ا، ة ← ه، ى ← ي)، وتُتجاهل الحركات وأداة التعريف (Al-، El-، ال)، وتُعامل الفروق الشائعة في كتابة الأسماء بالحروف اللاتينية معاملة واحدة (ou/u، ei/ai)، وتُحذف كلمات مثل "locality" و"محلية".
- المطابقة التامة. يُقارن المفتاح أولًا بالاسمين الرسميين العربي والإنجليزي لكل مكان.
- الصيغ المعروفة. ثم بأكثر من ألف صيغة مراجَعة، جُمعت من GeoNames وويكي بيانات وOpenStreetMap ومن مجموعات البيانات الإنسانية.
- المطابقة التقريبية. ثم بجميع الأسماء حسب درجة التشابه، فتُلتقط الأخطاء الإملائية والصيغ الجديدة.
- القرار. لا يُقبل أفضل مرشح إلا إذا بلغت درجته 0.82 على الأقل، وتفوّق على المكان التالي بفارق 0.05 على الأقل. وإلا عُرض عليك المرشحون، والقرار لك.
The Python and JavaScript matchers share the same rules file and are tested against the same expected results, so they return identical answers.
تعتمد أداتا المطابقة في بايثون وجافاسكربت على ملف القواعد نفسه، وتُختبران على النتائج المتوقعة نفسها، ولذلك تعطيان الإجابة نفسها دائمًا.
How accurate it isما مدى دقته؟
We tested the matcher on 299 place names copied as written from eight public datasets on HDX: refugee sites (UNHCR), people reached and who does what where (OCHA), displacement (IOM DTM), food insecurity (IPC), schools, floods and population tables. 253 of them should match a state or locality. The other 46 should match nothing: camps and villages, names shared by several places, and stray header and total rows. With the state given as a hint, as most humanitarian spreadsheets allow:
اختبرنا أداة المطابقة على 299 اسم مكان، نُقلت كما كُتبت من ثماني مجموعات بيانات عامة على منصة HDX: مواقع اللاجئين (المفوضية)، والمستفيدون ومن يعمل أين (أوتشا)، والنزوح (مصفوفة تتبّع النزوح التابعة للمنظمة الدولية للهجرة)، وانعدام الأمن الغذائي (التصنيف المرحلي المتكامل)، والمدارس، والفيضانات، وجداول السكان. من هذه الأسماء 253 يجب أن تُربط بولاية أو محلية، و46 يجب ألا تُربط بشيء: مخيمات وقرى، وأسماء تشترك فيها عدة أماكن، وصفوف عناوين ومجاميع وردت في الجداول. وحين تُذكر الولاية تلميحًا، كما تسمح أغلب الجداول الإنسانية، كانت النتائج:
- 94.9% of the 253 matched to the right place first time
- 99.6% (252 of 253) had the right place among the top three
- 0 of 299 matched to a wrong place on this set: when it wasn't sure, it asked (13 names)
- 94.9% من الأسماء الـ253 رُبطت بمكانها الصحيح مباشرة
- 99.6% (252 من 253) كان مكانها الصحيح بين أول ثلاثة مرشحين
- لا اسم من الـ299 رُبط بمكان خاطئ في هذا الاختبار: حين لم تكن الأداة متأكدة سألت (13 اسمًا)
What these figures don't show. The threshold (0.82) was chosen on this same set of names, so the results describe this set and are not an independent test: on new data the matcher will make mistakes, wrong matches included. Without a state hint it is right first time for 85.0% and names a wrong place for 2.3% of the names (7 of 299), so give the state whenever you have it. None of the test names was added to the matcher's spellings by hand; 47 are spellings it already knew from GeoNames, Wikidata, COD-AB or OpenStreetMap. If you find a wrong match, please report it on GitHub.
ما لا تقوله هذه الأرقام. اختيرت عتبة القبول (0.82) على هذه الأسماء نفسها، فالنتائج تصف هذا الاختبار وليست تقييمًا مستقلًا، وستخطئ الأداة في بيانات جديدة، ومن ذلك أن تربط اسمًا بمكان خاطئ. ومن دون ذكر الولاية تصيب الأداة من أول مرة في 85.0% من الأسماء، وتربط 2.3% منها بمكان خاطئ (7 من 299)، فاذكر الولاية كلما عرفتها. لم يُضَف أيٌّ من أسماء الاختبار يدويًا إلى صيغ الأداة، و47 منها صيغ كانت تعرفها مسبقًا من GeoNames وويكي بيانات وCOD-AB وOpenStreetMap. وإن وجدت مطابقة خاطئة فنرجو أن تبلغنا بها على GitHub.
The full evaluation, with every failure, is in MATCHER_EVALUATION.md, and the names themselves are in match_cases.csv.
تفاصيل التقييم كاملة، مع كل حالة أخطأت فيها الأداة، في MATCHER_EVALUATION.md، والأسماء نفسها في match_cases.csv (بالإنجليزية).
Sources and licencesالمصادر والرخص
Boundaries and P-codes: OCHA's Common Operational Dataset for Sudan (COD-AB, version v03), CC BY 3.0 IGO. Spellings: GeoNames (CC BY 4.0), Wikidata (CC0) and OpenStreetMap (ODbL, kept in a separate file). Code: MIT. Sudan Atlas's own data: CC BY 4.0. Boundaries do not imply any opinion on the legal status of any territory. More on the data and sources page. To cite Sudan Atlas: doi:10.5281/zenodo.24191932.
الحدود والرموز المكانية: مجموعة COD-AB للسودان (الإصدار v03) من أوتشا، برخصة CC BY 3.0 IGO. صيغ الأسماء: GeoNames (CC BY 4.0) وويكي بيانات (CC0) وOpenStreetMap (ODbL، في ملف مستقل). البرمجيات: MIT. بيانات أطلس السودان: CC BY 4.0. ولا يعبّر رسم الحدود عن أي موقف من الوضع القانوني لأي إقليم. ولمزيد من التفاصيل، راجع صفحة البيانات والمصادر. وللاستشهاد بأطلس السودان: doi:10.5281/zenodo.24191932.