Master branch 
To install the latest stable release via PyPi:
python -m pip install mapactionpy_controller
To install a specific version for testing, see the relevant command line from here: https://pypi.org/project/mapactionpy-controller/#history
There are two key files, typically named cmf_description.json and event_description.json that need to be in the root of the crash move folder. Most command-line options require one or the other of these.
General help:
> mapchef --help
Verify the content of the default crash move folder (e.g. MXD Naming Convention, MXD Template Naming Convention, Layer Naming Convention and self-consistency of various configuration files.):
> mapchef defaultcmf --verify c:/path/to/default/crash/move/folder/cmf_description.json
Check the compliance with the Data Naming Convention.
mapchef gisdata --verify /path/to/current/cmf/2019gbr01/event_description.json
Create all maps in the cookbook file:
mapchef maps --build /path/to/current/cmf/2019gbr01/event_description.json
Create the map "MA001" from the cookbook file:
mapchef maps --build --map-number "MA001" /path/to/current/cmf/2019gbr01/event_description.json
Three classes are designed for reuse in other modules. For each of these, there is a corresponding json representation. There should not be any need for any additional code to touch these JSON files:
- MapRecipe : An object representing a recipe (as read from a json file).
This object may be manipulated by (e.g. the data_search tool, updates thedatasourcesfields ) - CrashMoveFolder : An object that describes the CrashMoveFolder and its contents. There should be no need to hardcode any path (absolute or relative) to anywhere in a crash move folder
- Event : This describes the real-world humanitarian event to which the Crash Move Folder corresponds.
(Note1:) The name Event matches the equivalent concept's naming on the Map & Data Repository (see https://github.com/mapaction/ckanext-mapactionevent). However, it is rather too generic in this context. A more descriptive name for this class would be helpful.
(Note2: in the MapExportTool, the information within the CrashMoveFolder and Event used to be encapsulated in the operational_config.xml file. This mixed state about the event/emergency and configuration about the local paths to and within the crash move folder. )
The naming_convention sub-module provides a framework for specifying a naming convention (such as for file or table). A naming convention is defined in a json configuration file and consists of:
- A regular expression with named groups.
- For each named group in the regex, details of a class that provides further validation of that value in that named group.
Examples of the naming convention config files are in the examples directory, including MapAction's DataNamingConvention, MXDNamingConvention and LayerfileNamingConvention.
DataNameConvention represents the convention itself. At its core is a regular expression. Each named group (clause) within the regex as additional validation implemented by a DataNameClause object. DataNameConvention has a dictionary of DataNameClause objects. A individual name is tested by using the .validate(data_name_str) method. If the data name does not match the regex the value None is returned. If the regex matches, a DataNameInstance object is returned, whether or not all of the clauses pass.
DataNameClause is an abstract class. Callers are unlikely to need to directly access this class or any concrete examples. Concrete examples are DataNameFreeTextClause and DataNameLookupClause. When the .validate(data_name_str) method is called on a DataNameConvention object, it will call .validate(clause_str) in each individual DataNameClause obj.
DataNameResult represents the result of a specific data name test and is returned by DataNameConvention.validate(). The .is_parsable property indicates whether or not the name could be parsed by the DataNameConvention's regex. The .is_valid property indicates whether or not all of the clauses validate. (.is_valid will always be False if .is_parsable is False). DataNameResult is a namedtuple.
The values for individual clauses can be directly accessed using dotted property notation (e.g. via members such as dnr.datatheme.Description or dnr.source.Organisation. Each individual clause will have its own .is_valid property (eg . dnr.datatheme.is_valid).
Example code:
dnc = DataNameConvention(path_to_dnc_json_definition)
# regex does not match
dnr = dnc.validate('abcde')
self.assertFalse(dnr.is_parsable)
# regex does matches, but some clauses fail lookup in csv file
dnr = dnc.validate(r'aaa_admn_ad3_py_s0_wfp_pp')
if dnr.is_valid:
print('the dataname is valid')
else:
print('the dataname is not valid')
# use the `_asdict()` method to loop through all clauses
for clause in dnr._asdict().values():
clause_details = dni.clause(clause)
if clause_details:
print('The extra information associated with clause name {} are {}'.format(clause, clause_details)
else:
print('The erroneous value for clause {} was {} '.format(clause, clause_details)
# Use the dnr object in template strings
print('The {dnr.datatheme.Description} data was generously supplied by {dnr.source.Organisation}, downloaded '
'from {dnr.source.url}'.format(dnr=dnr))
Output:
The erroneous value for clause `geoext` was `aaa`
Extra information associated with clause `scale`:
Description = Global mapping
Scale_range = ? 5 000 000
Extra information associated with clause `freetext`:
text = None
Extra information associated with clause `perm`:
Description = Data public - Products public
Extra information associated with clause `source`:
url =
Organisation = World Food Program
admn1PCode =
admn2Name =
admn2PCode =
admn1Name =
Extra information associated with clause `datacat`:
Description = Admin
Extra information associated with clause `geom`:
Description = Polygon / area
Extra information associated with clause `datatheme`:
Category = admn
Description = Administrative boundary (level 3)
The Administrative boundary (level 3) data generously supplied by the World Food Program, downloaded from https://www.wfp.org/.