The Study Region is a multipolygon that refers to all areas within which new Marine Protected Areas may be proposed. Often this is based on a combination of factors including the administrative jurisdiction of the agency implementing the MPAs, biogeography, and the logistics of running a design process across a wide area. For example, the Marine Life Protection Act Initiative proceeded with establishing MPAs by breaking up the state of California into 5 study regions. Each study region was addressed in series, and the study region was limited to state waters because the process was backed by state legislation.
The Study Region is the fundamental unit that defines a Madrona installation. To support the California MLPA Initiative, 5 instances of Madrona would need to be built and run. Madrona clips all Marine Protected Areas to the Study Region boundaries. It also uses the Study Region bounds to determine the default extent of the map.
The madrona.layers project includes an initial_data fixture that will setup an example Study Region when the database is first setup using the syncdb management command.
Changing the Study Region boundaries on a deployed application presents many problems.
- All Marine Protected Areas affected by the Study Region geometry changes will need to be re-clipped.
- Any reports associated with those MPAs will need to be regenerated.
- Some cached data structures such as the network graph used for calculating Array spacing will need to be regenerated.
Madrona is designed to make this process work as smoothly as possible, but the steps to change a Study Region must be followed exactly to avoid any problems.
Every project should define a study region if the ClipToStudyRegion manipulator will be used. The study region is a (multi)polygon shape which defines where shapes can be created. If the ClipToStudyRegion manipulator is used on a feature, new shapes are clipped to this boundary. It is highly recomended to create/choose your study region with great consideration up front; changing the study region at a later date is MUCH more complicated as all the user shapes will need to be re-clipped. Fortunately Madrona stores the original geometry as well as the “manipulated” version so such clipping will never destroy the original digitized shape.
To create a new study region a shapefile (or other LayerMapping compatible datasource) that contains a single multipolygon representing the Study Region bounds is needed. One way to create such a file would be to use a tool like QGis to export the current Study Region in the database to a shapefile and modify the boundaries as needed.
It is highly recomended that the study region shapefile be created in the same spatial reference system as the application SRID.
Note
Do not modify the Study Region in-place in the database. Modifications to a Study Region geometry will not be detected by the application this way, leaving Marine Protected Areas clipped to the wrong shape in the system. Always use the management commands.
Once a shapefile is ready and sitting on the server, the next step is to use the create_study_region management command.
$ python manage.py create_study_region ~/Desktop/study_region2.shp
Study region created: Sample Study Region - Southern California MLPA, primary key = 18
To switch to this study region, you will need to run 'python manage.py change_study_region 18'
If the study region shapefile does not contain a field named ‘name’, you can specify the name on the command line using the –name option.
$ python manage.py create_study_region --name "new study region" ~/Desktop/study_region2.shp
Study region created: new study region, primary key = 3
To switch to this study region, you will need to run 'python manage.py change_study_region 3'
The Study Region should then be accessible via the admin tool.
Changing the Study Region on a live application is not recommended. Either shutdown the server or put Madrona into Maintenance Mode.
Currently, the change_study_region command simply sets specified region as the current active study region. It does not do any re-clipping, re-configuration, etc. If run on a working installation, this will require a lot more manual work. However, it is sufficient to initally set up the study region for a brand new project.
$ python manage.py change_study_region.py 18
Note
The following steps are not implemented, but this documentation can serve as a specification for the future tools.
The change_study_region command will walk one through the process of changing from one study region to another. The primary key of an existing study region is the only argument needed to start.
$ python manage.py change_study_region.py 18
This process should not be done when the Madrona application is publicly
accessible. Please shutdown the server or redirect users to a maintenance page
Type 'yes' to continue, or 'no' to cancel: yes
calculating difference between the specified study region and the one currently active...
current study region: Sample Study Region - Southern California MLPA
area: 6088792658.45
new study region: Sample Study Region - Southern California MLPA
area: 6087778804.81
difference between study regions:
area: 1013853.63735
sections: 1
User Shapes Affected:
Mpas: 12
Are you sure you would like the switch to the new study region?
Type 'yes' to continue, or 'no' to cancel: yes
Changing to a new study region means re-clipping and processing Marine Protected Area geometries, and will take a significant amount of time.
Processing shapes:
|--------------------------------------- | 84% | ETA: 00:00:12
When the process is over there is the option to send a summary email to users who have had shapes modified by the process.
Done processing shapes.
Would you like to send an email notifying users that their shapes have changed?
Type 'yes' or 'no': yes
sending emails...
This process is complete. You can now resume public access to the application.
Restart the server or take the application out of Maintenance Mode.
There are use cases where it makes sense to have integration across multiple study regions. For example, in California it makes sense for work in the southern study region to be informed by work in the central one. It would be desirable to report on the Marine Protected Areas in multiple study regions as a network. Such integration cannot happen within a single app, and will need to be supported by webservices. The actual implementation details of these services have yet to be worked out.